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 -- This package provides an implementation of Ada.Strings.Unbounded that uses
37 -- reference counts to implement copy on modification (rather than copy on
38 -- assignment). This is significantly more efficient on many targets.
40 -- This version is supported on:
41 -- - all Alpha platforms
42 -- - all ia64 platforms
43 -- - all PowerPC platforms
44 -- - all SPARC V9 platforms
45 -- - all x86 platforms
46 -- - all x86_64 platforms
48 -- This package uses several techniques to increase speed:
50 -- - Implicit sharing or copy-on-write. An Unbounded_String contains only
51 -- the reference to the data which is shared between several instances.
52 -- The shared data is reallocated only when its value is changed and
53 -- the object mutation can't be used or it is inefficient to use it.
55 -- - Object mutation. Shared data object can be reused without memory
56 -- reallocation when all of the following requirements are met:
57 -- - the shared data object is no longer used by anyone else;
58 -- - the size is sufficient to store the new value;
59 -- - the gap after reuse is less then a defined threshold.
61 -- - Memory preallocation. Most of used memory allocation algorithms
62 -- align allocated segments on the some boundary, thus some amount of
63 -- additional memory can be preallocated without any impact. Such
64 -- preallocated memory can used later by Append/Insert operations
65 -- without reallocation.
67 -- Reference counting uses GCC builtin atomic operations, which allows to
68 -- safely share internal data between Ada tasks. Nevertheless, this doesn't
69 -- make objects of Unbounded_String thread-safe: each instance can't be
70 -- accessed by several tasks simultaneously.
72 with Ada.Strings.Maps;
73 private with Ada.Finalization;
74 private with System.Atomic_Counters;
76 package Ada.Strings.Unbounded is
79 type Unbounded_String is private;
80 pragma Preelaborable_Initialization (Unbounded_String);
82 Null_Unbounded_String : constant Unbounded_String;
84 function Length (Source : Unbounded_String) return Natural;
86 type String_Access is access all String;
88 procedure Free (X : in out String_Access);
90 --------------------------------------------------------
91 -- Conversion, Concatenation, and Selection Functions --
92 --------------------------------------------------------
94 function To_Unbounded_String
95 (Source : String) return Unbounded_String;
97 function To_Unbounded_String
98 (Length : Natural) return Unbounded_String;
100 function To_String (Source : Unbounded_String) return String;
102 procedure Set_Unbounded_String
103 (Target : out Unbounded_String;
105 pragma Ada_05 (Set_Unbounded_String);
108 (Source : in out Unbounded_String;
109 New_Item : Unbounded_String);
112 (Source : in out Unbounded_String;
116 (Source : in out Unbounded_String;
117 New_Item : Character);
120 (Left : Unbounded_String;
121 Right : Unbounded_String) return Unbounded_String;
124 (Left : Unbounded_String;
125 Right : String) return Unbounded_String;
129 Right : Unbounded_String) return Unbounded_String;
132 (Left : Unbounded_String;
133 Right : Character) return Unbounded_String;
137 Right : Unbounded_String) return Unbounded_String;
140 (Source : Unbounded_String;
141 Index : Positive) return Character;
143 procedure Replace_Element
144 (Source : in out Unbounded_String;
149 (Source : Unbounded_String;
151 High : Natural) return String;
153 function Unbounded_Slice
154 (Source : Unbounded_String;
156 High : Natural) return Unbounded_String;
157 pragma Ada_05 (Unbounded_Slice);
159 procedure Unbounded_Slice
160 (Source : Unbounded_String;
161 Target : out Unbounded_String;
164 pragma Ada_05 (Unbounded_Slice);
167 (Left : Unbounded_String;
168 Right : Unbounded_String) return Boolean;
171 (Left : Unbounded_String;
172 Right : String) return Boolean;
176 Right : Unbounded_String) return Boolean;
179 (Left : Unbounded_String;
180 Right : Unbounded_String) return Boolean;
183 (Left : Unbounded_String;
184 Right : String) return Boolean;
188 Right : Unbounded_String) return Boolean;
191 (Left : Unbounded_String;
192 Right : Unbounded_String) return Boolean;
195 (Left : Unbounded_String;
196 Right : String) return Boolean;
200 Right : Unbounded_String) return Boolean;
203 (Left : Unbounded_String;
204 Right : Unbounded_String) return Boolean;
207 (Left : Unbounded_String;
208 Right : String) return Boolean;
212 Right : Unbounded_String) return Boolean;
215 (Left : Unbounded_String;
216 Right : Unbounded_String) return Boolean;
219 (Left : Unbounded_String;
220 Right : String) return Boolean;
224 Right : Unbounded_String) return Boolean;
226 ------------------------
227 -- Search Subprograms --
228 ------------------------
231 (Source : Unbounded_String;
233 Going : Direction := Forward;
234 Mapping : Maps.Character_Mapping := Maps.Identity) return Natural;
237 (Source : Unbounded_String;
239 Going : Direction := Forward;
240 Mapping : Maps.Character_Mapping_Function) return Natural;
243 (Source : Unbounded_String;
244 Set : Maps.Character_Set;
245 Test : Membership := Inside;
246 Going : Direction := Forward) return Natural;
249 (Source : Unbounded_String;
252 Going : Direction := Forward;
253 Mapping : Maps.Character_Mapping := Maps.Identity) return Natural;
254 pragma Ada_05 (Index);
257 (Source : Unbounded_String;
260 Going : Direction := Forward;
261 Mapping : Maps.Character_Mapping_Function) return Natural;
262 pragma Ada_05 (Index);
265 (Source : Unbounded_String;
266 Set : Maps.Character_Set;
268 Test : Membership := Inside;
269 Going : Direction := Forward) return Natural;
270 pragma Ada_05 (Index);
272 function Index_Non_Blank
273 (Source : Unbounded_String;
274 Going : Direction := Forward) return Natural;
276 function Index_Non_Blank
277 (Source : Unbounded_String;
279 Going : Direction := Forward) return Natural;
280 pragma Ada_05 (Index_Non_Blank);
283 (Source : Unbounded_String;
285 Mapping : Maps.Character_Mapping := Maps.Identity) return Natural;
288 (Source : Unbounded_String;
290 Mapping : Maps.Character_Mapping_Function) return Natural;
293 (Source : Unbounded_String;
294 Set : Maps.Character_Set) return Natural;
297 (Source : Unbounded_String;
298 Set : Maps.Character_Set;
301 First : out Positive;
303 pragma Ada_2012 (Find_Token);
306 (Source : Unbounded_String;
307 Set : Maps.Character_Set;
309 First : out Positive;
312 ------------------------------------
313 -- String Translation Subprograms --
314 ------------------------------------
317 (Source : Unbounded_String;
318 Mapping : Maps.Character_Mapping) return Unbounded_String;
321 (Source : in out Unbounded_String;
322 Mapping : Maps.Character_Mapping);
325 (Source : Unbounded_String;
326 Mapping : Maps.Character_Mapping_Function) return Unbounded_String;
329 (Source : in out Unbounded_String;
330 Mapping : Maps.Character_Mapping_Function);
332 ---------------------------------------
333 -- String Transformation Subprograms --
334 ---------------------------------------
336 function Replace_Slice
337 (Source : Unbounded_String;
340 By : String) return Unbounded_String;
342 procedure Replace_Slice
343 (Source : in out Unbounded_String;
349 (Source : Unbounded_String;
351 New_Item : String) return Unbounded_String;
354 (Source : in out Unbounded_String;
359 (Source : Unbounded_String;
361 New_Item : String) return Unbounded_String;
364 (Source : in out Unbounded_String;
369 (Source : Unbounded_String;
371 Through : Natural) return Unbounded_String;
374 (Source : in out Unbounded_String;
379 (Source : Unbounded_String;
380 Side : Trim_End) return Unbounded_String;
383 (Source : in out Unbounded_String;
387 (Source : Unbounded_String;
388 Left : Maps.Character_Set;
389 Right : Maps.Character_Set) return Unbounded_String;
392 (Source : in out Unbounded_String;
393 Left : Maps.Character_Set;
394 Right : Maps.Character_Set);
397 (Source : Unbounded_String;
399 Pad : Character := Space) return Unbounded_String;
402 (Source : in out Unbounded_String;
404 Pad : Character := Space);
407 (Source : Unbounded_String;
409 Pad : Character := Space) return Unbounded_String;
412 (Source : in out Unbounded_String;
414 Pad : Character := Space);
418 Right : Character) return Unbounded_String;
422 Right : String) return Unbounded_String;
426 Right : Unbounded_String) return Unbounded_String;
429 pragma Inline (Length);
431 package AF renames Ada.Finalization;
433 type Shared_String (Max_Length : Natural) is limited record
434 Counter : System.Atomic_Counters.Atomic_Counter;
438 Data : String (1 .. Max_Length);
439 -- Last is the index of last significant element of the Data. All
440 -- elements with larger indexes are currently insignificant.
443 type Shared_String_Access is access all Shared_String;
445 procedure Reference (Item : not null Shared_String_Access);
446 -- Increment reference counter
448 procedure Unreference (Item : not null Shared_String_Access);
449 -- Decrement reference counter, deallocate Item when counter goes to zero
451 function Can_Be_Reused
452 (Item : Shared_String_Access;
453 Length : Natural) return Boolean;
454 -- Returns True if Shared_String can be reused. There are two criteria when
455 -- Shared_String can be reused: its reference counter must be one (thus
456 -- Shared_String is owned exclusively) and its size is sufficient to
457 -- store string with specified length effectively.
459 function Allocate (Max_Length : Natural) return Shared_String_Access;
460 -- Allocates new Shared_String with at least specified maximum length.
461 -- Actual maximum length of the allocated Shared_String can be slightly
462 -- greater. Returns reference to Empty_Shared_String when requested length
465 Empty_Shared_String : aliased Shared_String (0);
467 function To_Unbounded (S : String) return Unbounded_String
468 renames To_Unbounded_String;
469 -- This renames are here only to be used in the pragma Stream_Convert
471 type Unbounded_String is new AF.Controlled with record
472 Reference : Shared_String_Access := Empty_Shared_String'Access;
475 pragma Stream_Convert (Unbounded_String, To_Unbounded, To_String);
476 -- Provide stream routines without dragging in Ada.Streams
478 pragma Finalize_Storage_Only (Unbounded_String);
479 -- Finalization is required only for freeing storage
481 overriding procedure Initialize (Object : in out Unbounded_String);
482 overriding procedure Adjust (Object : in out Unbounded_String);
483 overriding procedure Finalize (Object : in out Unbounded_String);
485 Null_Unbounded_String : constant Unbounded_String :=
487 Reference => Empty_Shared_String'Access);
489 end Ada.Strings.Unbounded;