A.4.5 Unbounded-Length String Handling
{
AI12-0445-1}
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 necessary to reflect the flexibility in length. Since the Unbounded_String
type is private, relevant constructor and selector operations are provided.
Reason: The transformation operations
for fixed- and bounded-length strings that are not necessarily length
preserving are supplied for Unbounded_String as procedures as well as
functions. This allows an implementation to do an initial allocation
for an unbounded string and to avoid further allocations as long as the
length does not exceed the allocated length.
Static Semantics
The library package
Strings.Unbounded has the following declaration:
{
AI12-0241-1}
{
AI12-0302-1}
with Ada.Strings.Maps;
package Ada.Strings.Unbounded
with Preelaborate, Nonblocking, Global =>
in out synchronized is 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;
{
AI95-00301-01}
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;
{
AI95-00301-01}
function Unbounded_Slice
(Source :
in Unbounded_String;
Low :
in Positive;
High :
in Natural)
return Unbounded_String;
{
AI95-00301-01}
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
{
AI95-00301-01}
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;
{
AI95-00301-01}
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;
{
AI95-00301-01}
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;
{
AI95-00301-01}
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;
{
AI05-0031-1}
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;
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.
{
AI95-00301-01}
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.
Ramification: {
AI12-0005-1}
If the resulting string is longer than Natural'Last, Constraint_Error
is raised because the upper bound of the underlying String concatenation
is outside of the range of the index subtype of Natural (see
4.5.3).
Note that the same is true for other operations that attempt to create
an overlong string: either they are defined in terms of this concatenation
operation (as with Append) or they are defined in terms of Ada.Strings.Fixed
operations (as with Insert and Replace_Slice), which themselves are defined
in terms of String concatenation (which raises Constraint_Error for overlong
strings as described above). Therefore, it is never possible to create
an Unbounded_String with a length greater than Natural'Last.
The Element, Replace_Element, and Slice subprograms
have the same effect as the corresponding bounded-length string subprograms.
{
AI95-00301-01}
{
AI05-0262-1}
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.
Implementation Note: {
AI95-00301-01}
A sample implementation of the private part of the package and several
of the subprograms appears in the Ada 95 Rationale.
Incompatibilities With Ada 95
{
AI95-00360-01}
Amendment Correction: Type Unbounded_String
is defined to need finalization. If the restriction No_Nested_Finalization
(see
D.7) applies to the partition, and Unbounded_String
does not have a controlled part, it will not be allowed in local objects
in Ada 2005 whereas it would be allowed in original Ada 95. Such code
is not portable, as most Ada compilers have a controlled part in Unbounded_String,
and thus would be illegal.
{
AI95-00301-01}
{
AI05-0005-1}
Procedure Set_Unbounded_String, two Unbounded_Slice subprograms, and
overloaded versions of Index and Index_Non_Blank are added to Strings.Unbounded.
If Strings.Unbounded is referenced in a
use_clause,
and an entity
E with the same
defining_identifier
as a new entity in Strings.Unbounded 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.
Extensions to Ada 95
{
AI95-00161-01}
Amendment Correction: Added a
pragma
Preelaborable_Initialization to type Unbounded_String, so that it can
be used to declare default-initialized objects in preelaborated units.
Incompatibilities With Ada 2005
{
AI05-0031-1}
An overloaded version of Find_Token is added to Strings.Unbounded.
If Strings.Unbounded is referenced in a
use_clause,
and an entity
E with a
defining_identifier
of Find_Token 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.
Ada 2005 and 2012 Editions sponsored in part by Ada-Europe
