A.4.5 Unbounded-Length String Handling
The language-defined package Strings.Unbounded provides
a private type Unbounded_String and a set of operations. An object of
type Unbounded_String represents a String whose low bound is 1 and whose
length can vary conceptually between 0 and Natural'Last. The subprograms
for fixed-length string handling are either overloaded directly for Unbounded_String,
or are modified as needed to reflect the flexibility in length. Since
the Unbounded_String type is private, relevant constructor and selector
operations are provided.
Static Semantics
The library package
Strings.Unbounded has the following declaration:
with Ada.Strings.Maps;
package Ada.Strings.Unbounded
is
pragma Preelaborate(Unbounded);
type Unbounded_String
is private;
pragma Preelaborable_Initialization(Unbounded_String);
Null_Unbounded_String :
constant Unbounded_String;
function Length (Source :
in Unbounded_String)
return Natural;
type String_Access
is access all String;
procedure Free (X :
in out String_Access);
-- Conversion, Concatenation, and Selection functions
function To_Unbounded_String (Source :
in String)
return Unbounded_String;
function To_Unbounded_String (Length :
in Natural)
return Unbounded_String;
function To_String (Source :
in Unbounded_String)
return String;
procedure Set_Unbounded_String
(Target :
out Unbounded_String;
Source :
in String);
procedure Append (Source :
in out Unbounded_String;
New_Item :
in Unbounded_String);
procedure Append (Source :
in out Unbounded_String;
New_Item :
in String);
procedure Append (Source :
in out Unbounded_String;
New_Item :
in Character);
function "&" (Left, Right : in Unbounded_String)
return Unbounded_String;
function "&" (Left : in Unbounded_String; Right : in String)
return Unbounded_String;
function "&" (Left : in String; Right : in Unbounded_String)
return Unbounded_String;
function "&" (Left : in Unbounded_String; Right : in Character)
return Unbounded_String;
function "&" (Left : in Character; Right : in Unbounded_String)
return Unbounded_String;
function Element (Source :
in Unbounded_String;
Index :
in Positive)
return Character;
procedure Replace_Element (Source :
in out Unbounded_String;
Index :
in Positive;
By :
in Character);
function Slice (Source :
in Unbounded_String;
Low :
in Positive;
High :
in Natural)
return String;
function Unbounded_Slice
(Source :
in Unbounded_String;
Low :
in Positive;
High :
in Natural)
return Unbounded_String;
procedure Unbounded_Slice
(Source :
in Unbounded_String;
Target :
out Unbounded_String;
Low :
in Positive;
High :
in Natural);
function "=" (Left, Right : in Unbounded_String) return Boolean;
function "=" (Left : in Unbounded_String; Right : in String)
return Boolean;
function "=" (Left : in String; Right : in Unbounded_String)
return Boolean;
function "<" (Left, Right : in Unbounded_String) return Boolean;
function "<" (Left : in Unbounded_String; Right : in String)
return Boolean;
function "<" (Left : in String; Right : in Unbounded_String)
return Boolean;
function "<=" (Left, Right : in Unbounded_String) return Boolean;
function "<=" (Left : in Unbounded_String; Right : in String)
return Boolean;
function "<=" (Left : in String; Right : in Unbounded_String)
return Boolean;
function ">" (Left, Right : in Unbounded_String) return Boolean;
function ">" (Left : in Unbounded_String; Right : in String)
return Boolean;
function ">" (Left : in String; Right : in Unbounded_String)
return Boolean;
function ">=" (Left, Right : in Unbounded_String) return Boolean;
function ">=" (Left : in Unbounded_String; Right : in String)
return Boolean;
function ">=" (Left : in String; Right : in Unbounded_String)
return Boolean;
-- Search subprograms
function Index (Source :
in Unbounded_String;
Pattern :
in String;
From :
in Positive;
Going :
in Direction := Forward;
Mapping :
in Maps.Character_Mapping := Maps.Identity)
return Natural;
function Index (Source :
in Unbounded_String;
Pattern :
in String;
From :
in Positive;
Going :
in Direction := Forward;
Mapping :
in Maps.Character_Mapping_Function)
return Natural;
function Index (Source :
in Unbounded_String;
Pattern :
in String;
Going :
in Direction := Forward;
Mapping :
in Maps.Character_Mapping
:= Maps.Identity)
return Natural;
function Index (Source :
in Unbounded_String;
Pattern :
in String;
Going :
in Direction := Forward;
Mapping :
in Maps.Character_Mapping_Function)
return Natural;
function Index (Source :
in Unbounded_String;
Set :
in Maps.Character_Set;
From :
in Positive;
Test :
in Membership := Inside;
Going :
in Direction := Forward)
return Natural;
function Index (Source :
in Unbounded_String;
Set :
in Maps.Character_Set;
Test :
in Membership := Inside;
Going :
in Direction := Forward)
return Natural;
function Index_Non_Blank (Source :
in Unbounded_String;
From :
in Positive;
Going :
in Direction := Forward)
return Natural;
function Index_Non_Blank (Source :
in Unbounded_String;
Going :
in Direction := Forward)
return Natural;
function Count (Source :
in Unbounded_String;
Pattern :
in String;
Mapping :
in Maps.Character_Mapping
:= Maps.Identity)
return Natural;
function Count (Source :
in Unbounded_String;
Pattern :
in String;
Mapping :
in Maps.Character_Mapping_Function)
return Natural;
function Count (Source :
in Unbounded_String;
Set :
in Maps.Character_Set)
return Natural;
procedure Find_Token (Source :
in Unbounded_String;
Set :
in Maps.Character_Set;
From :
in Positive;
Test :
in Membership;
First :
out Positive;
Last :
out Natural);
procedure Find_Token (Source :
in Unbounded_String;
Set :
in Maps.Character_Set;
Test :
in Membership;
First :
out Positive;
Last :
out Natural);
-- String translation subprograms
function Translate (Source :
in Unbounded_String;
Mapping :
in Maps.Character_Mapping)
return Unbounded_String;
procedure Translate (Source :
in out Unbounded_String;
Mapping :
in Maps.Character_Mapping);
function Translate (Source :
in Unbounded_String;
Mapping :
in Maps.Character_Mapping_Function)
return Unbounded_String;
procedure Translate (Source :
in out Unbounded_String;
Mapping :
in Maps.Character_Mapping_Function);
-- String transformation subprograms
function Replace_Slice (Source :
in Unbounded_String;
Low :
in Positive;
High :
in Natural;
By :
in String)
return Unbounded_String;
procedure Replace_Slice (Source :
in out Unbounded_String;
Low :
in Positive;
High :
in Natural;
By :
in String);
function Insert (Source :
in Unbounded_String;
Before :
in Positive;
New_Item :
in String)
return Unbounded_String;
procedure Insert (Source :
in out Unbounded_String;
Before :
in Positive;
New_Item :
in String);
function Overwrite (Source :
in Unbounded_String;
Position :
in Positive;
New_Item :
in String)
return Unbounded_String;
procedure Overwrite (Source :
in out Unbounded_String;
Position :
in Positive;
New_Item :
in String);
function Delete (Source :
in Unbounded_String;
From :
in Positive;
Through :
in Natural)
return Unbounded_String;
procedure Delete (Source :
in out Unbounded_String;
From :
in Positive;
Through :
in Natural);
function Trim (Source :
in Unbounded_String;
Side :
in Trim_End)
return Unbounded_String;
procedure Trim (Source :
in out Unbounded_String;
Side :
in Trim_End);
function Trim (Source :
in Unbounded_String;
Left :
in Maps.Character_Set;
Right :
in Maps.Character_Set)
return Unbounded_String;
procedure Trim (Source :
in out Unbounded_String;
Left :
in Maps.Character_Set;
Right :
in Maps.Character_Set);
function Head (Source :
in Unbounded_String;
Count :
in Natural;
Pad :
in Character := Space)
return Unbounded_String;
procedure Head (Source :
in out Unbounded_String;
Count :
in Natural;
Pad :
in Character := Space);
function Tail (Source :
in Unbounded_String;
Count :
in Natural;
Pad :
in Character := Space)
return Unbounded_String;
procedure Tail (Source :
in out Unbounded_String;
Count :
in Natural;
Pad :
in Character := Space);
function "*" (Left : in Natural;
Right : in Character)
return Unbounded_String;
function "*" (Left : in Natural;
Right : in String)
return Unbounded_String;
function "*" (Left : in Natural;
Right : in Unbounded_String)
return Unbounded_String;
private
... -- not specified by the language
end Ada.Strings.Unbounded;
The type Unbounded_String needs finalization
(see
7.6).
Null_Unbounded_String represents the null String.
If an object of type Unbounded_String is not otherwise initialized, it
will be initialized to the same value as Null_Unbounded_String.
The function Length returns the length of the String
represented by Source.
The type String_Access provides a (nonprivate) access
type for explicit processing of unbounded-length strings. The procedure
Free performs an unchecked deallocation of an object of type String_Access.
The function To_Unbounded_String(Source : in String)
returns an Unbounded_String that represents Source. The function To_Unbounded_String(Length
: in Natural) returns an Unbounded_String that represents an uninitialized
String whose length is Length.
The function To_String
returns the String with lower bound 1 represented by Source. To_String
and To_Unbounded_String are related as follows:
If S is a String, then To_String(To_Unbounded_String(S))
= S.
If U is an Unbounded_String, then To_Unbounded_String(To_String(U))
= U.
The procedure Set_Unbounded_String sets Target
to an Unbounded_String that represents Source.
For each of the Append procedures, the resulting
string represented by the Source parameter is given by the concatenation
of the original value of Source and the value of New_Item.
Each of the "&" functions returns an
Unbounded_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_Unbounded_String
to the concatenation result string.
The Element, Replace_Element, and Slice subprograms
have the same effect as the corresponding bounded-length string subprograms.
The function Unbounded_Slice returns the slice
at positions Low through High in the string represented by Source as
an Unbounded_String. The procedure Unbounded_Slice sets Target to the
Unbounded_String representing the slice at positions Low through High
in the string represented by Source. Both subprograms propagate Index_Error
if Low > Length(Source)+1 or High > Length(Source).
Each of the functions "=", "<",
">", "<=", and ">=" returns the
same result as the corresponding String operation applied to the String
values given or represented by Left and Right.
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 Unbounded_String
parameter.
The Translate function has an analogous effect to
the corresponding subprogram in Strings.Fixed. The translation is applied
to the string represented by the Unbounded_String parameter, and the
result is converted (via To_Unbounded_String) to an Unbounded_String.
Each of the transformation functions (Replace_Slice,
Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and
constructor functions ("*") is likewise analogous to its corresponding
subprogram in Strings.Fixed. For each of the subprograms, the corresponding
fixed-length string subprogram is applied to the string represented by
the Unbounded_String parameter, and To_Unbounded_String is applied the
result string.
For each of the procedures Translate, Replace_Slice,
Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string
represented by the Source parameter is given by the corresponding function
for fixed-length strings applied to the string represented by Source's
original value.
Implementation Requirements
No storage associated with an Unbounded_String object
shall be lost upon assignment or scope exit.
Ada 2005 and 2012 Editions sponsored in part by Ada-Europe
