1 ------------------------------------------------------------------------------
3 -- GNAT RUN-TIME COMPONENTS --
5 -- A D A . S T R I N G S . B O U N D E D --
9 -- Copyright (C) 1992-2006, 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 with Ada.Strings.Maps;
39 with Ada.Strings.Superbounded;
41 package Ada.Strings.Bounded is
46 -- Maximum length of a Bounded_String
48 package Generic_Bounded_Length is
50 Max_Length : constant Positive := Max;
52 type Bounded_String is private;
53 pragma Preelaborable_Initialization (Bounded_String);
55 Null_Bounded_String : constant Bounded_String;
57 subtype Length_Range is Natural range 0 .. Max_Length;
59 function Length (Source : Bounded_String) return Length_Range;
61 --------------------------------------------------------
62 -- Conversion, Concatenation, and Selection Functions --
63 --------------------------------------------------------
65 function To_Bounded_String
67 Drop : Truncation := Error) return Bounded_String;
69 function To_String (Source : Bounded_String) return String;
71 procedure Set_Bounded_String
72 (Target : out Bounded_String;
74 Drop : Truncation := Error);
75 pragma Ada_05 (Set_Bounded_String);
78 (Left : Bounded_String;
79 Right : Bounded_String;
80 Drop : Truncation := Error) return Bounded_String;
83 (Left : Bounded_String;
85 Drop : Truncation := Error) return Bounded_String;
89 Right : Bounded_String;
90 Drop : Truncation := Error) return Bounded_String;
93 (Left : Bounded_String;
95 Drop : Truncation := Error) return Bounded_String;
99 Right : Bounded_String;
100 Drop : Truncation := Error) return Bounded_String;
103 (Source : in out Bounded_String;
104 New_Item : Bounded_String;
105 Drop : Truncation := Error);
108 (Source : in out Bounded_String;
110 Drop : Truncation := Error);
113 (Source : in out Bounded_String;
114 New_Item : Character;
115 Drop : Truncation := Error);
118 (Left : Bounded_String;
119 Right : Bounded_String) return Bounded_String;
122 (Left : Bounded_String;
123 Right : String) return Bounded_String;
127 Right : Bounded_String) return Bounded_String;
130 (Left : Bounded_String;
131 Right : Character) return Bounded_String;
135 Right : Bounded_String) return Bounded_String;
138 (Source : Bounded_String;
139 Index : Positive) return Character;
141 procedure Replace_Element
142 (Source : in out Bounded_String;
147 (Source : Bounded_String;
149 High : Natural) return String;
151 function Bounded_Slice
152 (Source : Bounded_String;
154 High : Natural) return Bounded_String;
155 pragma Ada_05 (Bounded_Slice);
157 procedure Bounded_Slice
158 (Source : Bounded_String;
159 Target : out Bounded_String;
162 pragma Ada_05 (Bounded_Slice);
165 (Left : Bounded_String;
166 Right : Bounded_String) return Boolean;
169 (Left : Bounded_String;
170 Right : String) return Boolean;
174 Right : Bounded_String) return Boolean;
177 (Left : Bounded_String;
178 Right : Bounded_String) return Boolean;
181 (Left : Bounded_String;
182 Right : String) return Boolean;
186 Right : Bounded_String) return Boolean;
189 (Left : Bounded_String;
190 Right : Bounded_String) return Boolean;
193 (Left : Bounded_String;
194 Right : String) return Boolean;
198 Right : Bounded_String) return Boolean;
201 (Left : Bounded_String;
202 Right : Bounded_String) return Boolean;
205 (Left : Bounded_String;
206 Right : String) return Boolean;
210 Right : Bounded_String) return Boolean;
213 (Left : Bounded_String;
214 Right : Bounded_String) return Boolean;
217 (Left : Bounded_String;
218 Right : String) return Boolean;
222 Right : Bounded_String) return Boolean;
224 ----------------------
225 -- Search Functions --
226 ----------------------
229 (Source : Bounded_String;
231 Going : Direction := Forward;
232 Mapping : Maps.Character_Mapping := Maps.Identity) return Natural;
235 (Source : Bounded_String;
237 Going : Direction := Forward;
238 Mapping : Maps.Character_Mapping_Function) return Natural;
241 (Source : Bounded_String;
242 Set : Maps.Character_Set;
243 Test : Membership := Inside;
244 Going : Direction := Forward) return Natural;
247 (Source : Bounded_String;
250 Going : Direction := Forward;
251 Mapping : Maps.Character_Mapping := Maps.Identity) return Natural;
252 pragma Ada_05 (Index);
255 (Source : Bounded_String;
258 Going : Direction := Forward;
259 Mapping : Maps.Character_Mapping_Function) return Natural;
260 pragma Ada_05 (Index);
263 (Source : Bounded_String;
264 Set : Maps.Character_Set;
266 Test : Membership := Inside;
267 Going : Direction := Forward) return Natural;
268 pragma Ada_05 (Index);
270 function Index_Non_Blank
271 (Source : Bounded_String;
272 Going : Direction := Forward) return Natural;
274 function Index_Non_Blank
275 (Source : Bounded_String;
277 Going : Direction := Forward) return Natural;
278 pragma Ada_05 (Index_Non_Blank);
281 (Source : Bounded_String;
283 Mapping : Maps.Character_Mapping := Maps.Identity) return Natural;
286 (Source : Bounded_String;
288 Mapping : Maps.Character_Mapping_Function) return Natural;
291 (Source : Bounded_String;
292 Set : Maps.Character_Set) return Natural;
295 (Source : Bounded_String;
296 Set : Maps.Character_Set;
298 First : out Positive;
301 ------------------------------------
302 -- String Translation Subprograms --
303 ------------------------------------
306 (Source : Bounded_String;
307 Mapping : Maps.Character_Mapping) return Bounded_String;
310 (Source : in out Bounded_String;
311 Mapping : Maps.Character_Mapping);
314 (Source : Bounded_String;
315 Mapping : Maps.Character_Mapping_Function) return Bounded_String;
318 (Source : in out Bounded_String;
319 Mapping : Maps.Character_Mapping_Function);
321 ---------------------------------------
322 -- String Transformation Subprograms --
323 ---------------------------------------
325 function Replace_Slice
326 (Source : Bounded_String;
330 Drop : Truncation := Error) return Bounded_String;
332 procedure Replace_Slice
333 (Source : in out Bounded_String;
337 Drop : Truncation := Error);
340 (Source : Bounded_String;
343 Drop : Truncation := Error) return Bounded_String;
346 (Source : in out Bounded_String;
349 Drop : Truncation := Error);
352 (Source : Bounded_String;
355 Drop : Truncation := Error) return Bounded_String;
358 (Source : in out Bounded_String;
361 Drop : Truncation := Error);
364 (Source : Bounded_String;
366 Through : Natural) return Bounded_String;
369 (Source : in out Bounded_String;
373 ---------------------------------
374 -- String Selector Subprograms --
375 ---------------------------------
378 (Source : Bounded_String;
379 Side : Trim_End) return Bounded_String;
382 (Source : in out Bounded_String;
386 (Source : Bounded_String;
387 Left : Maps.Character_Set;
388 Right : Maps.Character_Set) return Bounded_String;
391 (Source : in out Bounded_String;
392 Left : Maps.Character_Set;
393 Right : Maps.Character_Set);
396 (Source : Bounded_String;
398 Pad : Character := Space;
399 Drop : Truncation := Error) return Bounded_String;
402 (Source : in out Bounded_String;
404 Pad : Character := Space;
405 Drop : Truncation := Error);
408 (Source : Bounded_String;
410 Pad : Character := Space;
411 Drop : Truncation := Error) return Bounded_String;
414 (Source : in out Bounded_String;
416 Pad : Character := Space;
417 Drop : Truncation := Error);
419 ------------------------------------
420 -- String Constructor Subprograms --
421 ------------------------------------
425 Right : Character) return Bounded_String;
429 Right : String) return Bounded_String;
433 Right : Bounded_String) return Bounded_String;
438 Drop : Truncation := Error) return Bounded_String;
443 Drop : Truncation := Error) return Bounded_String;
447 Item : Bounded_String;
448 Drop : Truncation := Error) return Bounded_String;
451 -- Most of the implementation is in the separate non generic package
452 -- Ada.Strings.Superbounded. Type Bounded_String is derived from type
453 -- Superbounded.Super_String with the maximum length constraint. In
454 -- almost all cases, the routines in Superbounded can be called with
455 -- no requirement to pass the maximum length explicitly, since there
456 -- is at least one Bounded_String argument from which the maximum
457 -- length can be obtained. For all such routines, the implementation
458 -- in this private part is simply a renaming of the corresponding
459 -- routine in the super bouded package.
461 -- The five exceptions are the * and Replicate routines operating on
462 -- character values. For these cases, we have a routine in the body
463 -- that calls the superbounded routine passing the maximum length
464 -- explicitly as an extra parameter.
466 type Bounded_String is new Superbounded.Super_String (Max_Length);
467 -- Deriving Bounded_String from Superbounded.Super_String is the
468 -- real trick, it ensures that the type Bounded_String declared in
469 -- the generic instantiation is compatible with the Super_String
470 -- type declared in the Superbounded package.
472 Null_Bounded_String : constant Bounded_String :=
473 (Max_Length => Max_Length,
476 (1 .. Max_Length => ASCII.NUL));
478 pragma Inline (To_Bounded_String);
480 procedure Set_Bounded_String
481 (Target : out Bounded_String;
483 Drop : Truncation := Error)
484 renames Set_Super_String;
487 (Source : Bounded_String) return Length_Range
488 renames Super_Length;
491 (Source : Bounded_String) return String
492 renames Super_To_String;
495 (Left : Bounded_String;
496 Right : Bounded_String;
497 Drop : Truncation := Error) return Bounded_String
498 renames Super_Append;
501 (Left : Bounded_String;
503 Drop : Truncation := Error) return Bounded_String
504 renames Super_Append;
508 Right : Bounded_String;
509 Drop : Truncation := Error) return Bounded_String
510 renames Super_Append;
513 (Left : Bounded_String;
515 Drop : Truncation := Error) return Bounded_String
516 renames Super_Append;
520 Right : Bounded_String;
521 Drop : Truncation := Error) return Bounded_String
522 renames Super_Append;
525 (Source : in out Bounded_String;
526 New_Item : Bounded_String;
527 Drop : Truncation := Error)
528 renames Super_Append;
531 (Source : in out Bounded_String;
533 Drop : Truncation := Error)
534 renames Super_Append;
537 (Source : in out Bounded_String;
538 New_Item : Character;
539 Drop : Truncation := Error)
540 renames Super_Append;
543 (Left : Bounded_String;
544 Right : Bounded_String) return Bounded_String
548 (Left : Bounded_String;
549 Right : String) return Bounded_String
554 Right : Bounded_String) return Bounded_String
558 (Left : Bounded_String;
559 Right : Character) return Bounded_String
564 Right : Bounded_String) return Bounded_String
568 (Source : Bounded_String;
569 Index : Positive) return Character
570 renames Super_Element;
572 procedure Replace_Element
573 (Source : in out Bounded_String;
576 renames Super_Replace_Element;
579 (Source : Bounded_String;
581 High : Natural) return String
584 function Bounded_Slice
585 (Source : Bounded_String;
587 High : Natural) return Bounded_String
590 procedure Bounded_Slice
591 (Source : Bounded_String;
592 Target : out Bounded_String;
598 (Left : Bounded_String;
599 Right : Bounded_String) return Boolean
603 (Left : Bounded_String;
604 Right : String) return Boolean
609 Right : Bounded_String) return Boolean
613 (Left : Bounded_String;
614 Right : Bounded_String) return Boolean
618 (Left : Bounded_String;
619 Right : String) return Boolean
624 Right : Bounded_String) return Boolean
628 (Left : Bounded_String;
629 Right : Bounded_String) return Boolean
630 renames Less_Or_Equal;
633 (Left : Bounded_String;
634 Right : String) return Boolean
635 renames Less_Or_Equal;
639 Right : Bounded_String) return Boolean
640 renames Less_Or_Equal;
643 (Left : Bounded_String;
644 Right : Bounded_String) return Boolean
648 (Left : Bounded_String;
649 Right : String) return Boolean
654 Right : Bounded_String) return Boolean
658 (Left : Bounded_String;
659 Right : Bounded_String) return Boolean
660 renames Greater_Or_Equal;
663 (Left : Bounded_String;
664 Right : String) return Boolean
665 renames Greater_Or_Equal;
669 Right : Bounded_String) return Boolean
670 renames Greater_Or_Equal;
673 (Source : Bounded_String;
675 Going : Direction := Forward;
676 Mapping : Maps.Character_Mapping := Maps.Identity) return Natural
680 (Source : Bounded_String;
682 Going : Direction := Forward;
683 Mapping : Maps.Character_Mapping_Function) return Natural
687 (Source : Bounded_String;
688 Set : Maps.Character_Set;
689 Test : Membership := Inside;
690 Going : Direction := Forward) return Natural
694 (Source : Bounded_String;
697 Going : Direction := Forward;
698 Mapping : Maps.Character_Mapping := Maps.Identity) return Natural
702 (Source : Bounded_String;
705 Going : Direction := Forward;
706 Mapping : Maps.Character_Mapping_Function) return Natural
710 (Source : Bounded_String;
711 Set : Maps.Character_Set;
713 Test : Membership := Inside;
714 Going : Direction := Forward) return Natural
717 function Index_Non_Blank
718 (Source : Bounded_String;
719 Going : Direction := Forward) return Natural
720 renames Super_Index_Non_Blank;
722 function Index_Non_Blank
723 (Source : Bounded_String;
725 Going : Direction := Forward) return Natural
726 renames Super_Index_Non_Blank;
729 (Source : Bounded_String;
731 Mapping : Maps.Character_Mapping := Maps.Identity) return Natural
735 (Source : Bounded_String;
737 Mapping : Maps.Character_Mapping_Function) return Natural
741 (Source : Bounded_String;
742 Set : Maps.Character_Set) return Natural
746 (Source : Bounded_String;
747 Set : Maps.Character_Set;
749 First : out Positive;
751 renames Super_Find_Token;
754 (Source : Bounded_String;
755 Mapping : Maps.Character_Mapping) return Bounded_String
756 renames Super_Translate;
759 (Source : in out Bounded_String;
760 Mapping : Maps.Character_Mapping)
761 renames Super_Translate;
764 (Source : Bounded_String;
765 Mapping : Maps.Character_Mapping_Function) return Bounded_String
766 renames Super_Translate;
769 (Source : in out Bounded_String;
770 Mapping : Maps.Character_Mapping_Function)
771 renames Super_Translate;
773 function Replace_Slice
774 (Source : Bounded_String;
778 Drop : Truncation := Error) return Bounded_String
779 renames Super_Replace_Slice;
781 procedure Replace_Slice
782 (Source : in out Bounded_String;
786 Drop : Truncation := Error)
787 renames Super_Replace_Slice;
790 (Source : Bounded_String;
793 Drop : Truncation := Error) return Bounded_String
794 renames Super_Insert;
797 (Source : in out Bounded_String;
800 Drop : Truncation := Error)
801 renames Super_Insert;
804 (Source : Bounded_String;
807 Drop : Truncation := Error) return Bounded_String
808 renames Super_Overwrite;
811 (Source : in out Bounded_String;
814 Drop : Truncation := Error)
815 renames Super_Overwrite;
818 (Source : Bounded_String;
820 Through : Natural) return Bounded_String
821 renames Super_Delete;
824 (Source : in out Bounded_String;
827 renames Super_Delete;
830 (Source : Bounded_String;
831 Side : Trim_End) return Bounded_String
835 (Source : in out Bounded_String;
840 (Source : Bounded_String;
841 Left : Maps.Character_Set;
842 Right : Maps.Character_Set) return Bounded_String
846 (Source : in out Bounded_String;
847 Left : Maps.Character_Set;
848 Right : Maps.Character_Set)
852 (Source : Bounded_String;
854 Pad : Character := Space;
855 Drop : Truncation := Error) return Bounded_String
859 (Source : in out Bounded_String;
861 Pad : Character := Space;
862 Drop : Truncation := Error)
866 (Source : Bounded_String;
868 Pad : Character := Space;
869 Drop : Truncation := Error) return Bounded_String
873 (Source : in out Bounded_String;
875 Pad : Character := Space;
876 Drop : Truncation := Error)
881 Right : Bounded_String) return Bounded_String
886 Item : Bounded_String;
887 Drop : Truncation := Error) return Bounded_String
888 renames Super_Replicate;
890 end Generic_Bounded_Length;
892 end Ada.Strings.Bounded;