Annotated Ada Reference ManualLegal Information
Contents   Index   References   Search   Previous   Next 

A.4.4 Bounded-Length String Handling

1
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.
1.a
Reason: Strings.Bounded declares an inner generic package, versus itself being directly a generic child of Strings, in order to retain compatibility with a version of the string-handling packages that is generic with respect to the character and string types.
1.b
Reason: The bound of a bounded-length string is specified as a parameter to a generic, versus as the value for a discriminant, because of the inappropriateness of assignment and equality of discriminated types for the copying and comparison of bounded strings.

Static Semantics

2
The library package Strings.Bounded has the following declaration: 
3
with Ada.Strings.Maps;
package Ada.Strings.Bounded is
   pragma Preelaborate(Bounded);
4
   generic
      Max   : Positive;    -- Maximum length of a Bounded_String
   package Generic_Bounded_Length is
5
      Max_Length : constant Positive := Max;
6
      type Bounded_String is private;
7
      Null_Bounded_String : constant Bounded_String;
8
      subtype Length_Range is Natural range 0 .. Max_Length;
9
      function Length (Source : in Bounded_String) return Length_Range;
10
   -- Conversion, Concatenation, and Selection functions
11
      function To_Bounded_String (Source : in String;
                                  Drop   : in Truncation := Error)
         return Bounded_String;
12
      function To_String (Source : in Bounded_String) return String;
12.1/2
{AI95-00301-01}       procedure Set_Bounded_String
         (Target :    out Bounded_String;
          Source : in     String;
          Drop   : in     Truncation := Error);
13
      function Append (Left, Right : in Bounded_String;
                       Drop        : in Truncation  := Error)
         return Bounded_String;
14
      function Append (Left  : in Bounded_String;
                       Right : in String;
                       Drop  : in Truncation := Error)
         return Bounded_String;
15
      function Append (Left  : in String;
                       Right : in Bounded_String;
                       Drop  : in Truncation := Error)
         return Bounded_String;
16
      function Append (Left  : in Bounded_String;
                       Right : in Character;
                       Drop  : in Truncation := Error)
         return Bounded_String;
17
      function Append (Left  : in Character;
                       Right : in Bounded_String;
                       Drop  : in Truncation := Error)
         return Bounded_String;
18
      procedure Append (Source   : in out Bounded_String;
                        New_Item : in Bounded_String;
                        Drop     : in Truncation  := Error);
19
      procedure Append (Source   : in out Bounded_String;
                        New_Item : in String;
                        Drop     : in Truncation  := Error);
20
      procedure Append (Source   : in out Bounded_String;
                        New_Item : in Character;
                        Drop     : in Truncation  := Error);
21
      function "&" (Left, Right : in Bounded_String)
         return Bounded_String;
22
      function "&" (Left : in Bounded_String; Right : in String)
         return Bounded_String;
23
      function "&" (Left : in String; Right : in Bounded_String)
         return Bounded_String;
24
      function "&" (Left : in Bounded_String; Right : in Character)
         return Bounded_String;
25
      function "&" (Left : in Character; Right : in Bounded_String)
         return Bounded_String;
26
      function Element (Source : in Bounded_String;
                        Index  : in Positive)
         return Character;
27
      procedure Replace_Element (Source : in out Bounded_String;
                                 Index  : in Positive;
                                 By     : in Character);
28
      function Slice (Source : in Bounded_String;
                      Low    : in Positive;
                      High   : in Natural)
         return String;
28.1/2
{AI95-00301-01}       function Bounded_Slice
         (Source : in Bounded_String;
          Low    : in Positive;
          High   : in Natural)
             return Bounded_String;
28.2/2
{AI95-00301-01}       procedure Bounded_Slice
         (Source : in     Bounded_String;
          Target :    out Bounded_String;
          Low    : in     Positive;
          High   : in     Natural);
29
      function "="  (Left, Right : in Bounded_String) return Boolean;
      function "="  (Left : in Bounded_String; Right : in String)
        return Boolean;
30
      function "="  (Left : in String; Right : in Bounded_String)
        return Boolean;
31
      function "<"  (Left, Right : in Bounded_String) return Boolean;
32
      function "<"  (Left : in Bounded_String; Right : in String)
        return Boolean;
33
      function "<"  (Left : in String; Right : in Bounded_String)
        return Boolean;
