fixing pr42337
[official-gcc.git] / gcc / ada / a-strunb.ads
blobe61bae50a5a4625c329d7ee999778dc9cc6993c3
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-2009, 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 ------------------------------------------------------------------------------
36 with Ada.Strings.Maps;
37 with Ada.Finalization;
39 package Ada.Strings.Unbounded is
40 pragma Preelaborate;
42 type Unbounded_String is private;
43 pragma Preelaborable_Initialization (Unbounded_String);
45 Null_Unbounded_String : constant Unbounded_String;
47 function Length (Source : Unbounded_String) return Natural;
49 type String_Access is access all String;
51 procedure Free (X : in out String_Access);
53 --------------------------------------------------------
54 -- Conversion, Concatenation, and Selection Functions --
55 --------------------------------------------------------
57 function To_Unbounded_String
58 (Source : String) return Unbounded_String;
60 function To_Unbounded_String
61 (Length : Natural) return Unbounded_String;
63 function To_String (Source : Unbounded_String) return String;
65 procedure Set_Unbounded_String
66 (Target : out Unbounded_String;
67 Source : String);
68 pragma Ada_05 (Set_Unbounded_String);
70 procedure Append
71 (Source : in out Unbounded_String;
72 New_Item : Unbounded_String);
74 procedure Append
75 (Source : in out Unbounded_String;
76 New_Item : String);
78 procedure Append
79 (Source : in out Unbounded_String;
80 New_Item : Character);
82 function "&"
83 (Left : Unbounded_String;
84 Right : Unbounded_String) return Unbounded_String;
86 function "&"
87 (Left : Unbounded_String;
88 Right : String) return Unbounded_String;
90 function "&"
91 (Left : String;
92 Right : Unbounded_String) return Unbounded_String;
94 function "&"
95 (Left : Unbounded_String;
96 Right : Character) return Unbounded_String;
98 function "&"
99 (Left : Character;
100 Right : Unbounded_String) return Unbounded_String;
102 function Element
103 (Source : Unbounded_String;
104 Index : Positive) return Character;
106 procedure Replace_Element
107 (Source : in out Unbounded_String;
108 Index : Positive;
109 By : Character);
111 function Slice
112 (Source : Unbounded_String;
113 Low : Positive;
114 High : Natural) return String;
116 function Unbounded_Slice
117 (Source : Unbounded_String;
118 Low : Positive;
119 High : Natural) return Unbounded_String;
120 pragma Ada_05 (Unbounded_Slice);
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);
129 function "="
130 (Left : Unbounded_String;
131 Right : Unbounded_String) return Boolean;
133 function "="
134 (Left : Unbounded_String;
135 Right : String) return Boolean;
137 function "="
138 (Left : String;
139 Right : Unbounded_String) return Boolean;
141 function "<"
142 (Left : Unbounded_String;
143 Right : Unbounded_String) return Boolean;
145 function "<"
146 (Left : Unbounded_String;
147 Right : String) return Boolean;
149 function "<"
150 (Left : String;
151 Right : Unbounded_String) return Boolean;
153 function "<="
154 (Left : Unbounded_String;
155 Right : Unbounded_String) return Boolean;
157 function "<="
158 (Left : Unbounded_String;
159 Right : String) return Boolean;
161 function "<="
162 (Left : String;
163 Right : Unbounded_String) return Boolean;
165 function ">"
166 (Left : Unbounded_String;
167 Right : Unbounded_String) return Boolean;
169 function ">"
170 (Left : Unbounded_String;
171 Right : String) return Boolean;
173 function ">"
174 (Left : String;
175 Right : Unbounded_String) return Boolean;
177 function ">="
178 (Left : Unbounded_String;
179 Right : Unbounded_String) return Boolean;
181 function ">="
182 (Left : Unbounded_String;
183 Right : String) return Boolean;
185 function ">="
186 (Left : String;
187 Right : Unbounded_String) return Boolean;
189 ------------------------
190 -- Search Subprograms --
191 ------------------------
193 function Index
194 (Source : Unbounded_String;
195 Pattern : String;
196 Going : Direction := Forward;
197 Mapping : Maps.Character_Mapping := Maps.Identity) return Natural;
199 function Index
200 (Source : Unbounded_String;
201 Pattern : String;
202 Going : Direction := Forward;
203 Mapping : Maps.Character_Mapping_Function) return Natural;
205 function Index
206 (Source : Unbounded_String;
207 Set : Maps.Character_Set;
208 Test : Membership := Inside;
209 Going : Direction := Forward) return Natural;
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);
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);
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);
235 function Index_Non_Blank
236 (Source : Unbounded_String;
237 Going : Direction := Forward) return Natural;
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);
245 function Count
246 (Source : Unbounded_String;
247 Pattern : String;
248 Mapping : Maps.Character_Mapping := Maps.Identity) return Natural;
250 function Count
251 (Source : Unbounded_String;
252 Pattern : String;
253 Mapping : Maps.Character_Mapping_Function) return Natural;
255 function Count
256 (Source : Unbounded_String;
257 Set : Maps.Character_Set) return Natural;
259 procedure Find_Token
260 (Source : Unbounded_String;
261 Set : Maps.Character_Set;
262 Test : Membership;
263 First : out Positive;
264 Last : out Natural);
266 ------------------------------------
267 -- String Translation Subprograms --
268 ------------------------------------
270 function Translate
271 (Source : Unbounded_String;
272 Mapping : Maps.Character_Mapping) return Unbounded_String;
274 procedure Translate
275 (Source : in out Unbounded_String;
276 Mapping : Maps.Character_Mapping);
278 function Translate
279 (Source : Unbounded_String;
280 Mapping : Maps.Character_Mapping_Function) return Unbounded_String;
282 procedure Translate
283 (Source : in out Unbounded_String;
284 Mapping : Maps.Character_Mapping_Function);
286 ---------------------------------------
287 -- String Transformation Subprograms --
288 ---------------------------------------
290 function Replace_Slice
291 (Source : Unbounded_String;
292 Low : Positive;
293 High : Natural;
294 By : String) return Unbounded_String;
296 procedure Replace_Slice
297 (Source : in out Unbounded_String;
298 Low : Positive;
299 High : Natural;
300 By : String);
302 function Insert
303 (Source : Unbounded_String;
304 Before : Positive;
305 New_Item : String) return Unbounded_String;
307 procedure Insert
308 (Source : in out Unbounded_String;
309 Before : Positive;
310 New_Item : String);
312 function Overwrite
313 (Source : Unbounded_String;
314 Position : Positive;
315 New_Item : String) return Unbounded_String;
317 procedure Overwrite
318 (Source : in out Unbounded_String;
319 Position : Positive;
320 New_Item : String);
322 function Delete
323 (Source : Unbounded_String;
324 From : Positive;
325 Through : Natural) return Unbounded_String;
327 procedure Delete
328 (Source : in out Unbounded_String;
329 From : Positive;
330 Through : Natural);
332 function Trim
333 (Source : Unbounded_String;
334 Side : Trim_End) return Unbounded_String;
336 procedure Trim
337 (Source : in out Unbounded_String;
338 Side : Trim_End);
340 function Trim
341 (Source : Unbounded_String;
342 Left : Maps.Character_Set;
343 Right : Maps.Character_Set) return Unbounded_String;
345 procedure Trim
346 (Source : in out Unbounded_String;
347 Left : Maps.Character_Set;
348 Right : Maps.Character_Set);
350 function Head
351 (Source : Unbounded_String;
352 Count : Natural;
353 Pad : Character := Space) return Unbounded_String;
355 procedure Head
356 (Source : in out Unbounded_String;
357 Count : Natural;
358 Pad : Character := Space);
360 function Tail
361 (Source : Unbounded_String;
362 Count : Natural;
363 Pad : Character := Space) return Unbounded_String;
365 procedure Tail
366 (Source : in out Unbounded_String;
367 Count : Natural;
368 Pad : Character := Space);
370 function "*"
371 (Left : Natural;
372 Right : Character) return Unbounded_String;
374 function "*"
375 (Left : Natural;
376 Right : String) return Unbounded_String;
378 function "*"
379 (Left : Natural;
380 Right : Unbounded_String) return Unbounded_String;
382 private
383 pragma Inline (Length);
385 package AF renames Ada.Finalization;
387 Null_String : aliased String := "";
389 function To_Unbounded (S : String) return Unbounded_String
390 renames To_Unbounded_String;
392 type Unbounded_String is new AF.Controlled with record
393 Reference : String_Access := Null_String'Access;
394 Last : Natural := 0;
395 end record;
396 -- The Unbounded_String is using a buffered implementation to increase
397 -- speed of the Append/Delete/Insert procedures. The Reference string
398 -- pointer above contains the current string value and extra room at the
399 -- end to be used by the next Append routine. Last is the index of the
400 -- string ending character. So the current string value is really
401 -- Reference (1 .. Last).
403 pragma Stream_Convert (Unbounded_String, To_Unbounded, To_String);
404 -- Provide stream routines without dragging in Ada.Streams
406 pragma Finalize_Storage_Only (Unbounded_String);
407 -- Finalization is required only for freeing storage
409 procedure Initialize (Object : in out Unbounded_String);
410 procedure Adjust (Object : in out Unbounded_String);
411 procedure Finalize (Object : in out Unbounded_String);
413 procedure Realloc_For_Chunk
414 (Source : in out Unbounded_String;
415 Chunk_Size : Natural);
416 pragma Inline (Realloc_For_Chunk);
417 -- Adjust the size allocated for the string. Add at least Chunk_Size so it
418 -- is safe to add a string of this size at the end of the current content.
419 -- The real size allocated for the string is Chunk_Size + x of the current
420 -- string size. This buffered handling makes the Append unbounded string
421 -- routines very fast. This spec is in the private part so that it can be
422 -- accessed from children (e.g. from Unbounded.Text_IO).
424 Null_Unbounded_String : constant Unbounded_String :=
425 (AF.Controlled with
426 Reference => Null_String'Access,
427 Last => 0);
428 end Ada.Strings.Unbounded;