A.4.5 Unbounded-Length String Handling

Contents | Index | Previous | Next

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;

    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 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 "="  (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;
                    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; 
                    Test   : in Membership := Inside; 
                    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; 
                          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 (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.

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.

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.

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.

Contents | Index | Previous | Next Legal