34
      function "<=" (Left, Right : in Bounded_String) return Boolean;
35
      function "<="  (Left : in Bounded_String; Right : in String)
        return Boolean;
36
      function "<="  (Left : in String; Right : in Bounded_String)
        return Boolean;
37
      function ">"  (Left, Right : in Bounded_String) return Boolean;
38
      function ">"  (Left : in Bounded_String; Right : in String)
        return Boolean;
39
      function ">"  (Left : in String; Right : in Bounded_String)
        return Boolean;
40
      function ">=" (Left, Right : in Bounded_String) return Boolean;
41
      function ">="  (Left : in Bounded_String; Right : in String)
        return Boolean;
42
      function ">="  (Left : in String; Right : in Bounded_String)
        return Boolean;
43/2
{AI95-00301-01}    -- Search subprograms functions
43.1/2
{AI95-00301-01}       function Index (Source  : in Bounded_String;
                      Pattern : in String;
                      From    : in Positive;
                      Going   : in Direction := Forward;
                      Mapping : in Maps.Character_Mapping := Maps.Identity)
         return Natural;
43.2/2
{AI95-00301-01}       function Index (Source  : in Bounded_String;
                      Pattern : in String;
                      From    : in Positive;
                      Going   : in Direction := Forward;
                      Mapping : in Maps.Character_Mapping_Function)
         return Natural;
44
      function Index (Source   : in Bounded_String;
                      Pattern  : in String;
                      Going    : in Direction := Forward;
                      Mapping  : in Maps.Character_Mapping
                                 := Maps.Identity)
         return Natural;
45
      function Index (Source   : in Bounded_String;
                      Pattern  : in String;
                      Going    : in Direction := Forward;
                      Mapping  : in Maps.Character_Mapping_Function)
         return Natural;
45.1/2
{AI95-00301-01}       function Index (Source  : in Bounded_String;
                      Set     : in Maps.Character_Set;
                      From    : in Positive;
                      Test    : in Membership := Inside;
                      Going   : in Direction := Forward)
         return Natural;
46
      function Index (Source : in Bounded_String;
                      Set    : in Maps.Character_Set;
                      Test   : in Membership := Inside;
                      Going  : in Direction  := Forward)
         return Natural;
46.1/2
{AI95-00301-01}       function Index_Non_Blank (Source : in Bounded_String;
                                From   : in Positive;
                                Going  : in Direction := Forward)
         return Natural;
47
      function Index_Non_Blank (Source : in Bounded_String;
                                Going  : in Direction := Forward)
         return Natural;
48
      function Count (Source   : in Bounded_String;
                      Pattern  : in String;
                      Mapping  : in Maps.Character_Mapping
                                   := Maps.Identity)
         return Natural;
49
      function Count (Source   : in Bounded_String;
                      Pattern  : in String;
                      Mapping  : in Maps.Character_Mapping_Function)
         return Natural;
50
      function Count (Source   : in Bounded_String;
                      Set      : in Maps.Character_Set)
         return Natural;
50.1/3
{AI05-0031-1}       procedure Find_Token (Source : in Bounded_String;
                            Set    : in Maps.Character_Set;
                            From   : in Positive;
                            Test   : in Membership;
                            First  : out Positive;
                            Last   : out Natural);
51
      procedure Find_Token (Source : in Bounded_String;
                            Set    : in Maps.Character_Set;
                            Test   : in Membership;
                            First  : out Positive;
                            Last   : out Natural);
52
   -- String translation subprograms
53
      function Translate (Source  : in Bounded_String;
                          Mapping : in Maps.Character_Mapping)
         return Bounded_String;
54
      procedure Translate (Source  : in out Bounded_String;
                           Mapping : in Maps.Character_Mapping);
55
      function Translate (Source  : in Bounded_String;
                          Mapping : in Maps.Character_Mapping_Function)
         return Bounded_String;
56
      procedure Translate (Source  : in out Bounded_String;
                           Mapping : in Maps.Character_Mapping_Function);
57
   -- String transformation subprograms
58
      function Replace_Slice (Source   : in Bounded_String;
                              Low      : in Positive;
                              High     : in Natural;
                              By       : in String;
                              Drop     : in Truncation := Error)
         return Bounded_String;
