A.4.4 Bounded-Length String Handling
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 needed to reflect the
variability in length. Additionally, since the Bounded_String type is
private, appropriate constructor and selector operations are provided.
Static Semantics
The library package
Strings.Bounded has the following declaration:
with Ada.Strings.Maps;
package Ada.Strings.Bounded
is
pragma Preelaborate(Bounded);
generic
Max : Positive; --
Maximum length of a Bounded_String
package Generic_Bounded_Length
is
Max_Length :
constant Positive := Max;
type Bounded_String
is private;
Null_Bounded_String :
constant Bounded_String;
subtype Length_Range
is Natural
range 0 .. Max_Length;
function Length (Source :
in Bounded_String)
return Length_Range;
-- Conversion, Concatenation, and Selection functions
function To_Bounded_String (Source :
in String;
Drop :
in Truncation := Error)
return Bounded_String;
function To_String (Source :
in Bounded_String)
return String;
procedure Set_Bounded_String
(Target :
out Bounded_String;
Source :
in String;
Drop :
in Truncation := Error);
function Append (Left, Right :
in Bounded_String;
Drop :
in Truncation := Error)
return Bounded_String;
function Append (Left :
in Bounded_String;
Right :
in String;
Drop :
in Truncation := Error)
return Bounded_String;
function Append (Left :
in String;
Right :
in Bounded_String;
Drop :
in Truncation := Error)
return Bounded_String;
function Append (Left :
in Bounded_String;
Right :
in Character;
Drop :
in Truncation := Error)
return Bounded_String;
function Append (Left :
in Character;
Right :
in Bounded_String;
Drop :
in Truncation := Error)
return Bounded_String;
procedure Append (Source :
in out Bounded_String;
New_Item :
in Bounded_String;
Drop :
in Truncation := Error);
procedure Append (Source :
in out Bounded_String;
New_Item :
in String;
Drop :
in Truncation := Error);
procedure Append (Source :
in out Bounded_String;
New_Item :
in Character;
Drop :
in Truncation := Error);
function "&" (Left, Right : in Bounded_String)
return Bounded_String;
function "&" (Left : in Bounded_String; Right : in String)
return Bounded_String;
function "&" (Left : in String; Right : in Bounded_String)
return Bounded_String;
function "&" (Left : in Bounded_String; Right : in Character)
return Bounded_String;
function "&" (Left : in Character; Right : in Bounded_String)
return Bounded_String;
function Element (Source :
in Bounded_String;
Index :
in Positive)
return Character;
procedure Replace_Element (Source :
in out Bounded_String;
Index :
in Positive;
By :
in Character);
function Slice (Source :
in Bounded_String;
Low :
in Positive;
High :
in Natural)
return String;
function Bounded_Slice
(Source :
in Bounded_String;
Low :
in Positive;
High :
in Natural)
return Bounded_String;
procedure Bounded_Slice
(Source :
in Bounded_String;
Target :
out Bounded_String;
Low :
in Positive;
High :
in Natural);
function "=" (Left, Right : in Bounded_String) return Boolean;
function "=" (Left : in Bounded_String; Right : in String)
return Boolean;
function "=" (Left : in String; Right : in Bounded_String)
return Boolean;
function "<" (Left, Right : in Bounded_String) return Boolean;
function "<" (Left : in Bounded_String; Right : in String)
return Boolean;
function "<" (Left : in String; Right : in Bounded_String)
return Boolean;
function "<=" (Left, Right : in Bounded_String) return Boolean;
function "<=" (Left : in Bounded_String; Right : in String)
return Boolean;
function "<=" (Left : in String; Right : in Bounded_String)
return Boolean;
function ">" (Left, Right : in Bounded_String) return Boolean;
function ">" (Left : in Bounded_String; Right : in String)
return Boolean;
function ">" (Left : in String; Right : in Bounded_String)
return Boolean;
function ">=" (Left, Right : in Bounded_String) return Boolean;
function ">=" (Left : in Bounded_String; Right : in String)
return Boolean;
function ">=" (Left : in String; Right : in Bounded_String)
return Boolean;
-- Search subprograms
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;
function Index (Source :
in Bounded_String;
Pattern :
in String;
From :
in Positive;
Going :
in Direction := Forward;
Mapping :
in Maps.Character_Mapping_Function)
return Natural;
function Index (Source :
in Bounded_String;
Pattern :
in String;
Going :
in Direction := Forward;
Mapping :
in Maps.Character_Mapping
:= Maps.Identity)
return Natural;
function Index (Source :
in Bounded_String;
Pattern :
in String;
Going :
in Direction := Forward;
Mapping :
in Maps.Character_Mapping_Function)
return Natural;
function Index (Source :
in Bounded_String;
Set :
in Maps.Character_Set;
From :
in Positive;
Test :
in Membership := Inside;
Going :
in Direction := Forward)
return Natural;
function Index (Source :
in Bounded_String;
Set :
in Maps.Character_Set;
Test :
in Membership := Inside;
Going :
in Direction := Forward)
return Natural;
function Index_Non_Blank (Source :
in Bounded_String;
From :
in Positive;
Going :
in Direction := Forward)
return Natural;
function Index_Non_Blank (Source :
in Bounded_String;
Going :
in Direction := Forward)
return Natural;
function Count (Source :
in Bounded_String;
Pattern :
in String;
Mapping :
in Maps.Character_Mapping
:= Maps.Identity)
return Natural;
function Count (Source :
in Bounded_String;
Pattern :
in String;
Mapping :
in Maps.Character_Mapping_Function)
return Natural;
function Count (Source :
in Bounded_String;
Set :
in Maps.Character_Set)
return Natural;
procedure Find_Token (Source :
in Bounded_String;
Set :
in Maps.Character_Set;
Test :
in Membership;
First :
out Positive;
Last :
out Natural);
-- String translation subprograms
function Translate (Source :
in Bounded_String;
Mapping :
in Maps.Character_Mapping)
return Bounded_String;
procedure Translate (Source :
in out Bounded_String;
Mapping :
in Maps.Character_Mapping);
function Translate (Source :
in Bounded_String;
Mapping :
in Maps.Character_Mapping_Function)
return Bounded_String;
procedure Translate (Source :
in out Bounded_String;
Mapping :
in Maps.Character_Mapping_Function);
-- String transformation subprograms
function Replace_Slice (Source :
in Bounded_String;
Low :
in Positive;
High :
in Natural;
By :
in String;
Drop :
in Truncation := Error)
return Bounded_String;
procedure Replace_Slice (Source :
in out Bounded_String;
Low :
in Positive;
High :
in Natural;
By :
in String;
Drop :
in Truncation := Error);
function Insert (Source :
in Bounded_String;
Before :
in Positive;
New_Item :
in String;
Drop :
in Truncation := Error)
return Bounded_String;
procedure Insert (Source :
in out Bounded_String;
Before :
in Positive;
New_Item :
in String;
Drop :
in Truncation := Error);
function Overwrite (Source :
in Bounded_String;
Position :
in Positive;
New_Item :
in String;
Drop :
in Truncation := Error)
return Bounded_String;
procedure Overwrite (Source :
in out Bounded_String;
Position :
in Positive;
New_Item :
in String;
Drop :
in Truncation := Error);
function Delete (Source :
in Bounded_String;
From :
in Positive;
Through :
in Natural)
return Bounded_String;
procedure Delete (Source :
in out Bounded_String;
From :
in Positive;
Through :
in Natural);
--String selector subprograms
function Trim (Source :
in Bounded_String;
Side :
in Trim_End)
return Bounded_String;
procedure Trim (Source :
in out Bounded_String;
Side :
in Trim_End);
function Trim (Source :
in Bounded_String;
Left :
in Maps.Character_Set;
Right :
in Maps.Character_Set)
return Bounded_String;
procedure Trim (Source :
in out Bounded_String;
Left :
in Maps.Character_Set;
Right :
in Maps.Character_Set);
function Head (Source :
in Bounded_String;
Count :
in Natural;
Pad :
in Character := Space;
Drop :
in Truncation := Error)
return Bounded_String;
procedure Head (Source :
in out Bounded_String;
Count :
in Natural;
Pad :
in Character := Space;
Drop :
in Truncation := Error);
function Tail (Source :
in Bounded_String;
Count :
in Natural;
Pad :
in Character := Space;
Drop :
in Truncation := Error)
return Bounded_String;
procedure Tail (Source :
in out Bounded_String;
Count :
in Natural;
Pad :
in Character := Space;
Drop :
in Truncation := Error);
--String constructor subprograms
function "*" (Left : in Natural;
Right : in Character)
return Bounded_String;
function "*" (Left : in Natural;
Right : in String)
return Bounded_String;
function "*" (Left : in Natural;
Right : in Bounded_String)
return Bounded_String;
function Replicate (Count :
in Natural;
Item :
in Character;
Drop :
in Truncation := Error)
return Bounded_String;
function Replicate (Count :
in Natural;
Item :
in String;
Drop :
in Truncation := Error)
return Bounded_String;
function Replicate (Count :
in Natural;
Item :
in Bounded_String;
Drop :
in Truncation := Error)
return Bounded_String;
private
... -- not specified by the language
end Generic_Bounded_Length;
end Ada.Strings.Bounded;
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.
function Length (Source : in Bounded_String) return Length_Range;
The Length function
returns the length of the string represented by Source.
function To_Bounded_String (Source : in String;
Drop : in Truncation := Error)
return Bounded_String;
If Source'Length
<= Max_Length then this function returns a Bounded_String that represents
Source. Otherwise the effect depends on the value of Drop:
If Drop=Left, then the result is a Bounded_String
that represents the string comprising the rightmost Max_Length characters
of Source.
If Drop=Right, then the result is a Bounded_String
that represents the string comprising the leftmost Max_Length characters
of Source.
If Drop=Error,
then Strings.Length_Error is propagated.
function To_String (Source : in Bounded_String) return String;
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)).
procedure Set_Bounded_String
(Target : out Bounded_String;
Source : in String;
Drop : in Truncation := Error);
Equivalent to Target
:= To_Bounded_String (Source, Drop);
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.
Each of the procedures Append(Source, New_Item, Drop)
has the same effect as the corresponding assignment Source := Append(Source,
New_Item, Drop).
Each of the "&" functions has the same
effect as the corresponding Append function, with Error as the Drop parameter.
function Element (Source : in Bounded_String;
Index : in Positive)
return Character;
Returns the character
at position Index in the string represented by Source; propagates Index_Error
if Index > Length(Source).
procedure Replace_Element (Source : in out Bounded_String;
Index : in Positive;
By : in Character);
Updates Source such
that the character at position Index in the string represented by Source
is By; propagates Index_Error if Index > Length(Source).
function Slice (Source : in Bounded_String;
Low : in Positive;
High : in Natural)
return String;
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..
function Bounded_Slice
(Source : in Bounded_String;
Low : in Positive;
High : in Natural)
return Bounded_String;
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).
procedure Bounded_Slice
(Source : in Bounded_String;
Target : out Bounded_String;
Low : in Positive;
High : in Natural);
Equivalent to Target
:= Bounded_Slice (Source, Low, High);
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.
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.
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.
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
Bounded string objects should not be implemented
by implicit pointers and dynamic allocation.
Sponsored by Ada-Europe