A.4.5 Unbounded-Length String Handling

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 needed to reflect the flexibility in length. Since
the Unbounded_String type is private, relevant constructor and selector
operations are provided.

1.a

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.

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.

74

The function Length returns the length of the String
represented by Source.

75

The type String_Access provides a (non-private) access
type for explicit processing of unbounded-length strings. The procedure
Free performs an unchecked deallocation of an object of type String_Access.

76

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.

77

The function To_String
returns the String with lower bound 1 represented by Source. To_String
and To_Unbounded_String are related as follows:

78

If S is a String, then To_String(To_Unbounded_String(S))
= S.

79

If U is an Unbounded_String, then
To_Unbounded_String(To_String(U)) = U.

79.1/2

{AI95-00301-01}
The procedure Set_Unbounded_String sets Target
to an Unbounded_String that represents Source.

80

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.

81

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.

82

The Element, Replace_Element, and Slice subprograms
have the same effect as the corresponding bounded-length string subprograms.

82.1/2

{AI95-00301-01}
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 routines propagate Index_Error
if Low > Length(Source)+1 or High > Length(Source).

83

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.

84

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.

85

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.

86

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.

87

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

88

No storage associated with an Unbounded_String object
shall be lost upon assignment or scope exit.

88.a/2

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

88.b/2

{AI95-00360-01}
{incompatibilities with Ada 95} 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.

88.c/2

{AI95-00301-01}
Procedure Set_Unbounded_String, two Unbounded_Slice
subprograms, and overloaded versions of Index and Index_Non_Blank are
newly 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

88.d/2

{AI95-00161-01}
{extensions to Ada 95} 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.