59
      procedure Replace_Slice (Source   : in out Bounded_String;
                               Low      : in Positive;
                               High     : in Natural;
                               By       : in String;
                               Drop     : in Truncation := Error);
60
      function Insert (Source   : in Bounded_String;
                       Before   : in Positive;
                       New_Item : in String;
                       Drop     : in Truncation := Error)
         return Bounded_String;
61
      procedure Insert (Source   : in out Bounded_String;
                        Before   : in Positive;
                        New_Item : in String;
                        Drop     : in Truncation := Error);
62
      function Overwrite (Source    : in Bounded_String;
                          Position  : in Positive;
                          New_Item  : in String;
                          Drop      : in Truncation := Error)
         return Bounded_String;
63
      procedure Overwrite (Source    : in out Bounded_String;
                           Position  : in Positive;
                           New_Item  : in String;
                           Drop      : in Truncation := Error);
64
      function Delete (Source  : in Bounded_String;
                       From    : in Positive;
                       Through : in Natural)
         return Bounded_String;
65
      procedure Delete (Source  : in out Bounded_String;
                        From    : in Positive;
                        Through : in Natural);
66
   --String selector subprograms
67
      function Trim (Source : in Bounded_String;
                     Side   : in Trim_End)
         return Bounded_String;
      procedure Trim (Source : in out Bounded_String;
                      Side   : in Trim_End);
68
      function Trim (Source : in Bounded_String;
                     Left   : in Maps.Character_Set;
                     Right  : in Maps.Character_Set)
         return Bounded_String;
69
      procedure Trim (Source : in out Bounded_String;
                      Left   : in Maps.Character_Set;
                      Right  : in Maps.Character_Set);
70
      function Head (Source : in Bounded_String;
                     Count  : in Natural;
                     Pad    : in Character  := Space;
                     Drop   : in Truncation := Error)
         return Bounded_String;
71
      procedure Head (Source : in out Bounded_String;
                      Count  : in Natural;
                      Pad    : in Character  := Space;
                      Drop   : in Truncation := Error);
72
      function Tail (Source : in Bounded_String;
                     Count  : in Natural;
                     Pad    : in Character  := Space;
                     Drop   : in Truncation := Error)
         return Bounded_String;
73
      procedure Tail (Source : in out Bounded_String;
                      Count  : in Natural;
                      Pad    : in Character  := Space;
                      Drop   : in Truncation := Error);
74
   --String constructor subprograms
75
      function "*" (Left  : in Natural;
                    Right : in Character)
         return Bounded_String;
76
      function "*" (Left  : in Natural;
                    Right : in String)
         return Bounded_String;
77
      function "*" (Left  : in Natural;
                    Right : in Bounded_String)
         return Bounded_String;
78
      function Replicate (Count : in Natural;
                          Item  : in Character;
                          Drop  : in Truncation := Error)
         return Bounded_String;
79
      function Replicate (Count : in Natural;
                          Item  : in String;
                          Drop  : in Truncation := Error)
         return Bounded_String;
80
      function Replicate (Count : in Natural;
                          Item  : in Bounded_String;
                          Drop  : in Truncation := Error)
         return Bounded_String;
81
   private
       ... -- not specified by the language
   end Generic_Bounded_Length;
82
end Ada.Strings.Bounded;
82.a.1/2
This paragraph was deleted.Implementation Note: {8652/0097} {AI95-00115-01} {AI95-00344-01} Bounded_String cannot be implemented as a (directly) controlled type, as Ada.Strings.Bounded.Generic_Bounded_Length can be instantiated at any nesting depth. Bounded_String could have a component of a controlled type, as long as that type is declared in some other (non-generic) package (including directly in Ada.Strings.Bounded).
83
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. 
84
function Length (Source : in Bounded_String) return Length_Range;
85
The Length function returns the length of the string represented by Source.
86
function To_Bounded_String (Source : in String;
                            Drop   : in Truncation := Error)
   return Bounded_String;
87/3
{AI05-0264-1} If Source'Length <= Max_Length, then this function returns a Bounded_String that represents Source. Otherwise, the effect depends on the value of Drop: 
88
If Drop=Left, then the result is a Bounded_String that represents the string comprising the rightmost Max_Length characters of Source.
89
If Drop=Right, then the result is a Bounded_String that represents the string comprising the leftmost Max_Length characters of Source.
90
If Drop=Error, then Strings.Length_Error is propagated. 
91
function To_String (Source : in Bounded_String) return String;
92
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)).
92.1/2
procedure Set_Bounded_String
   (Target :    out Bounded_String;
    Source : in     String;
    Drop   : in     Truncation := Error);
