1------------------------------------------------------------------------------
2--                                                                          --
3--                          GNAT RUNTIME 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-2002 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 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,  59 Temple Place - Suite 330,  Boston, --
24-- MA 02111-1307, USA.                                                      --
25--                                                                          --
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.                                      --
32--                                                                          --
33-- GNAT was originally developed  by the GNAT team at  New York University. --
34-- Extensive contributions were provided by Ada Core Technologies Inc.      --
35--                                                                          --
36------------------------------------------------------------------------------
37
38with Ada.Strings.Maps;
39with Ada.Finalization;
40
41package Ada.Strings.Unbounded is
42pragma Preelaborate (Unbounded);
43
44   type Unbounded_String is private;
45
46   Null_Unbounded_String : constant Unbounded_String;
47
48   function Length (Source : Unbounded_String) return Natural;
49
50   type String_Access is access all String;
51
52   procedure Free (X : in out String_Access);
53
54   --------------------------------------------------------
55   -- Conversion, Concatenation, and Selection Functions --
56   --------------------------------------------------------
57
58   function To_Unbounded_String (Source : String)     return Unbounded_String;
59   function To_Unbounded_String (Length : in Natural) return Unbounded_String;
60
61   function To_String (Source : Unbounded_String) return String;
62
63   procedure Append
64     (Source   : in out Unbounded_String;
65      New_Item : in Unbounded_String);
66
67   procedure Append
68     (Source   : in out Unbounded_String;
69      New_Item : in String);
70
71   procedure Append
72     (Source   : in out Unbounded_String;
73      New_Item : in Character);
74
75   function "&" (Left, Right : Unbounded_String) return Unbounded_String;
76
77   function "&"
78     (Left  : in Unbounded_String;
79      Right : in String)
80      return  Unbounded_String;
81
82   function "&"
83     (Left  : in String;
84      Right : in Unbounded_String)
85      return  Unbounded_String;
86
87   function "&"
88     (Left  : in Unbounded_String;
89      Right : in Character)
90      return  Unbounded_String;
91
92   function "&"
93     (Left  : in Character;
94      Right : in Unbounded_String)
95      return  Unbounded_String;
96
97   function Element
98     (Source : in Unbounded_String;
99      Index  : in Positive)
100      return   Character;
101
102   procedure Replace_Element
103     (Source : in out Unbounded_String;
104      Index  : in Positive;
105      By     : Character);
106
107   function Slice
108     (Source : in Unbounded_String;
109      Low    : in Positive;
110      High   : in Natural)
111      return   String;
112
113   function "=" (Left, Right : in Unbounded_String) return Boolean;
114
115   function "="
116     (Left  : in Unbounded_String;
117      Right : in String)
118      return  Boolean;
119
120   function "="
121     (Left  : in String;
122      Right : in Unbounded_String)
123      return  Boolean;
124
125   function "<" (Left, Right : in Unbounded_String) return Boolean;
126
127   function "<"
128     (Left  : in Unbounded_String;
129      Right : in String)
130      return  Boolean;
131
132   function "<"
133     (Left  : in String;
134      Right : in Unbounded_String)
135      return  Boolean;
136
137   function "<=" (Left, Right : in Unbounded_String) return Boolean;
138
139   function "<="
140     (Left  : in Unbounded_String;
141      Right : in String)
142      return  Boolean;
143
144   function "<="
145     (Left  : in String;
146      Right : in Unbounded_String)
147      return  Boolean;
148
149   function ">" (Left, Right : in Unbounded_String) return Boolean;
150
151   function ">"
152     (Left  : in Unbounded_String;
153      Right : in String)
154      return  Boolean;
155
156   function ">"
157     (Left  : in String;
158      Right : in Unbounded_String)
159      return  Boolean;
160
161   function ">=" (Left, Right : in Unbounded_String) return Boolean;
162
163   function ">="
164     (Left  : in Unbounded_String;
165      Right : in String)
166      return  Boolean;
167
168   function ">="
169     (Left  : in String;
170      Right : in Unbounded_String)
171      return  Boolean;
172
173   ------------------------
174   -- Search Subprograms --
175   ------------------------
176
177   function Index
178     (Source   : in Unbounded_String;
179      Pattern  : in String;
180      Going    : in Direction := Forward;
181      Mapping  : in Maps.Character_Mapping := Maps.Identity)
182      return     Natural;
183
184   function Index
185     (Source   : in Unbounded_String;
186      Pattern  : in String;
187      Going    : in Direction := Forward;
188      Mapping  : in Maps.Character_Mapping_Function)
189      return     Natural;
190
191   function Index
192     (Source : in Unbounded_String;
193      Set    : in Maps.Character_Set;
194      Test   : in Membership := Inside;
195      Going  : in Direction  := Forward)
196      return   Natural;
197
198   function Index_Non_Blank
199     (Source : in Unbounded_String;
200      Going  : in Direction := Forward)
201      return   Natural;
202
203   function Count
204     (Source  : in Unbounded_String;
205      Pattern : in String;
206      Mapping : in Maps.Character_Mapping := Maps.Identity)
207      return    Natural;
208
209   function Count
210     (Source   : in Unbounded_String;
211      Pattern  : in String;
212      Mapping  : in Maps.Character_Mapping_Function)
213      return     Natural;
214
215   function Count
216     (Source : in Unbounded_String;
217      Set    : in Maps.Character_Set)
218      return   Natural;
219
220   procedure Find_Token
221     (Source : in Unbounded_String;
222      Set    : in Maps.Character_Set;
223      Test   : in Membership;
224      First  : out Positive;
225      Last   : out Natural);
226
227   ------------------------------------
228   -- String Translation Subprograms --
229   ------------------------------------
230
231   function Translate
232     (Source  : in Unbounded_String;
233      Mapping : in Maps.Character_Mapping)
234      return    Unbounded_String;
235
236   procedure Translate
237     (Source  : in out Unbounded_String;
238      Mapping : Maps.Character_Mapping);
239
240   function Translate
241     (Source  : in Unbounded_String;
242      Mapping : in Maps.Character_Mapping_Function)
243      return    Unbounded_String;
244
245   procedure Translate
246     (Source  : in out Unbounded_String;
247      Mapping : in Maps.Character_Mapping_Function);
248
249   ---------------------------------------
250   -- String Transformation Subprograms --
251   ---------------------------------------
252
253   function Replace_Slice
254     (Source : in Unbounded_String;
255      Low    : in Positive;
256      High   : in Natural;
257      By     : in String)
258      return   Unbounded_String;
259
260   procedure Replace_Slice
261     (Source   : in out Unbounded_String;
262      Low      : in Positive;
263      High     : in Natural;
264      By       : in String);
265
266   function Insert
267     (Source   : in Unbounded_String;
268      Before   : in Positive;
269      New_Item : in String)
270      return     Unbounded_String;
271
272   procedure Insert
273     (Source   : in out Unbounded_String;
274      Before   : in Positive;
275      New_Item : in String);
276
277   function Overwrite
278     (Source   : in Unbounded_String;
279      Position : in Positive;
280      New_Item : in String)
281      return     Unbounded_String;
282
283   procedure Overwrite
284     (Source    : in out Unbounded_String;
285      Position  : in Positive;
286      New_Item  : in String);
287
288   function Delete
289     (Source  : in Unbounded_String;
290      From    : in Positive;
291      Through : in Natural)
292      return    Unbounded_String;
293
294   procedure Delete
295     (Source  : in out Unbounded_String;
296      From    : in Positive;
297      Through : in Natural);
298
299   function Trim
300     (Source : in Unbounded_String;
301      Side   : in Trim_End)
302      return   Unbounded_String;
303
304   procedure Trim
305     (Source : in out Unbounded_String;
306      Side   : in Trim_End);
307
308   function Trim
309     (Source : in Unbounded_String;
310      Left   : in Maps.Character_Set;
311      Right  : in Maps.Character_Set)
312      return   Unbounded_String;
313
314   procedure Trim
315     (Source : in out Unbounded_String;
316      Left   : in Maps.Character_Set;
317      Right  : in Maps.Character_Set);
318
319   function Head
320     (Source : in Unbounded_String;
321      Count  : in Natural;
322      Pad    : in Character := Space)
323      return   Unbounded_String;
324
325   procedure Head
326     (Source : in out Unbounded_String;
327      Count  : in Natural;
328      Pad    : in Character := Space);
329
330   function Tail
331     (Source : in Unbounded_String;
332      Count  : in Natural;
333      Pad    : in Character := Space)
334      return   Unbounded_String;
335
336   procedure Tail
337     (Source : in out Unbounded_String;
338      Count  : in Natural;
339      Pad    : in Character := Space);
340
341   function "*"
342     (Left  : in Natural;
343      Right : in Character)
344      return  Unbounded_String;
345
346   function "*"
347     (Left  : in Natural;
348      Right : in String)
349      return  Unbounded_String;
350
351   function "*"
352     (Left  : in Natural;
353      Right : in Unbounded_String)
354      return  Unbounded_String;
355
356private
357   pragma Inline (Length);
358
359   package AF renames Ada.Finalization;
360
361   Null_String : aliased String := "";
362
363   function To_Unbounded (S : String) return Unbounded_String
364     renames To_Unbounded_String;
365
366   type Unbounded_String is new AF.Controlled with record
367      Reference : String_Access := Null_String'Access;
368      Last      : Natural       := 0;
369   end record;
370
371   --  The Unbounded_String is using a buffered implementation to increase
372   --  speed of the Append/Delete/Insert procedures. The Reference string
373   --  pointer above contains the current string value and extra room at the
374   --  end to be used by the next Append routine. Last is the index of the
375   --  string ending character. So the current string value is really
376   --  Reference (1 .. Last).
377
378   pragma Stream_Convert (Unbounded_String, To_Unbounded, To_String);
379
380   pragma Finalize_Storage_Only (Unbounded_String);
381
382   procedure Initialize (Object : in out Unbounded_String);
383   procedure Adjust     (Object : in out Unbounded_String);
384   procedure Finalize   (Object : in out Unbounded_String);
385
386   --  Note: the following declaration is illegal since library level
387   --  controlled objects are not allowed in preelaborated units. See
388   --  AI-161 for a discussion of this issue and an attempt to address it.
389   --  Meanwhile, what happens in GNAT is that this check is omitted for
390   --  internal implementation units (see check in sem_cat.adb).
391
392   Null_Unbounded_String : constant Unbounded_String :=
393     (AF.Controlled with Reference => Null_String'Access, Last => 0);
394
395end Ada.Strings.Unbounded;
396