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
;