File : a-strunb.ads
1 ------------------------------------------------------------------------------
2 -- --
3 -- GNAT RUN-TIME COMPONENTS --
4 -- --
5 -- A D A . S T R I N G S . U N B O U N D E D --
6 -- --
7 -- S p e c --
8 -- --
9 -- Copyright (C) 1992-2011, Free Software Foundation, Inc. --
10 -- --
11 -- This specification is derived from the Ada Reference Manual for use with --
12 -- GNAT. The copyright notice above, and the license provisions that follow --
13 -- apply solely to the contents of the part following the private keyword. --
14 -- --
15 -- GNAT is free software; you can redistribute it and/or modify it under --
16 -- terms of the GNU General Public License as published by the Free Soft- --
17 -- ware Foundation; either version 3, or (at your option) any later ver- --
18 -- sion. GNAT is distributed in the hope that it will be useful, but WITH- --
19 -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
20 -- or FITNESS FOR A PARTICULAR PURPOSE. --
21 -- --
22 -- --
23 -- --
24 -- --
25 -- --
26 -- You should have received a copy of the GNU General Public License and --
27 -- a copy of the GCC Runtime Library Exception along with this program; --
28 -- see the files COPYING3 and COPYING.RUNTIME respectively. If not, see --
29 -- <http://www.gnu.org/licenses/>. --
30 -- --
31 -- GNAT was originally developed by the GNAT team at New York University. --
32 -- Extensive contributions were provided by Ada Core Technologies Inc. --
33 -- --
34 ------------------------------------------------------------------------------
35
36 with Ada.Strings.Maps;
37 with Ada.Finalization;
38
39 package Ada.Strings.Unbounded is
40 pragma Preelaborate;
41
42 type Unbounded_String is private;
43 pragma Preelaborable_Initialization (Unbounded_String);
44
45 Null_Unbounded_String : constant Unbounded_String;
46
47 function Length (Source : Unbounded_String) return Natural;
48
49 type String_Access is access all String;
50
51 procedure Free (X : in out String_Access);
52
53 --------------------------------------------------------
54 -- Conversion, Concatenation, and Selection Functions --
55 --------------------------------------------------------
56
57 function To_Unbounded_String
58 (Source : String) return Unbounded_String;
59
60 function To_Unbounded_String
61 (Length : Natural) return Unbounded_String;
62
63 function To_String (Source : Unbounded_String) return String;
64
65 procedure Set_Unbounded_String
66 (Target : out Unbounded_String;
67 Source : String);
68 pragma Ada_05 (Set_Unbounded_String);
69
70 procedure Append
71 (Source : in out Unbounded_String;
72 New_Item : Unbounded_String);
73
74 procedure Append
75 (Source : in out Unbounded_String;
76 New_Item : String);
77
78 procedure Append
79 (Source : in out Unbounded_String;
80 New_Item : Character);
81
82 function "&"
83 (Left : Unbounded_String;
84 Right : Unbounded_String) return Unbounded_String;
85
86 function "&"
87 (Left : Unbounded_String;
88 Right : String) return Unbounded_String;
89
90 function "&"
91 (Left : String;
92 Right : Unbounded_String) return Unbounded_String;
93
94 function "&"
95 (Left : Unbounded_String;
96 Right : Character) return Unbounded_String;
97
98 function "&"
99 (Left : Character;
100 Right : Unbounded_String) return Unbounded_String;
101
102 function Element
103 (Source : Unbounded_String;
104 Index : Positive) return Character;
105
106 procedure Replace_Element
107 (Source : in out Unbounded_String;
108 Index : Positive;
109 By : Character);
110
111 function Slice
112 (Source : Unbounded_String;
113 Low : Positive;
114 High : Natural) return String;
115
116 function Unbounded_Slice
117 (Source : Unbounded_String;
118 Low : Positive;
119 High : Natural) return Unbounded_String;
120 pragma Ada_05 (Unbounded_Slice);
121
122 procedure Unbounded_Slice
123 (Source : Unbounded_String;
124 Target : out Unbounded_String;
125 Low : Positive;
126 High : Natural);
127 pragma Ada_05 (Unbounded_Slice);
128
129 function "="
130 (Left : Unbounded_String;
131 Right : Unbounded_String) return Boolean;
132
133 function "="
134 (Left : Unbounded_String;
135 Right : String) return Boolean;
136
137 function "="
138 (Left : String;
139 Right : Unbounded_String) return Boolean;
140
141 function "<"
142 (Left : Unbounded_String;
143 Right : Unbounded_String) return Boolean;
144
145 function "<"
146 (Left : Unbounded_String;
147 Right : String) return Boolean;
148
149 function "<"
150 (Left : String;
151 Right : Unbounded_String) return Boolean;
152
153 function "<="
154 (Left : Unbounded_String;
155 Right : Unbounded_String) return Boolean;
156
157 function "<="
158 (Left : Unbounded_String;
159 Right : String) return Boolean;
160
161 function "<="
162 (Left : String;
163 Right : Unbounded_String) return Boolean;
164
165 function ">"
166 (Left : Unbounded_String;
167 Right : Unbounded_String) return Boolean;
168
169 function ">"
170 (Left : Unbounded_String;
171 Right : String) return Boolean;
172
173 function ">"
174 (Left : String;
175 Right : Unbounded_String) return Boolean;
176
177 function ">="
178 (Left : Unbounded_String;
179 Right : Unbounded_String) return Boolean;
180
181 function ">="
182 (Left : Unbounded_String;
183 Right : String) return Boolean;
184
185 function ">="
186 (Left : String;
187 Right : Unbounded_String) return Boolean;
188
189 ------------------------
190 -- Search Subprograms --
191 ------------------------
192
193 function Index
194 (Source : Unbounded_String;
195 Pattern : String;
196 Going : Direction := Forward;
197 Mapping : Maps.Character_Mapping := Maps.Identity) return Natural;
198
199 function Index
200 (Source : Unbounded_String;
201 Pattern : String;
202 Going : Direction := Forward;
203 Mapping : Maps.Character_Mapping_Function) return Natural;
204
205 function Index
206 (Source : Unbounded_String;
207 Set : Maps.Character_Set;
208 Test : Membership := Inside;
209 Going : Direction := Forward) return Natural;
210
211 function Index
212 (Source : Unbounded_String;
213 Pattern : String;
214 From : Positive;
215 Going : Direction := Forward;
216 Mapping : Maps.Character_Mapping := Maps.Identity) return Natural;
217 pragma Ada_05 (Index);
218
219 function Index
220 (Source : Unbounded_String;
221 Pattern : String;
222 From : Positive;
223 Going : Direction := Forward;
224 Mapping : Maps.Character_Mapping_Function) return Natural;
225 pragma Ada_05 (Index);
226
227 function Index
228 (Source : Unbounded_String;
229 Set : Maps.Character_Set;
230 From : Positive;
231 Test : Membership := Inside;
232 Going : Direction := Forward) return Natural;
233 pragma Ada_05 (Index);
234
235 function Index_Non_Blank
236 (Source : Unbounded_String;
237 Going : Direction := Forward) return Natural;
238
239 function Index_Non_Blank
240 (Source : Unbounded_String;
241 From : Positive;
242 Going : Direction := Forward) return Natural;
243 pragma Ada_05 (Index_Non_Blank);
244
245 function Count
246 (Source : Unbounded_String;
247 Pattern : String;
248 Mapping : Maps.Character_Mapping := Maps.Identity) return Natural;
249
250 function Count
251 (Source : Unbounded_String;
252 Pattern : String;
253 Mapping : Maps.Character_Mapping_Function) return Natural;
254
255 function Count
256 (Source : Unbounded_String;
257 Set : Maps.Character_Set) return Natural;
258
259 procedure Find_Token
260 (Source : Unbounded_String;
261 Set : Maps.Character_Set;
262 From : Positive;
263 Test : Membership;
264 First : out Positive;
265 Last : out Natural);
266 pragma Ada_2012 (Find_Token);
267
268 procedure Find_Token
269 (Source : Unbounded_String;
270 Set : Maps.Character_Set;
271 Test : Membership;
272 First : out Positive;
273 Last : out Natural);
274
275 ------------------------------------
276 -- String Translation Subprograms --
277 ------------------------------------
278
279 function Translate
280 (Source : Unbounded_String;
281 Mapping : Maps.Character_Mapping) return Unbounded_String;
282
283 procedure Translate
284 (Source : in out Unbounded_String;
285 Mapping : Maps.Character_Mapping);
286
287 function Translate
288 (Source : Unbounded_String;
289 Mapping : Maps.Character_Mapping_Function) return Unbounded_String;
290
291 procedure Translate
292 (Source : in out Unbounded_String;
293 Mapping : Maps.Character_Mapping_Function);
294
295 ---------------------------------------
296 -- String Transformation Subprograms --
297 ---------------------------------------
298
299 function Replace_Slice
300 (Source : Unbounded_String;
301 Low : Positive;
302 High : Natural;
303 By : String) return Unbounded_String;
304
305 procedure Replace_Slice
306 (Source : in out Unbounded_String;
307 Low : Positive;
308 High : Natural;
309 By : String);
310
311 function Insert
312 (Source : Unbounded_String;
313 Before : Positive;
314 New_Item : String) return Unbounded_String;
315
316 procedure Insert
317 (Source : in out Unbounded_String;
318 Before : Positive;
319 New_Item : String);
320
321 function Overwrite
322 (Source : Unbounded_String;
323 Position : Positive;
324 New_Item : String) return Unbounded_String;
325
326 procedure Overwrite
327 (Source : in out Unbounded_String;
328 Position : Positive;
329 New_Item : String);
330
331 function Delete
332 (Source : Unbounded_String;
333 From : Positive;
334 Through : Natural) return Unbounded_String;
335
336 procedure Delete
337 (Source : in out Unbounded_String;
338 From : Positive;
339 Through : Natural);
340
341 function Trim
342 (Source : Unbounded_String;
343 Side : Trim_End) return Unbounded_String;
344
345 procedure Trim
346 (Source : in out Unbounded_String;
347 Side : Trim_End);
348
349 function Trim
350 (Source : Unbounded_String;
351 Left : Maps.Character_Set;
352 Right : Maps.Character_Set) return Unbounded_String;
353
354 procedure Trim
355 (Source : in out Unbounded_String;
356 Left : Maps.Character_Set;
357 Right : Maps.Character_Set);
358
359 function Head
360 (Source : Unbounded_String;
361 Count : Natural;
362 Pad : Character := Space) return Unbounded_String;
363
364 procedure Head
365 (Source : in out Unbounded_String;
366 Count : Natural;
367 Pad : Character := Space);
368
369 function Tail
370 (Source : Unbounded_String;
371 Count : Natural;
372 Pad : Character := Space) return Unbounded_String;
373
374 procedure Tail
375 (Source : in out Unbounded_String;
376 Count : Natural;
377 Pad : Character := Space);
378
379 function "*"
380 (Left : Natural;
381 Right : Character) return Unbounded_String;
382
383 function "*"
384 (Left : Natural;
385 Right : String) return Unbounded_String;
386
387 function "*"
388 (Left : Natural;
389 Right : Unbounded_String) return Unbounded_String;
390
391 private
392 pragma Inline (Length);
393
394 package AF renames Ada.Finalization;
395
396 Null_String : aliased String := "";
397
398 function To_Unbounded (S : String) return Unbounded_String
399 renames To_Unbounded_String;
400
401 type Unbounded_String is new AF.Controlled with record
402 Reference : String_Access := Null_String'Access;
403 Last : Natural := 0;
404 end record;
405 -- The Unbounded_String is using a buffered implementation to increase
406 -- speed of the Append/Delete/Insert procedures. The Reference string
407 -- pointer above contains the current string value and extra room at the
408 -- end to be used by the next Append routine. Last is the index of the
409 -- string ending character. So the current string value is really
410 -- Reference (1 .. Last).
411
412 pragma Stream_Convert (Unbounded_String, To_Unbounded, To_String);
413 -- Provide stream routines without dragging in Ada.Streams
414
415 pragma Finalize_Storage_Only (Unbounded_String);
416 -- Finalization is required only for freeing storage
417
418 procedure Initialize (Object : in out Unbounded_String);
419 procedure Adjust (Object : in out Unbounded_String);
420 procedure Finalize (Object : in out Unbounded_String);
421
422 procedure Realloc_For_Chunk
423 (Source : in out Unbounded_String;
424 Chunk_Size : Natural);
425 pragma Inline (Realloc_For_Chunk);
426 -- Adjust the size allocated for the string. Add at least Chunk_Size so it
427 -- is safe to add a string of this size at the end of the current content.
428 -- The real size allocated for the string is Chunk_Size + x of the current
429 -- string size. This buffered handling makes the Append unbounded string
430 -- routines very fast. This spec is in the private part so that it can be
431 -- accessed from children (e.g. from Unbounded.Text_IO).
432
433 Null_Unbounded_String : constant Unbounded_String :=
434 (AF.Controlled with
435 Reference => Null_String'Access,
436 Last => 0);
437 end Ada.Strings.Unbounded;