A.4.4 Bounded-Length String Handling

Contents | Index | Previous | Next

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.

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;

        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;

        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;

    -- Search functions

        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;

        function Index (Source : in Bounded_String; 
                        Set    : in Maps.Character_Set; 
                        Test   : in Membership := Inside; 
                        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)).

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;

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).

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.

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.

Implementation Advice

Bounded string objects should not be implemented by implicit pointers and dynamic allocation.

Contents | Index | Previous | Next Legal