1 ------------------------------------------------------------------------------
3 -- GNAT RUN-TIME COMPONENTS --
5 -- A D A . S T R I N G S . U N B O U N D E D --
9 -- Copyright (C) 1992-2011, Free Software Foundation, Inc. --
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. --
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. --
22 -- As a special exception under Section 7 of GPL version 3, you are granted --
23 -- additional permissions described in the GCC Runtime Library Exception, --
24 -- version 3.1, as published by the Free Software Foundation. --
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/>. --
31 -- GNAT was originally developed by the GNAT team at New York University. --
32 -- Extensive contributions were provided by Ada Core Technologies Inc. --
34 ------------------------------------------------------------------------------
36 with Ada.Strings.Maps;
37 with Ada.Finalization;
39 package Ada.Strings.Unbounded is
42 type Unbounded_String is private;
43 pragma Preelaborable_Initialization (Unbounded_String);
45 Null_Unbounded_String : constant Unbounded_String;
47 function Length (Source : Unbounded_String) return Natural;
49 type String_Access is access all String;
51 procedure Free (X : in out String_Access);
53 --------------------------------------------------------
54 -- Conversion, Concatenation, and Selection Functions --
55 --------------------------------------------------------
57 function To_Unbounded_String
58 (Source : String) return Unbounded_String;
60 function To_Unbounded_String
61 (Length : Natural) return Unbounded_String;
63 function To_String (Source : Unbounded_String) return String;
65 procedure Set_Unbounded_String
66 (Target : out Unbounded_String;
68 pragma Ada_05 (Set_Unbounded_String);
71 (Source : in out Unbounded_String;
72 New_Item : Unbounded_String);
75 (Source : in out Unbounded_String;
79 (Source : in out Unbounded_String;
80 New_Item : Character);
83 (Left : Unbounded_String;
84 Right : Unbounded_String) return Unbounded_String;
87 (Left : Unbounded_String;
88 Right : String) return Unbounded_String;
92 Right : Unbounded_String) return Unbounded_String;
95 (Left : Unbounded_String;
96 Right : Character) return Unbounded_String;
100 Right : Unbounded_String) return Unbounded_String;
103 (Source : Unbounded_String;
104 Index : Positive) return Character;
106 procedure Replace_Element
107 (Source : in out Unbounded_String;
112 (Source : Unbounded_String;
114 High : Natural) return String;
116 function Unbounded_Slice
117 (Source : Unbounded_String;
119 High : Natural) return Unbounded_String;
120 pragma Ada_05 (Unbounded_Slice);
122 procedure Unbounded_Slice
123 (Source : Unbounded_String;
124 Target : out Unbounded_String;
127 pragma Ada_05 (Unbounded_Slice);
130 (Left : Unbounded_String;
131 Right : Unbounded_String) return Boolean;
134 (Left : Unbounded_String;
135 Right : String) return Boolean;
139 Right : Unbounded_String) return Boolean;
142 (Left : Unbounded_String;
143 Right : Unbounded_String) return Boolean;
146 (Left : Unbounded_String;
147 Right : String) return Boolean;
151 Right : Unbounded_String) return Boolean;
154 (Left : Unbounded_String;
155 Right : Unbounded_String) return Boolean;
158 (Left : Unbounded_String;
159 Right : String) return Boolean;
163 Right : Unbounded_String) return Boolean;
166 (Left : Unbounded_String;
167 Right : Unbounded_String) return Boolean;
170 (Left : Unbounded_String;
171 Right : String) return Boolean;
175 Right : Unbounded_String) return Boolean;
178 (Left : Unbounded_String;
179 Right : Unbounded_String) return Boolean;
182 (Left : Unbounded_String;
183 Right : String) return Boolean;
187 Right : Unbounded_String) return Boolean;
189 ------------------------
190 -- Search Subprograms --
191 ------------------------
194 (Source : Unbounded_String;
196 Going : Direction := Forward;
197 Mapping : Maps.Character_Mapping := Maps.Identity) return Natural;
200 (Source : Unbounded_String;
202 Going : Direction := Forward;
203 Mapping : Maps.Character_Mapping_Function) return Natural;
206 (Source : Unbounded_String;
207 Set : Maps.Character_Set;
208 Test : Membership := Inside;
209 Going : Direction := Forward) return Natural;
212 (Source : Unbounded_String;
215 Going : Direction := Forward;
216 Mapping : Maps.Character_Mapping := Maps.Identity) return Natural;
217 pragma Ada_05 (Index);
220 (Source : Unbounded_String;
223 Going : Direction := Forward;
224 Mapping : Maps.Character_Mapping_Function) return Natural;
225 pragma Ada_05 (Index);
228 (Source : Unbounded_String;
229 Set : Maps.Character_Set;
231 Test : Membership := Inside;
232 Going : Direction := Forward) return Natural;
233 pragma Ada_05 (Index);
235 function Index_Non_Blank
236 (Source : Unbounded_String;
237 Going : Direction := Forward) return Natural;
239 function Index_Non_Blank
240 (Source : Unbounded_String;
242 Going : Direction := Forward) return Natural;
243 pragma Ada_05 (Index_Non_Blank);
246 (Source : Unbounded_String;
248 Mapping : Maps.Character_Mapping := Maps.Identity) return Natural;
251 (Source : Unbounded_String;
253 Mapping : Maps.Character_Mapping_Function) return Natural;
256 (Source : Unbounded_String;
257 Set : Maps.Character_Set) return Natural;
260 (Source : Unbounded_String;
261 Set : Maps.Character_Set;
264 First : out Positive;
266 pragma Ada_2012 (Find_Token);
269 (Source : Unbounded_String;
270 Set : Maps.Character_Set;
272 First : out Positive;
275 ------------------------------------
276 -- String Translation Subprograms --
277 ------------------------------------
280 (Source : Unbounded_String;
281 Mapping : Maps.Character_Mapping) return Unbounded_String;
284 (Source : in out Unbounded_String;
285 Mapping : Maps.Character_Mapping);
288 (Source : Unbounded_String;
289 Mapping : Maps.Character_Mapping_Function) return Unbounded_String;
292 (Source : in out Unbounded_String;
293 Mapping : Maps.Character_Mapping_Function);
295 ---------------------------------------
296 -- String Transformation Subprograms --
297 ---------------------------------------
299 function Replace_Slice
300 (Source : Unbounded_String;
303 By : String) return Unbounded_String;
305 procedure Replace_Slice
306 (Source : in out Unbounded_String;
312 (Source : Unbounded_String;
314 New_Item : String) return Unbounded_String;
317 (Source : in out Unbounded_String;
322 (Source : Unbounded_String;
324 New_Item : String) return Unbounded_String;
327 (Source : in out Unbounded_String;
332 (Source : Unbounded_String;
334 Through : Natural) return Unbounded_String;
337 (Source : in out Unbounded_String;
342 (Source : Unbounded_String;
343 Side : Trim_End) return Unbounded_String;
346 (Source : in out Unbounded_String;
350 (Source : Unbounded_String;
351 Left : Maps.Character_Set;
352 Right : Maps.Character_Set) return Unbounded_String;
355 (Source : in out Unbounded_String;
356 Left : Maps.Character_Set;
357 Right : Maps.Character_Set);
360 (Source : Unbounded_String;
362 Pad : Character := Space) return Unbounded_String;
365 (Source : in out Unbounded_String;
367 Pad : Character := Space);
370 (Source : Unbounded_String;
372 Pad : Character := Space) return Unbounded_String;
375 (Source : in out Unbounded_String;
377 Pad : Character := Space);
381 Right : Character) return Unbounded_String;
385 Right : String) return Unbounded_String;
389 Right : Unbounded_String) return Unbounded_String;
392 pragma Inline (Length);
394 package AF renames Ada.Finalization;
396 Null_String : aliased String := "";
398 function To_Unbounded (S : String) return Unbounded_String
399 renames To_Unbounded_String;
401 type Unbounded_String is new AF.Controlled with record
402 Reference : String_Access := Null_String'Access;
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).
412 pragma Stream_Convert (Unbounded_String, To_Unbounded, To_String);
413 -- Provide stream routines without dragging in Ada.Streams
415 pragma Finalize_Storage_Only (Unbounded_String);
416 -- Finalization is required only for freeing storage
418 procedure Initialize (Object : in out Unbounded_String);
419 procedure Adjust (Object : in out Unbounded_String);
420 procedure Finalize (Object : in out Unbounded_String);
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).
433 Null_Unbounded_String : constant Unbounded_String :=
435 Reference => Null_String'Access,
437 end Ada.Strings.Unbounded;