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-- 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.               --
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
36with Ada.Strings.Maps;
37with Ada.Finalization;
38
39package 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
391private
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);
437end Ada.Strings.Unbounded;
438