Ada Reference Manual (Ada 2022) — Legal Information

# A.4.4 Bounded-Length String Handling

1/5
The language-defined package Strings.Bounded provides a generic package each of whose instances yields a private type Bounded_String and a set of operations. An object of a particular Bounded_String type represents a String whose low bound is 1 and whose length can vary conceptually between 0 and a maximum size established at the generic instantiation. The subprograms for fixed-length string handling are either overloaded directly for Bounded_String, or are modified as necessary to reflect the variability in length. Additionally, since the Bounded_String type is private, appropriate constructor and selector operations are provided.

#### Static Semantics

2
The library package Strings.Bounded has the following declaration:
3/5
with Ada.Strings.Maps;
package Ada.Strings.Bounded
with Preelaborate, Nonblocking, Global => in out synchronized is
4
generic
Max : Positive; -- Maximum length of a Bounded_String
package Generic_Bounded_Length is
5
Max_Length : constant Positive := Max;
6
type Bounded_String is private;
7
Null_Bounded_String : constant Bounded_String;
8
subtype Length_Range is Natural range 0 .. Max_Length;
9
function Length (Source : in Bounded_String) return Length_Range;
10
-- Conversion, Concatenation, and Selection functions
11
function To_Bounded_String (Source : in String;
Drop : in Truncation := Error)
return Bounded_String;
12
function To_String (Source : in Bounded_String) return String;
12.1/2
procedure Set_Bounded_String
(Target : out Bounded_String;
Source : in String;
Drop : in Truncation := Error);
13
function Append (Left, Right : in Bounded_String;
Drop : in Truncation := Error)
return Bounded_String;
14
function Append (Left : in Bounded_String;
Right : in String;
Drop : in Truncation := Error)
return Bounded_String;
15
function Append (Left : in String;
Right : in Bounded_String;
Drop : in Truncation := Error)
return Bounded_String;
16
function Append (Left : in Bounded_String;
Right : in Character;
Drop : in Truncation := Error)
return Bounded_String;
17
function Append (Left : in Character;
Right : in Bounded_String;
Drop : in Truncation := Error)
return Bounded_String;
18
procedure Append (Source : in out Bounded_String;
New_Item : in Bounded_String;
Drop : in Truncation := Error);
19
procedure Append (Source : in out Bounded_String;
New_Item : in String;
Drop : in Truncation := Error);
20
procedure Append (Source : in out Bounded_String;
New_Item : in Character;
Drop : in Truncation := Error);
21
function "&" (Left, Right : in Bounded_String)
return Bounded_String;
22
function "&" (Left : in Bounded_String; Right : in String)
return Bounded_String;
23
function "&" (Left : in String; Right : in Bounded_String)
return Bounded_String;
24
function "&" (Left : in Bounded_String; Right : in Character)
return Bounded_String;
25
function "&" (Left : in Character; Right : in Bounded_String)
return Bounded_String;
26
function Element (Source : in Bounded_String;
Index : in Positive)
return Character;
27
procedure Replace_Element (Source : in out Bounded_String;
Index : in Positive;
By : in Character);
28
function Slice (Source : in Bounded_String;
Low : in Positive;
High : in Natural)
return String;
28.1/2
function Bounded_Slice
(Source : in Bounded_String;
Low : in Positive;
High : in Natural)
return Bounded_String;
28.2/2
procedure Bounded_Slice
(Source : in Bounded_String;
Target : out Bounded_String;
Low : in Positive;
High : in Natural);
29
function "=" (Left, Right : in Bounded_String) return Boolean;
function "=" (Left : in Bounded_String; Right : in String)
return Boolean;
30
function "=" (Left : in String; Right : in Bounded_String)
return Boolean;
31
function "<" (Left, Right : in Bounded_String) return Boolean;
32
function "<" (Left : in Bounded_String; Right : in String)
return Boolean;
33
function "<" (Left : in String; Right : in Bounded_String)
return Boolean;
34
function "<=" (Left, Right : in Bounded_String) return Boolean;
35
function "<=" (Left : in Bounded_String; Right : in String)
return Boolean;
36
function "<=" (Left : in String; Right : in Bounded_String)
return Boolean;
37
function ">" (Left, Right : in Bounded_String) return Boolean;
38
function ">" (Left : in Bounded_String; Right : in String)
return Boolean;
39
function ">" (Left : in String; Right : in Bounded_String)
return Boolean;
40
function ">=" (Left, Right : in Bounded_String) return Boolean;
41
function ">=" (Left : in Bounded_String; Right : in String)
return Boolean;
42
function ">=" (Left : in String; Right : in Bounded_String)
return Boolean;
43/2
-- Search subprograms
43.1/2
function Index (Source : in Bounded_String;
Pattern : in String;
From : in Positive;
Going : in Direction := Forward;
Mapping : in Maps.Character_Mapping := Maps.Identity)
return Natural;
43.2/2
function Index (Source : in Bounded_String;
Pattern : in String;
From : in Positive;
Going : in Direction := Forward;
Mapping : in Maps.Character_Mapping_Function)
return Natural;
44
function Index (Source : in Bounded_String;
Pattern : in String;
Going : in Direction := Forward;
Mapping : in Maps.Character_Mapping
:= Maps.Identity)
return Natural;
45
function Index (Source : in Bounded_String;
Pattern : in String;
Going : in Direction := Forward;
Mapping : in Maps.Character_Mapping_Function)
return Natural;
45.1/2
function Index (Source : in Bounded_String;
Set : in Maps.Character_Set;
From : in Positive;
Test : in Membership := Inside;
Going : in Direction := Forward)
return Natural;
46
function Index (Source : in Bounded_String;
Set : in Maps.Character_Set;
Test : in Membership := Inside;
Going : in Direction := Forward)
return Natural;
46.1/2
function Index_Non_Blank (Source : in Bounded_String;
From : in Positive;
Going : in Direction := Forward)
return Natural;
47
function Index_Non_Blank (Source : in Bounded_String;
Going : in Direction := Forward)
return Natural;
48
function Count (Source : in Bounded_String;
Pattern : in String;
Mapping : in Maps.Character_Mapping
:= Maps.Identity)
return Natural;
49
function Count (Source : in Bounded_String;
Pattern : in String;
Mapping : in Maps.Character_Mapping_Function)
return Natural;
50
function Count (Source : in Bounded_String;
Set : in Maps.Character_Set)
return Natural;
50.1/3
procedure Find_Token (Source : in Bounded_String;
Set : in Maps.Character_Set;
From : in Positive;
Test : in Membership;
First : out Positive;
Last : out Natural);
51
procedure Find_Token (Source : in Bounded_String;
Set : in Maps.Character_Set;
Test : in Membership;
First : out Positive;
Last : out Natural);
52
-- String translation subprograms
53
function Translate (Source : in Bounded_String;
Mapping : in Maps.Character_Mapping)
return Bounded_String;
54
procedure Translate (Source : in out Bounded_String;
Mapping : in Maps.Character_Mapping);
55
function Translate (Source : in Bounded_String;
Mapping : in Maps.Character_Mapping_Function)
return Bounded_String;
56
procedure Translate (Source : in out Bounded_String;
Mapping : in Maps.Character_Mapping_Function);
57
-- String transformation subprograms
58
function Replace_Slice (Source : in Bounded_String;
Low : in Positive;
High : in Natural;
By : in String;
Drop : in Truncation := Error)
return Bounded_String;
59
procedure Replace_Slice (Source : in out Bounded_String;
Low : in Positive;
High : in Natural;
By : in String;
Drop : in Truncation := Error);
60
function Insert (Source : in Bounded_String;
Before : in Positive;
New_Item : in String;
Drop : in Truncation := Error)
return Bounded_String;
61
procedure Insert (Source : in out Bounded_String;
Before : in Positive;
New_Item : in String;
Drop : in Truncation := Error);
62
function Overwrite (Source : in Bounded_String;
Position : in Positive;
New_Item : in String;
Drop : in Truncation := Error)
return Bounded_String;
63
procedure Overwrite (Source : in out Bounded_String;
Position : in Positive;
New_Item : in String;
Drop : in Truncation := Error);
64
function Delete (Source : in Bounded_String;
From : in Positive;
Through : in Natural)
return Bounded_String;
65
procedure Delete (Source : in out Bounded_String;
From : in Positive;
Through : in Natural);
66
--String selector subprograms
67
function Trim (Source : in Bounded_String;
Side : in Trim_End)
return Bounded_String;
procedure Trim (Source : in out Bounded_String;
Side : in Trim_End);
68
function Trim (Source : in Bounded_String;
Left : in Maps.Character_Set;
Right : in Maps.Character_Set)
return Bounded_String;
69
procedure Trim (Source : in out Bounded_String;
Left : in Maps.Character_Set;
Right : in Maps.Character_Set);
70
function Head (Source : in Bounded_String;
Count : in Natural;
Pad : in Character := Space;
Drop : in Truncation := Error)
return Bounded_String;
71
procedure Head (Source : in out Bounded_String;
Count : in Natural;
Pad : in Character := Space;
Drop : in Truncation := Error);
72
function Tail (Source : in Bounded_String;
Count : in Natural;
Pad : in Character := Space;
Drop : in Truncation := Error)
return Bounded_String;
73
procedure Tail (Source : in out Bounded_String;
Count : in Natural;
Pad : in Character := Space;
Drop : in Truncation := Error);
74
--String constructor subprograms
75
function "*" (Left : in Natural;
Right : in Character)
return Bounded_String;
76
function "*" (Left : in Natural;
Right : in String)
return Bounded_String;
77
function "*" (Left : in Natural;
Right : in Bounded_String)
return Bounded_String;
78
function Replicate (Count : in Natural;
Item : in Character;
Drop : in Truncation := Error)
return Bounded_String;
79
function Replicate (Count : in Natural;
Item : in String;
Drop : in Truncation := Error)
return Bounded_String;
80
function Replicate (Count : in Natural;
Item : in Bounded_String;
Drop : in Truncation := Error)
return Bounded_String;
81
private
... -- not specified by the language
end Generic_Bounded_Length;
82
end Ada.Strings.Bounded;
83
Null_Bounded_String represents the null string. If an object of type Bounded_String is not otherwise initialized, it will be initialized to the same value as Null_Bounded_String.
84
function Length (Source : in Bounded_String) return Length_Range;
85
The Length function returns the length of the string represented by Source.
86
function To_Bounded_String (Source : in String;
Drop : in Truncation := Error)
return Bounded_String;
87/3
If Source'Length <= Max_Length, then this function returns a Bounded_String that represents Source. Otherwise, the effect depends on the value of Drop:
88
If Drop=Left, then the result is a Bounded_String that represents the string comprising the rightmost Max_Length characters of Source.
89
If Drop=Right, then the result is a Bounded_String that represents the string comprising the leftmost Max_Length characters of Source.
90
If Drop=Error, then Strings.Length_Error is propagated.
91
function To_String (Source : in Bounded_String) return String;
92
To_String returns the String value with lower bound 1 represented by Source. If B is a Bounded_String, then B = To_Bounded_String(To_String(B)).
92.1/2
procedure Set_Bounded_String
(Target : out Bounded_String;
Source : in String;
Drop : in Truncation := Error);
92.2/2
Equivalent to Target := To_Bounded_String (Source, Drop);
93
Each of the Append functions returns a Bounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Bounded_String to the concatenation result string, with Drop as provided to the Append function.
94
Each of the procedures Append(Source, New_Item, Drop) has the same effect as the corresponding assignment Source := Append(Source, New_Item, Drop).
95
Each of the "&" functions has the same effect as the corresponding Append function, with Error as the Drop parameter.
96
function Element (Source : in Bounded_String;
Index : in Positive)
return Character;
97
Returns the character at position Index in the string represented by Source; propagates Index_Error if Index > Length(Source).
98
procedure Replace_Element (Source : in out Bounded_String;
Index : in Positive;
By : in Character);
99
Updates Source such that the character at position Index in the string represented by Source is By; propagates Index_Error if Index > Length(Source).
100
function Slice (Source : in Bounded_String;
Low : in Positive;
High : in Natural)
return String;
101/1
Returns the slice at positions Low through High in the string represented by Source; propagates Index_Error if Low > Length(Source)+1 or High > Length(Source). The bounds of the returned string are Low and High.
101.1/2
function Bounded_Slice
(Source : in Bounded_String;
Low : in Positive;
High : in Natural)
return Bounded_String;
101.2/2
Returns the slice at positions Low through High in the string represented by Source as a bounded string; propagates Index_Error if Low > Length(Source)+1 or High > Length(Source).
101.3/2
procedure Bounded_Slice
(Source : in Bounded_String;
Target : out Bounded_String;
Low : in Positive;
High : in Natural);
101.4/2
Equivalent to Target := Bounded_Slice (Source, Low, High);
102
Each of the functions "=", "<", ">", "<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by the two parameters.
103
Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Bounded_String parameter.
104
Each of the Translate subprograms, when applied to a Bounded_String, has an analogous effect to the corresponding subprogram in Strings.Fixed. For the Translate function, the translation is applied to the string represented by the Bounded_String parameter, and the result is converted (via To_Bounded_String) to a Bounded_String. For the Translate procedure, the string represented by the Bounded_String parameter after the translation is given by the Translate function for fixed-length strings applied to the string represented by the original value of the parameter.
105/1
Each of the transformation subprograms (Replace_Slice, Insert, Overwrite, Delete), selector subprograms (Trim, Head, Tail), and constructor functions ("*") has an effect based on its corresponding subprogram in Strings.Fixed, and Replicate is based on Fixed."*". In the case of a function, the corresponding fixed-length string subprogram is applied to the string represented by the Bounded_String parameter. To_Bounded_String is applied the result string, with Drop (or Error in the case of Generic_Bounded_Length."*") determining the effect when the string length exceeds Max_Length. In the case of a procedure, the corresponding function in Strings.Bounded.Generic_Bounded_Length is applied, with the result assigned into the Source parameter.

#### Implementation Advice

106
Bounded string objects should not be implemented by implicit pointers and dynamic allocation.

Ada 2005 and 2012 Editions sponsored in part by Ada-Europe