92.2/2
{AI95-00301-01} Equivalent to Target := To_Bounded_String (Source, Drop);
93
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.
94
Each of the procedures Append(Source, New_Item, Drop) has the same effect as the corresponding assignment Source := Append(Source, New_Item, Drop).
95
Each of the "&" functions has the same effect as the corresponding Append function, with Error as the Drop parameter.
96
function Element (Source : in Bounded_String;
                  Index  : in Positive)
   return Character;
97
Returns the character at position Index in the string represented by Source; propagates Index_Error if Index > Length(Source).
98
procedure Replace_Element (Source : in out Bounded_String;
                           Index  : in Positive;
                           By     : in Character);
99
Updates Source such that the character at position Index in the string represented by Source is By; propagates Index_Error if Index > Length(Source).
100
function Slice (Source : in Bounded_String;
                Low    : in Positive;
                High   : in Natural)
   return String;
101/1
{8652/0049} {AI95-00128-01} {AI95-00238-01} 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). The bounds of the returned string are Low and High..
101.1/2
function Bounded_Slice
   (Source : in Bounded_String;
    Low    : in Positive;
    High   : in Natural)
       return Bounded_String;
101.2/2
{AI95-00301-01} Returns the slice at positions Low through High in the string represented by Source as a bounded string; propagates Index_Error if Low > Length(Source)+1 or High > Length(Source).
101.3/2
procedure Bounded_Slice
   (Source : in     Bounded_String;
    Target :    out Bounded_String;
    Low    : in     Positive;
    High   : in     Natural);
101.4/2
{AI95-00301-01} Equivalent to Target := Bounded_Slice (Source, Low, High);
102
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.
103
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.
104
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.
105/1
  {8652/0049} {AI95-00128-01} 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 For each of these subprograms, 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.
105.a/2
Ramification: {AI95-00114-01} The "/=" operations between Bounded_String and String, and between String and Bounded_String, are automatically defined based on the corresponding corrsponding "=" operations. 

Implementation Advice

106
Bounded string objects should not be implemented by implicit pointers and dynamic allocation. 
106.a.1/2
Implementation Advice: Bounded string objects should not be implemented by implicit pointers and dynamic allocation.
106.a
Implementation Note: The following is a possible implementation of the private part of the package: 
106.b
type Bounded_String_Internals (Length : Length_Range := 0) is
   record
      Data : String(1..Length);
   end record;
106.c
type Bounded_String is
   record
      Data : Bounded_String_Internals;  -- Unconstrained
   end record;
106.d
Null_Bounded_String : constant Bounded_String :=
   (Data => (Length => 0,
             Data   => (1..0 => ' ')));

Inconsistencies With Ada 95

106.e/2
{AI95-00238-01} Amendment Correction: The bounds of the string returned from Slice are now defined. This is technically an inconsistency; if a program depended on some other lower bound for the string returned from Slice, it could fail when compiled with Ada 2005. Such code is not portable even between Ada 95 implementations, so it should be very rare. 

Incompatibilities With Ada 95

106.f/2
{AI95-00301-01} Procedure Set_Bounded_String, two Bounded_Slice subprograms, and overloaded versions of Index and Index_Non_Blank are newly added to Strings.Bounded.Generic_Bounded_Length. If an instance of Generic_Bounded_Length is referenced in a use_clause, and an entity E with the defining_identifier as a new entity in Generic_Bounded_Length 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. 

Wording Changes from Ada 95

106.g/2
{8652/0049} {AI95-00128-01} Corrigendum: Corrected the conditions for which Slice raises Index_Error.
106.h/2
{8652/0049} {AI95-00128-01} Corrigendum: Clarified the meaning of transformation, selector, and constructor subprograms by describing the effects of procedures and functions separately. 

Incompatibilities With Ada 2005

106.i/3
{AI05-0031-1} An overloaded version of Find_Token is newly added to Strings.Bounded.Generic_Bounded_Length. If an instance of Generic_Bounded_Length 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. 

Contents   Index   References   Search   Previous   Next 
Ada-Europe Ada 2005 and 2012 Editions sponsored in part by Ada-Europe