1 ------------------------------------------------------------------------------
3 -- GNAT RUN-TIME COMPONENTS --
5 -- A D A . S T R I N G S . W I D E _ W I D E _ 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 version is supported on:
37 -- - all Alpha platforms
38 -- - all ia64 platforms
39 -- - all PowerPC platforms
40 -- - all SPARC V9 platforms
41 -- - all x86 platforms
42 -- - all x86_64 platforms
44 with Ada.Strings.Wide_Wide_Maps;
45 private with Ada.Finalization;
46 private with System.Atomic_Counters;
48 package Ada.Strings.Wide_Wide_Unbounded is
51 type Unbounded_Wide_Wide_String is private;
52 pragma Preelaborable_Initialization (Unbounded_Wide_Wide_String);
54 Null_Unbounded_Wide_Wide_String : constant Unbounded_Wide_Wide_String;
56 function Length (Source : Unbounded_Wide_Wide_String) return Natural;
58 type Wide_Wide_String_Access is access all Wide_Wide_String;
60 procedure Free (X : in out Wide_Wide_String_Access);
62 --------------------------------------------------------
63 -- Conversion, Concatenation, and Selection Functions --
64 --------------------------------------------------------
66 function To_Unbounded_Wide_Wide_String
67 (Source : Wide_Wide_String) return Unbounded_Wide_Wide_String;
69 function To_Unbounded_Wide_Wide_String
70 (Length : Natural) return Unbounded_Wide_Wide_String;
72 function To_Wide_Wide_String
73 (Source : Unbounded_Wide_Wide_String) return Wide_Wide_String;
75 procedure Set_Unbounded_Wide_Wide_String
76 (Target : out Unbounded_Wide_Wide_String;
77 Source : Wide_Wide_String);
78 pragma Ada_05 (Set_Unbounded_Wide_Wide_String);
81 (Source : in out Unbounded_Wide_Wide_String;
82 New_Item : Unbounded_Wide_Wide_String);
85 (Source : in out Unbounded_Wide_Wide_String;
86 New_Item : Wide_Wide_String);
89 (Source : in out Unbounded_Wide_Wide_String;
90 New_Item : Wide_Wide_Character);
93 (Left : Unbounded_Wide_Wide_String;
94 Right : Unbounded_Wide_Wide_String) return Unbounded_Wide_Wide_String;
97 (Left : Unbounded_Wide_Wide_String;
98 Right : Wide_Wide_String) return Unbounded_Wide_Wide_String;
101 (Left : Wide_Wide_String;
102 Right : Unbounded_Wide_Wide_String) return Unbounded_Wide_Wide_String;
105 (Left : Unbounded_Wide_Wide_String;
106 Right : Wide_Wide_Character) return Unbounded_Wide_Wide_String;
109 (Left : Wide_Wide_Character;
110 Right : Unbounded_Wide_Wide_String) return Unbounded_Wide_Wide_String;
113 (Source : Unbounded_Wide_Wide_String;
114 Index : Positive) return Wide_Wide_Character;
116 procedure Replace_Element
117 (Source : in out Unbounded_Wide_Wide_String;
119 By : Wide_Wide_Character);
122 (Source : Unbounded_Wide_Wide_String;
124 High : Natural) return Wide_Wide_String;
126 function Unbounded_Slice
127 (Source : Unbounded_Wide_Wide_String;
129 High : Natural) return Unbounded_Wide_Wide_String;
130 pragma Ada_05 (Unbounded_Slice);
132 procedure Unbounded_Slice
133 (Source : Unbounded_Wide_Wide_String;
134 Target : out Unbounded_Wide_Wide_String;
137 pragma Ada_05 (Unbounded_Slice);
140 (Left : Unbounded_Wide_Wide_String;
141 Right : Unbounded_Wide_Wide_String) return Boolean;
144 (Left : Unbounded_Wide_Wide_String;
145 Right : Wide_Wide_String) return Boolean;
148 (Left : Wide_Wide_String;
149 Right : Unbounded_Wide_Wide_String) return Boolean;
152 (Left : Unbounded_Wide_Wide_String;
153 Right : Unbounded_Wide_Wide_String) return Boolean;
156 (Left : Unbounded_Wide_Wide_String;
157 Right : Wide_Wide_String) return Boolean;
160 (Left : Wide_Wide_String;
161 Right : Unbounded_Wide_Wide_String) return Boolean;
164 (Left : Unbounded_Wide_Wide_String;
165 Right : Unbounded_Wide_Wide_String) return Boolean;
168 (Left : Unbounded_Wide_Wide_String;
169 Right : Wide_Wide_String) return Boolean;
172 (Left : Wide_Wide_String;
173 Right : Unbounded_Wide_Wide_String) return Boolean;
176 (Left : Unbounded_Wide_Wide_String;
177 Right : Unbounded_Wide_Wide_String) return Boolean;
180 (Left : Unbounded_Wide_Wide_String;
181 Right : Wide_Wide_String) return Boolean;
184 (Left : Wide_Wide_String;
185 Right : Unbounded_Wide_Wide_String) return Boolean;
188 (Left : Unbounded_Wide_Wide_String;
189 Right : Unbounded_Wide_Wide_String) return Boolean;
192 (Left : Unbounded_Wide_Wide_String;
193 Right : Wide_Wide_String) return Boolean;
196 (Left : Wide_Wide_String;
197 Right : Unbounded_Wide_Wide_String) return Boolean;
199 ------------------------
200 -- Search Subprograms --
201 ------------------------
204 (Source : Unbounded_Wide_Wide_String;
205 Pattern : Wide_Wide_String;
206 Going : Direction := Forward;
207 Mapping : Wide_Wide_Maps.Wide_Wide_Character_Mapping :=
208 Wide_Wide_Maps.Identity)
212 (Source : Unbounded_Wide_Wide_String;
213 Pattern : Wide_Wide_String;
214 Going : Direction := Forward;
215 Mapping : Wide_Wide_Maps.Wide_Wide_Character_Mapping_Function)
219 (Source : Unbounded_Wide_Wide_String;
220 Set : Wide_Wide_Maps.Wide_Wide_Character_Set;
221 Test : Membership := Inside;
222 Going : Direction := Forward) return Natural;
225 (Source : Unbounded_Wide_Wide_String;
226 Pattern : Wide_Wide_String;
228 Going : Direction := Forward;
229 Mapping : Wide_Wide_Maps.Wide_Wide_Character_Mapping :=
230 Wide_Wide_Maps.Identity)
232 pragma Ada_05 (Index);
235 (Source : Unbounded_Wide_Wide_String;
236 Pattern : Wide_Wide_String;
238 Going : Direction := Forward;
239 Mapping : Wide_Wide_Maps.Wide_Wide_Character_Mapping_Function)
241 pragma Ada_05 (Index);
244 (Source : Unbounded_Wide_Wide_String;
245 Set : Wide_Wide_Maps.Wide_Wide_Character_Set;
247 Test : Membership := Inside;
248 Going : Direction := Forward) return Natural;
249 pragma Ada_05 (Index);
251 function Index_Non_Blank
252 (Source : Unbounded_Wide_Wide_String;
253 Going : Direction := Forward) return Natural;
255 function Index_Non_Blank
256 (Source : Unbounded_Wide_Wide_String;
258 Going : Direction := Forward) return Natural;
259 pragma Ada_05 (Index_Non_Blank);
262 (Source : Unbounded_Wide_Wide_String;
263 Pattern : Wide_Wide_String;
264 Mapping : Wide_Wide_Maps.Wide_Wide_Character_Mapping :=
265 Wide_Wide_Maps.Identity)
269 (Source : Unbounded_Wide_Wide_String;
270 Pattern : Wide_Wide_String;
271 Mapping : Wide_Wide_Maps.Wide_Wide_Character_Mapping_Function)
275 (Source : Unbounded_Wide_Wide_String;
276 Set : Wide_Wide_Maps.Wide_Wide_Character_Set) return Natural;
279 (Source : Unbounded_Wide_Wide_String;
280 Set : Wide_Wide_Maps.Wide_Wide_Character_Set;
283 First : out Positive;
285 pragma Ada_2012 (Find_Token);
288 (Source : Unbounded_Wide_Wide_String;
289 Set : Wide_Wide_Maps.Wide_Wide_Character_Set;
291 First : out Positive;
294 ------------------------------------
295 -- String Translation Subprograms --
296 ------------------------------------
299 (Source : Unbounded_Wide_Wide_String;
300 Mapping : Wide_Wide_Maps.Wide_Wide_Character_Mapping)
301 return Unbounded_Wide_Wide_String;
304 (Source : in out Unbounded_Wide_Wide_String;
305 Mapping : Wide_Wide_Maps.Wide_Wide_Character_Mapping);
308 (Source : Unbounded_Wide_Wide_String;
309 Mapping : Wide_Wide_Maps.Wide_Wide_Character_Mapping_Function)
310 return Unbounded_Wide_Wide_String;
313 (Source : in out Unbounded_Wide_Wide_String;
314 Mapping : Wide_Wide_Maps.Wide_Wide_Character_Mapping_Function);
316 ---------------------------------------
317 -- String Transformation Subprograms --
318 ---------------------------------------
320 function Replace_Slice
321 (Source : Unbounded_Wide_Wide_String;
324 By : Wide_Wide_String) return Unbounded_Wide_Wide_String;
326 procedure Replace_Slice
327 (Source : in out Unbounded_Wide_Wide_String;
330 By : Wide_Wide_String);
333 (Source : Unbounded_Wide_Wide_String;
335 New_Item : Wide_Wide_String) return Unbounded_Wide_Wide_String;
338 (Source : in out Unbounded_Wide_Wide_String;
340 New_Item : Wide_Wide_String);
343 (Source : Unbounded_Wide_Wide_String;
345 New_Item : Wide_Wide_String) return Unbounded_Wide_Wide_String;
348 (Source : in out Unbounded_Wide_Wide_String;
350 New_Item : Wide_Wide_String);
353 (Source : Unbounded_Wide_Wide_String;
355 Through : Natural) return Unbounded_Wide_Wide_String;
358 (Source : in out Unbounded_Wide_Wide_String;
363 (Source : Unbounded_Wide_Wide_String;
364 Side : Trim_End) return Unbounded_Wide_Wide_String;
367 (Source : in out Unbounded_Wide_Wide_String;
371 (Source : Unbounded_Wide_Wide_String;
372 Left : Wide_Wide_Maps.Wide_Wide_Character_Set;
373 Right : Wide_Wide_Maps.Wide_Wide_Character_Set)
374 return Unbounded_Wide_Wide_String;
377 (Source : in out Unbounded_Wide_Wide_String;
378 Left : Wide_Wide_Maps.Wide_Wide_Character_Set;
379 Right : Wide_Wide_Maps.Wide_Wide_Character_Set);
382 (Source : Unbounded_Wide_Wide_String;
384 Pad : Wide_Wide_Character := Wide_Wide_Space)
385 return Unbounded_Wide_Wide_String;
388 (Source : in out Unbounded_Wide_Wide_String;
390 Pad : Wide_Wide_Character := Wide_Wide_Space);
393 (Source : Unbounded_Wide_Wide_String;
395 Pad : Wide_Wide_Character := Wide_Wide_Space)
396 return Unbounded_Wide_Wide_String;
399 (Source : in out Unbounded_Wide_Wide_String;
401 Pad : Wide_Wide_Character := Wide_Wide_Space);
405 Right : Wide_Wide_Character) return Unbounded_Wide_Wide_String;
409 Right : Wide_Wide_String) return Unbounded_Wide_Wide_String;
413 Right : Unbounded_Wide_Wide_String) return Unbounded_Wide_Wide_String;
416 pragma Inline (Length);
418 package AF renames Ada.Finalization;
420 type Shared_Wide_Wide_String (Max_Length : Natural) is limited record
421 Counter : System.Atomic_Counters.Atomic_Counter;
425 Data : Wide_Wide_String (1 .. Max_Length);
426 -- Last is the index of last significant element of the Data. All
427 -- elements with larger indices are just an extra room.
430 type Shared_Wide_Wide_String_Access is access all Shared_Wide_Wide_String;
432 procedure Reference (Item : not null Shared_Wide_Wide_String_Access);
433 -- Increment reference counter.
435 procedure Unreference (Item : not null Shared_Wide_Wide_String_Access);
436 -- Decrement reference counter. Deallocate Item when reference counter is
439 function Can_Be_Reused
440 (Item : Shared_Wide_Wide_String_Access;
441 Length : Natural) return Boolean;
442 -- Returns True if Shared_Wide_Wide_String can be reused. There are two
443 -- criteria when Shared_Wide_Wide_String can be reused: its reference
444 -- counter must be one (thus Shared_Wide_Wide_String is owned exclusively)
445 -- and its size is sufficient to store string with specified length
449 (Max_Length : Natural) return Shared_Wide_Wide_String_Access;
450 -- Allocates new Shared_Wide_Wide_String with at least specified maximum
451 -- length. Actual maximum length of the allocated Shared_Wide_Wide_String
452 -- can be slightly greater. Returns reference to
453 -- Empty_Shared_Wide_Wide_String when requested length is zero.
455 Empty_Shared_Wide_Wide_String : aliased Shared_Wide_Wide_String (0);
457 function To_Unbounded
458 (S : Wide_Wide_String) return Unbounded_Wide_Wide_String
459 renames To_Unbounded_Wide_Wide_String;
460 -- This renames are here only to be used in the pragma Stream_Convert.
462 type Unbounded_Wide_Wide_String is new AF.Controlled with record
463 Reference : Shared_Wide_Wide_String_Access :=
464 Empty_Shared_Wide_Wide_String'Access;
467 -- The Unbounded_Wide_Wide_String uses several techniques to increase speed
468 -- of the application:
470 -- - implicit sharing or copy-on-write. Unbounded_Wide_Wide_String
471 -- contains only the reference to the data which is shared between
472 -- several instances. The shared data is reallocated only when its value
473 -- is changed and the object mutation can't be used or it is inefficient
476 -- - object mutation. Shared data object can be reused without memory
477 -- reallocation when all of the following requirements are meat:
478 -- - shared data object don't used anywhere longer;
479 -- - its size is sufficient to store new value;
480 -- - the gap after reuse is less then some threshold.
482 -- - memory preallocation. Most of used memory allocation algorithms
483 -- aligns allocated segment on the some boundary, thus some amount of
484 -- additional memory can be preallocated without any impact. Such
485 -- preallocated memory can used later by Append/Insert operations
486 -- without reallocation.
488 -- Reference counting uses GCC builtin atomic operations, which allows to
489 -- safely share internal data between Ada tasks. Nevertheless, this not
490 -- make objects of Unbounded_Wide_Wide_String thread-safe, so each instance
491 -- can't be accessed by several tasks simultaneously.
493 pragma Stream_Convert
494 (Unbounded_Wide_Wide_String, To_Unbounded, To_Wide_Wide_String);
495 -- Provide stream routines without dragging in Ada.Streams
497 pragma Finalize_Storage_Only (Unbounded_Wide_Wide_String);
498 -- Finalization is required only for freeing storage
500 overriding procedure Initialize
501 (Object : in out Unbounded_Wide_Wide_String);
502 overriding procedure Adjust
503 (Object : in out Unbounded_Wide_Wide_String);
504 overriding procedure Finalize
505 (Object : in out Unbounded_Wide_Wide_String);
507 Null_Unbounded_Wide_Wide_String : constant Unbounded_Wide_Wide_String :=
510 Empty_Shared_Wide_Wide_String'
513 end Ada.Strings.Wide_Wide_Unbounded;