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-2008, 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 superbounded 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 function From_String (Source : String) return Bounded_String;
473 -- Private routine used only by Stream_Convert
475 pragma Stream_Convert (Bounded_String, From_String, To_String);
476 -- Provide stream routines without dragging in Ada.Streams
478 Null_Bounded_String : constant Bounded_String :=
479 (Max_Length => Max_Length,
482 (1 .. Max_Length => ASCII.NUL));
484 pragma Inline (To_Bounded_String);
486 procedure Set_Bounded_String
487 (Target : out Bounded_String;
489 Drop : Truncation := Error)
490 renames Set_Super_String;
493 (Source : Bounded_String) return Length_Range
494 renames Super_Length;
497 (Source : Bounded_String) return String
498 renames Super_To_String;
501 (Left : Bounded_String;
502 Right : Bounded_String;
503 Drop : Truncation := Error) return Bounded_String
504 renames Super_Append;
507 (Left : Bounded_String;
509 Drop : Truncation := Error) return Bounded_String
510 renames Super_Append;
514 Right : Bounded_String;
515 Drop : Truncation := Error) return Bounded_String
516 renames Super_Append;
519 (Left : Bounded_String;
521 Drop : Truncation := Error) return Bounded_String
522 renames Super_Append;
526 Right : Bounded_String;
527 Drop : Truncation := Error) return Bounded_String
528 renames Super_Append;
531 (Source : in out Bounded_String;
532 New_Item : Bounded_String;
533 Drop : Truncation := Error)
534 renames Super_Append;
537 (Source : in out Bounded_String;
539 Drop : Truncation := Error)
540 renames Super_Append;
543 (Source : in out Bounded_String;
544 New_Item : Character;
545 Drop : Truncation := Error)
546 renames Super_Append;
549 (Left : Bounded_String;
550 Right : Bounded_String) return Bounded_String
554 (Left : Bounded_String;
555 Right : String) return Bounded_String
560 Right : Bounded_String) return Bounded_String
564 (Left : Bounded_String;
565 Right : Character) return Bounded_String
570 Right : Bounded_String) return Bounded_String
574 (Source : Bounded_String;
575 Index : Positive) return Character
576 renames Super_Element;
578 procedure Replace_Element
579 (Source : in out Bounded_String;
582 renames Super_Replace_Element;
585 (Source : Bounded_String;
587 High : Natural) return String
590 function Bounded_Slice
591 (Source : Bounded_String;
593 High : Natural) return Bounded_String
596 procedure Bounded_Slice
597 (Source : Bounded_String;
598 Target : out Bounded_String;
604 (Left : Bounded_String;
605 Right : Bounded_String) return Boolean
609 (Left : Bounded_String;
610 Right : String) return Boolean
615 Right : Bounded_String) return Boolean
619 (Left : Bounded_String;
620 Right : Bounded_String) return Boolean
624 (Left : Bounded_String;
625 Right : String) return Boolean
630 Right : Bounded_String) return Boolean
634 (Left : Bounded_String;
635 Right : Bounded_String) return Boolean
636 renames Less_Or_Equal;
639 (Left : Bounded_String;
640 Right : String) return Boolean
641 renames Less_Or_Equal;
645 Right : Bounded_String) return Boolean
646 renames Less_Or_Equal;
649 (Left : Bounded_String;
650 Right : Bounded_String) return Boolean
654 (Left : Bounded_String;
655 Right : String) return Boolean
660 Right : Bounded_String) return Boolean
664 (Left : Bounded_String;
665 Right : Bounded_String) return Boolean
666 renames Greater_Or_Equal;
669 (Left : Bounded_String;
670 Right : String) return Boolean
671 renames Greater_Or_Equal;
675 Right : Bounded_String) return Boolean
676 renames Greater_Or_Equal;
679 (Source : Bounded_String;
681 Going : Direction := Forward;
682 Mapping : Maps.Character_Mapping := Maps.Identity) return Natural
686 (Source : Bounded_String;
688 Going : Direction := Forward;
689 Mapping : Maps.Character_Mapping_Function) return Natural
693 (Source : Bounded_String;
694 Set : Maps.Character_Set;
695 Test : Membership := Inside;
696 Going : Direction := Forward) return Natural
700 (Source : Bounded_String;
703 Going : Direction := Forward;
704 Mapping : Maps.Character_Mapping := Maps.Identity) return Natural
708 (Source : Bounded_String;
711 Going : Direction := Forward;
712 Mapping : Maps.Character_Mapping_Function) return Natural
716 (Source : Bounded_String;
717 Set : Maps.Character_Set;
719 Test : Membership := Inside;
720 Going : Direction := Forward) return Natural
723 function Index_Non_Blank
724 (Source : Bounded_String;
725 Going : Direction := Forward) return Natural
726 renames Super_Index_Non_Blank;
728 function Index_Non_Blank
729 (Source : Bounded_String;
731 Going : Direction := Forward) return Natural
732 renames Super_Index_Non_Blank;
735 (Source : Bounded_String;
737 Mapping : Maps.Character_Mapping := Maps.Identity) return Natural
741 (Source : Bounded_String;
743 Mapping : Maps.Character_Mapping_Function) return Natural
747 (Source : Bounded_String;
748 Set : Maps.Character_Set) return Natural
752 (Source : Bounded_String;
753 Set : Maps.Character_Set;
755 First : out Positive;
757 renames Super_Find_Token;
760 (Source : Bounded_String;
761 Mapping : Maps.Character_Mapping) return Bounded_String
762 renames Super_Translate;
765 (Source : in out Bounded_String;
766 Mapping : Maps.Character_Mapping)
767 renames Super_Translate;
770 (Source : Bounded_String;
771 Mapping : Maps.Character_Mapping_Function) return Bounded_String
772 renames Super_Translate;
775 (Source : in out Bounded_String;
776 Mapping : Maps.Character_Mapping_Function)
777 renames Super_Translate;
779 function Replace_Slice
780 (Source : Bounded_String;
784 Drop : Truncation := Error) return Bounded_String
785 renames Super_Replace_Slice;
787 procedure Replace_Slice
788 (Source : in out Bounded_String;
792 Drop : Truncation := Error)
793 renames Super_Replace_Slice;
796 (Source : Bounded_String;
799 Drop : Truncation := Error) return Bounded_String
800 renames Super_Insert;
803 (Source : in out Bounded_String;
806 Drop : Truncation := Error)
807 renames Super_Insert;
810 (Source : Bounded_String;
813 Drop : Truncation := Error) return Bounded_String
814 renames Super_Overwrite;
817 (Source : in out Bounded_String;
820 Drop : Truncation := Error)
821 renames Super_Overwrite;
824 (Source : Bounded_String;
826 Through : Natural) return Bounded_String
827 renames Super_Delete;
830 (Source : in out Bounded_String;
833 renames Super_Delete;
836 (Source : Bounded_String;
837 Side : Trim_End) return Bounded_String
841 (Source : in out Bounded_String;
846 (Source : Bounded_String;
847 Left : Maps.Character_Set;
848 Right : Maps.Character_Set) return Bounded_String
852 (Source : in out Bounded_String;
853 Left : Maps.Character_Set;
854 Right : Maps.Character_Set)
858 (Source : Bounded_String;
860 Pad : Character := Space;
861 Drop : Truncation := Error) return Bounded_String
865 (Source : in out Bounded_String;
867 Pad : Character := Space;
868 Drop : Truncation := Error)
872 (Source : Bounded_String;
874 Pad : Character := Space;
875 Drop : Truncation := Error) return Bounded_String
879 (Source : in out Bounded_String;
881 Pad : Character := Space;
882 Drop : Truncation := Error)
887 Right : Bounded_String) return Bounded_String
892 Item : Bounded_String;
893 Drop : Truncation := Error) return Bounded_String
894 renames Super_Replicate;
896 end Generic_Bounded_Length;
898 end Ada.Strings.Bounded;