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.
Reason: Strings.Bounded declares an inner
generic package, versus itself being directly a generic child of Strings,
in order to retain compatibility with a version of the string-handling
packages that is generic with respect to the character and string types.
Reason: The bound of a bounded-length
string is specified as a parameter to a generic, versus as the value
for a discriminant, because of the inappropriateness of assignment and
equality of discriminated types for the copying and comparison of bounded
strings.
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;
{
AI95-00301-01}
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;
{
AI95-00301-01}
function Bounded_Slice
(Source :
in Bounded_String;
Low :
in Positive;
High :
in Natural)
return Bounded_String;
{
AI95-00301-01}
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;
{
AI95-00301-01}
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;
{
AI95-00301-01}
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;
{
AI95-00301-01}
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;
{
AI95-00301-01}
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);
{
AI95-00301-01}
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;
{
8652/0049}
{
AI95-00128-01}
{
AI95-00238-01}
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;
{
AI95-00301-01}
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);
{
AI95-00301-01}
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.
{
8652/0049}
{
AI95-00128-01}
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.
Ramification: {
AI95-00114-01}
The "/=" operations between Bounded_String and String, and
between String and Bounded_String, are automatically defined based on
the corresponding "=" operations.
Implementation Advice
Bounded string objects should not be implemented
by implicit pointers and dynamic allocation.
Implementation Advice: Bounded string
objects should not be implemented by implicit pointers and dynamic allocation.
Implementation
Note: The following is a possible implementation of the private part
of the package:
type Bounded_String_Internals (Length : Length_Range := 0) is
record
Data : String(1..Length);
end record;
type Bounded_String is
record
Data : Bounded_String_Internals; -- Unconstrained
end record;
Null_Bounded_String : constant Bounded_String :=
(Data => (Length => 0,
Data => (1..0 => ' ')));
Inconsistencies With Ada 95
{
AI95-00238-01}
{
inconsistencies with Ada 95}
Amendment
Correction: The bounds of the string returned from Slice are now
defined. This is technically an inconsistency; if a program depended
on some other lower bound for the string returned from Slice, it could
fail when compiled with Ada 2005. Such code is not portable even between
Ada 95 implementations, so it should be very rare.
Incompatibilities With Ada 95
{
AI95-00301-01}
{
incompatibilities with Ada 95}
Procedure
Set_Bounded_String, two Bounded_Slice subprograms, and overloaded versions
of Index and Index_Non_Blank are newly added to Strings.Bounded. If Strings.Bounded
is referenced in a
use_clause,
and an entity
E with the same
defining_identifier
as a new entity in Strings.Bounded is defined in a package that is also
referenced in a
use_clause,
the entity
E may no longer be use-visible, resulting in errors.
This should be rare and is easily fixed if it does occur.
Wording Changes from Ada 95
{
8652/0049}
{
AI95-00128-01}
Corrigendum: Clarified the meaning of transformation, selector,
and constructor subprograms by describing the effects of procedures and
functions separately.
Sponsored by Ada-Europe