1 ------------------------------------------------------------------------------
3 -- GNAT RUN-TIME COMPONENTS --
5 -- A D A . S T R I N G S . W I D E _ U N B O U N D E D --
9 -- Copyright (C) 1992-2009, 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 2, 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. See the GNU General Public License --
21 -- for more details. You should have received a copy of the GNU General --
22 -- Public License distributed with GNAT; see file COPYING. If not, write --
23 -- to the Free Software Foundation, 51 Franklin Street, Fifth Floor, --
24 -- Boston, MA 02110-1301, USA. --
26 -- As a special exception, if other files instantiate generics from this --
27 -- unit, or you link this unit with other files to produce an executable, --
28 -- this unit does not by itself cause the resulting executable to be --
29 -- covered by the GNU General Public License. This exception does not --
30 -- however invalidate any other reasons why the executable file might be --
31 -- covered by the GNU Public License. --
33 -- GNAT was originally developed by the GNAT team at New York University. --
34 -- Extensive contributions were provided by Ada Core Technologies Inc. --
36 ------------------------------------------------------------------------------
38 -- This version is supported on:
39 -- - all Alpha platforms
40 -- - all ia64 platforms
41 -- - all PowerPC platforms
42 -- - all SPARC V9 platforms
43 -- - all x86_64 platforms
45 with Ada
.Strings
.Wide_Maps
;
46 private with Ada
.Finalization
;
47 private with Interfaces
;
49 package Ada
.Strings
.Wide_Unbounded
is
52 type Unbounded_Wide_String
is private;
53 pragma Preelaborable_Initialization
(Unbounded_Wide_String
);
55 Null_Unbounded_Wide_String
: constant Unbounded_Wide_String
;
57 function Length
(Source
: Unbounded_Wide_String
) return Natural;
59 type Wide_String_Access
is access all Wide_String;
61 procedure Free
(X
: in out Wide_String_Access
);
63 --------------------------------------------------------
64 -- Conversion, Concatenation, and Selection Functions --
65 --------------------------------------------------------
67 function To_Unbounded_Wide_String
68 (Source
: Wide_String) return Unbounded_Wide_String
;
70 function To_Unbounded_Wide_String
71 (Length
: Natural) return Unbounded_Wide_String
;
73 function To_Wide_String
74 (Source
: Unbounded_Wide_String
) return Wide_String;
76 procedure Set_Unbounded_Wide_String
77 (Target
: out Unbounded_Wide_String
;
78 Source
: Wide_String);
79 pragma Ada_05
(Set_Unbounded_Wide_String
);
82 (Source
: in out Unbounded_Wide_String
;
83 New_Item
: Unbounded_Wide_String
);
86 (Source
: in out Unbounded_Wide_String
;
87 New_Item
: Wide_String);
90 (Source
: in out Unbounded_Wide_String
;
91 New_Item
: Wide_Character);
94 (Left
: Unbounded_Wide_String
;
95 Right
: Unbounded_Wide_String
) return Unbounded_Wide_String
;
98 (Left
: Unbounded_Wide_String
;
99 Right
: Wide_String) return Unbounded_Wide_String
;
103 Right
: Unbounded_Wide_String
) return Unbounded_Wide_String
;
106 (Left
: Unbounded_Wide_String
;
107 Right
: Wide_Character) return Unbounded_Wide_String
;
110 (Left
: Wide_Character;
111 Right
: Unbounded_Wide_String
) return Unbounded_Wide_String
;
114 (Source
: Unbounded_Wide_String
;
115 Index
: Positive) return Wide_Character;
117 procedure Replace_Element
118 (Source
: in out Unbounded_Wide_String
;
120 By
: Wide_Character);
123 (Source
: Unbounded_Wide_String
;
125 High
: Natural) return Wide_String;
127 function Unbounded_Slice
128 (Source
: Unbounded_Wide_String
;
130 High
: Natural) return Unbounded_Wide_String
;
131 pragma Ada_05
(Unbounded_Slice
);
133 procedure Unbounded_Slice
134 (Source
: Unbounded_Wide_String
;
135 Target
: out Unbounded_Wide_String
;
138 pragma Ada_05
(Unbounded_Slice
);
141 (Left
: Unbounded_Wide_String
;
142 Right
: Unbounded_Wide_String
) return Boolean;
145 (Left
: Unbounded_Wide_String
;
146 Right
: Wide_String) return Boolean;
150 Right
: Unbounded_Wide_String
) return Boolean;
153 (Left
: Unbounded_Wide_String
;
154 Right
: Unbounded_Wide_String
) return Boolean;
157 (Left
: Unbounded_Wide_String
;
158 Right
: Wide_String) return Boolean;
162 Right
: Unbounded_Wide_String
) return Boolean;
165 (Left
: Unbounded_Wide_String
;
166 Right
: Unbounded_Wide_String
) return Boolean;
169 (Left
: Unbounded_Wide_String
;
170 Right
: Wide_String) return Boolean;
174 Right
: Unbounded_Wide_String
) return Boolean;
177 (Left
: Unbounded_Wide_String
;
178 Right
: Unbounded_Wide_String
) return Boolean;
181 (Left
: Unbounded_Wide_String
;
182 Right
: Wide_String) return Boolean;
186 Right
: Unbounded_Wide_String
) return Boolean;
189 (Left
: Unbounded_Wide_String
;
190 Right
: Unbounded_Wide_String
) return Boolean;
193 (Left
: Unbounded_Wide_String
;
194 Right
: Wide_String) return Boolean;
198 Right
: Unbounded_Wide_String
) return Boolean;
200 ------------------------
201 -- Search Subprograms --
202 ------------------------
205 (Source
: Unbounded_Wide_String
;
206 Pattern
: Wide_String;
207 Going
: Direction
:= Forward
;
208 Mapping
: Wide_Maps
.Wide_Character_Mapping
:= Wide_Maps
.Identity
)
212 (Source
: Unbounded_Wide_String
;
213 Pattern
: Wide_String;
214 Going
: Direction
:= Forward
;
215 Mapping
: Wide_Maps
.Wide_Character_Mapping_Function
) return Natural;
218 (Source
: Unbounded_Wide_String
;
219 Set
: Wide_Maps
.Wide_Character_Set
;
220 Test
: Membership
:= Inside
;
221 Going
: Direction
:= Forward
) return Natural;
224 (Source
: Unbounded_Wide_String
;
225 Pattern
: Wide_String;
227 Going
: Direction
:= Forward
;
228 Mapping
: Wide_Maps
.Wide_Character_Mapping
:= Wide_Maps
.Identity
)
230 pragma Ada_05
(Index
);
233 (Source
: Unbounded_Wide_String
;
234 Pattern
: Wide_String;
236 Going
: Direction
:= Forward
;
237 Mapping
: Wide_Maps
.Wide_Character_Mapping_Function
) return Natural;
238 pragma Ada_05
(Index
);
241 (Source
: Unbounded_Wide_String
;
242 Set
: Wide_Maps
.Wide_Character_Set
;
244 Test
: Membership
:= Inside
;
245 Going
: Direction
:= Forward
) return Natural;
246 pragma Ada_05
(Index
);
248 function Index_Non_Blank
249 (Source
: Unbounded_Wide_String
;
250 Going
: Direction
:= Forward
) return Natural;
252 function Index_Non_Blank
253 (Source
: Unbounded_Wide_String
;
255 Going
: Direction
:= Forward
) return Natural;
256 pragma Ada_05
(Index_Non_Blank
);
259 (Source
: Unbounded_Wide_String
;
260 Pattern
: Wide_String;
261 Mapping
: Wide_Maps
.Wide_Character_Mapping
:= Wide_Maps
.Identity
)
265 (Source
: Unbounded_Wide_String
;
266 Pattern
: Wide_String;
267 Mapping
: Wide_Maps
.Wide_Character_Mapping_Function
) return Natural;
270 (Source
: Unbounded_Wide_String
;
271 Set
: Wide_Maps
.Wide_Character_Set
) return Natural;
274 (Source
: Unbounded_Wide_String
;
275 Set
: Wide_Maps
.Wide_Character_Set
;
277 First
: out Positive;
280 ------------------------------------
281 -- String Translation Subprograms --
282 ------------------------------------
285 (Source
: Unbounded_Wide_String
;
286 Mapping
: Wide_Maps
.Wide_Character_Mapping
)
287 return Unbounded_Wide_String
;
290 (Source
: in out Unbounded_Wide_String
;
291 Mapping
: Wide_Maps
.Wide_Character_Mapping
);
294 (Source
: Unbounded_Wide_String
;
295 Mapping
: Wide_Maps
.Wide_Character_Mapping_Function
)
296 return Unbounded_Wide_String
;
299 (Source
: in out Unbounded_Wide_String
;
300 Mapping
: Wide_Maps
.Wide_Character_Mapping_Function
);
302 ---------------------------------------
303 -- String Transformation Subprograms --
304 ---------------------------------------
306 function Replace_Slice
307 (Source
: Unbounded_Wide_String
;
310 By
: Wide_String) return Unbounded_Wide_String
;
312 procedure Replace_Slice
313 (Source
: in out Unbounded_Wide_String
;
319 (Source
: Unbounded_Wide_String
;
321 New_Item
: Wide_String) return Unbounded_Wide_String
;
324 (Source
: in out Unbounded_Wide_String
;
326 New_Item
: Wide_String);
329 (Source
: Unbounded_Wide_String
;
331 New_Item
: Wide_String) return Unbounded_Wide_String
;
334 (Source
: in out Unbounded_Wide_String
;
336 New_Item
: Wide_String);
339 (Source
: Unbounded_Wide_String
;
341 Through
: Natural) return Unbounded_Wide_String
;
344 (Source
: in out Unbounded_Wide_String
;
349 (Source
: Unbounded_Wide_String
;
350 Side
: Trim_End
) return Unbounded_Wide_String
;
353 (Source
: in out Unbounded_Wide_String
;
357 (Source
: Unbounded_Wide_String
;
358 Left
: Wide_Maps
.Wide_Character_Set
;
359 Right
: Wide_Maps
.Wide_Character_Set
) return Unbounded_Wide_String
;
362 (Source
: in out Unbounded_Wide_String
;
363 Left
: Wide_Maps
.Wide_Character_Set
;
364 Right
: Wide_Maps
.Wide_Character_Set
);
367 (Source
: Unbounded_Wide_String
;
369 Pad
: Wide_Character := Wide_Space
) return Unbounded_Wide_String
;
372 (Source
: in out Unbounded_Wide_String
;
374 Pad
: Wide_Character := Wide_Space
);
377 (Source
: Unbounded_Wide_String
;
379 Pad
: Wide_Character := Wide_Space
) return Unbounded_Wide_String
;
382 (Source
: in out Unbounded_Wide_String
;
384 Pad
: Wide_Character := Wide_Space
);
388 Right
: Wide_Character) return Unbounded_Wide_String
;
392 Right
: Wide_String) return Unbounded_Wide_String
;
396 Right
: Unbounded_Wide_String
) return Unbounded_Wide_String
;
399 pragma Inline
(Length
);
401 package AF
renames Ada
.Finalization
;
403 type Shared_Wide_String
(Max_Length
: Natural) is limited record
404 Counter
: aliased Interfaces
.Unsigned_32
:= 1;
405 -- Reference counter.
408 Data
: Wide_String (1 .. Max_Length
);
409 -- Last is the index of last significant element of the Data. All
410 -- elements with larger indecies are just an extra room.
413 type Shared_Wide_String_Access
is access all Shared_Wide_String
;
415 procedure Reference
(Item
: not null Shared_Wide_String_Access
);
416 -- Increment reference counter.
418 procedure Unreference
(Item
: not null Shared_Wide_String_Access
);
419 -- Decrement reference counter. Deallocate Item when reference counter is
422 function Can_Be_Reused
423 (Item
: Shared_Wide_String_Access
;
424 Length
: Natural) return Boolean;
425 -- Returns True if Shared_Wide_String can be reused. There are two criteria
426 -- when Shared_Wide_String can be reused: its reference counter must be one
427 -- (thus Shared_Wide_String is owned exclusively) and its size is
428 -- sufficient to store string with specified length effectively.
430 function Allocate
(Max_Length
: Natural) return Shared_Wide_String_Access
;
431 -- Allocates new Shared_Wide_String with at least specified maximum length.
432 -- Actual maximum length of the allocated Shared_Wide_String can be sligtly
433 -- greater. Returns reference to Empty_Shared_Wide_String when requested
436 Empty_Shared_Wide_String
: aliased Shared_Wide_String
(0);
438 function To_Unbounded
(S
: Wide_String) return Unbounded_Wide_String
439 renames To_Unbounded_Wide_String
;
440 -- This renames are here only to be used in the pragma Stream_Convert.
442 type Unbounded_Wide_String
is new AF
.Controlled
with record
443 Reference
: Shared_Wide_String_Access
:= Empty_Shared_Wide_String
'Access;
446 -- The Unbounded_Wide_String uses several techniques to increasy speed of
448 -- - implicit sharing or copy-on-write. Unbounded_Wide_String contains
449 -- only the reference to the data which is shared between several
450 -- instances. The shared data is reallocated only when its value is
451 -- changed and the object mutation can't be used or it is unefficient to
453 -- - object mutation. Shared data object can be reused without memory
454 -- reallocation when all of the following requirements are meat:
455 -- - shared data object don't used anywhere longer;
456 -- - its size is sufficient to store new value;
457 -- - the gap after reuse is less then some threashold.
458 -- - memory preallocation. Most of used memory allocation algorithms
459 -- alligns allocated segment on the some boundary, thus some amount of
460 -- additional memory can be preallocated without any impact. Such
461 -- preallocated memory can used later by Append/Insert operations
462 -- without reallocation.
464 -- Reference counting uses GCC builtin atomic operations, which allows to
465 -- safely share internal data between Ada tasks. Nevertheless, this not
466 -- make objects of Unbounded_Wide_String thread-safe, so each instance
467 -- can't be accessed by several tasks simulatenously.
469 pragma Stream_Convert
(Unbounded_Wide_String
, To_Unbounded
, To_Wide_String
);
470 -- Provide stream routines without dragging in Ada.Streams
472 pragma Finalize_Storage_Only
(Unbounded_Wide_String
);
473 -- Finalization is required only for freeing storage
475 overriding
procedure Initialize
(Object
: in out Unbounded_Wide_String
);
476 overriding
procedure Adjust
(Object
: in out Unbounded_Wide_String
);
477 overriding
procedure Finalize
(Object
: in out Unbounded_Wide_String
);
479 Null_Unbounded_Wide_String
: constant Unbounded_Wide_String
:=
481 Reference
=> Empty_Shared_Wide_String
'Access);
483 end Ada
.Strings
.Wide_Unbounded
;