Annotated Ada Reference ManualLegal Information
Contents   Index   References   Search   Previous   Next 

A.4.3 Fixed-Length String Handling

1
The language-defined package Strings.Fixed provides string-handling subprograms for fixed-length strings; that is, for values of type Standard.String. Several of these subprograms are procedures that modify the contents of a String that is passed as an out or an in out parameter; each has additional parameters to control the effect when the logical length of the result differs from the parameter's length.
2
For each function that returns a String, the lower bound of the returned value is 1. 
2.a/2
Discussion: {AI95-00114-01} Most operations that yield yields a String are provided both as a function and as a procedure. The functional form is possibly a more aesthetic style but may introduce overhead due to extra copying or dynamic memory usage in some implementations. Thus a procedural form, with an in out parameter so that all copying is done `in place', is also supplied.
3
The basic model embodied in the package is that a fixed-length string comprises significant characters and possibly padding (with space characters) on either or both ends. When a shorter string is copied to a longer string, padding is inserted, and when a longer string is copied to a shorter one, padding is stripped. The Move procedure in Strings.Fixed, which takes a String as an out parameter, allows the programmer to control these effects. Similar control is provided by the string transformation procedures. 

Static Semantics

4
The library package Strings.Fixed has the following declaration: 
5
with Ada.Strings.Maps;
package Ada.Strings.Fixed is
   pragma Preelaborate(Fixed);
6
-- "Copy" procedure for strings of possibly different lengths
7
   procedure Move (Source  : in  String;
                   Target  : out String;
                   Drop    : in  Truncation := Error;
                   Justify : in  Alignment  := Left;
                   Pad     : in  Character  := Space);
8
-- Search subprograms
8.1/2
{AI95-00301-01}    function Index (Source  : in String;
                   Pattern : in String;
                   From    : in Positive;
                   Going   : in Direction := Forward;
                   Mapping : in Maps.Character_Mapping := Maps.Identity)
      return Natural;
8.2/2
{AI95-00301-01}    function Index (Source  : in String;
                   Pattern : in String;
                   From    : in Positive;
                   Going   : in Direction := Forward;
                   Mapping : in Maps.Character_Mapping_Function)
      return Natural;
9
   function Index (Source   : in String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;
10
   function Index (Source   : in String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;
10.1/2
{AI95-00301-01}    function Index (Source  : in String;
                   Set     : in Maps.Character_Set;
                   From    : in Positive;
                   Test    : in Membership := Inside;
                   Going   : in Direction := Forward)
      return Natural;
11
   function Index (Source : in String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward)
      return Natural;
11.1/2
{AI95-00301-01}    function Index_Non_Blank (Source : in String;
                             From   : in Positive;
                             Going  : in Direction := Forward)
      return Natural;
12
   function Index_Non_Blank (Source : in String;
                             Going  : in Direction := Forward)
      return Natural;
13
   function Count (Source   : in String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                 := Maps.Identity)
      return Natural;
14
   function Count (Source   : in String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;
15
   function Count (Source   : in String;
                   Set      : in Maps.Character_Set)
      return Natural;
16
   procedure Find_Token (Source : in String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);
17
-- String translation subprograms
18
   function Translate (Source  : in String;
                       Mapping : in Maps.Character_Mapping)
      return String;
19
   procedure Translate (Source  : in out String;
                        Mapping : in Maps.Character_Mapping);
20
   function Translate (Source  : in String;
                       Mapping : in Maps.Character_Mapping_Function)
      return String;
21
   procedure Translate (Source  : in out String;
                        Mapping : in Maps.Character_Mapping_Function);
22
-- String transformation subprograms
23
   function Replace_Slice (Source   : in String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return String;
24
   procedure Replace_Slice (Source   : in out String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String;
                            Drop     : in Truncation := Error;
                            Justify  : in Alignment  := Left;
                            Pad      : in Character  := Space);
25
   function Insert (Source   : in String;
                    Before   : in Positive;
                    New_Item : in String)
      return String;
26
   procedure Insert (Source   : in out String;
                     Before   : in Positive;
                     New_Item : in String;
                     Drop     : in Truncation := Error);
27
   function Overwrite (Source   : in String;
                       Position : in Positive;
                       New_Item : in String)
      return String;
28
   procedure Overwrite (Source   : in out String;
                        Position : in Positive;
                        New_Item : in String;
                        Drop     : in Truncation := Right);
29
   function Delete (Source  : in String;
                    From    : in Positive;
                    Through : in Natural)
      return String;
30
   procedure Delete (Source  : in out String;
                     From    : in Positive;
                     Through : in Natural;
                     Justify : in Alignment := Left;
                     Pad     : in Character := Space);
31
 --String selector subprograms
   function Trim (Source : in String;
                  Side   : in Trim_End)
      return String;
32
   procedure Trim (Source  : in out String;
                   Side    : in Trim_End;
                   Justify : in Alignment := Left;
                   Pad     : in Character := Space);
33
   function Trim (Source : in String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return String;
34
   procedure Trim (Source  : in out String;
                   Left    : in Maps.Character_Set;
                   Right   : in Maps.Character_Set;
                   Justify : in Alignment := Strings.Left;
                   Pad     : in Character := Space);
35
   function Head (Source : in String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return String;
36
   procedure Head (Source  : in out String;
                   Count   : in Natural;
                   Justify : in Alignment := Left;
                   Pad     : in Character := Space);
37
   function Tail (Source : in String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return String;
38
   procedure Tail (Source  : in out String;
                   Count   : in Natural;
                   Justify : in Alignment := Left;
                   Pad     : in Character := Space);
39
--String constructor functions
40
   function "*" (Left  : in Natural;
                 Right : in Character) return String;
41
   function "*" (Left  : in Natural;
                 Right : in String) return String;
42
end Ada.Strings.Fixed;
43
The effects of the above subprograms are as follows.
44
procedure Move (Source  : in  String;
                Target  : out String;
                Drop    : in  Truncation := Error;
                Justify : in  Alignment  := Left;
                Pad     : in  Character  := Space);
45
The Move procedure copies characters from Source to Target. If Source has the same length as Target, then the effect is to assign Source to Target. If Source is shorter than Target then: 
46
47
48
49
50
If Source is longer than Target, then the effect is based on Drop. 
51
52
53
54
55
56
56.a
Ramification: The Move procedure will work even if Source and Target overlap.
56.b
Reason: The order of parameters (Source before Target) corresponds to the order in COBOL's MOVE verb.
56.1/2
function Index (Source  : in String;
                Pattern : in String;
                From    : in Positive;
                Going   : in Direction := Forward;
                Mapping : in Maps.Character_Mapping := Maps.Identity)
   return Natural;

function Index (Source  : in String;
                Pattern : in String;
                From    : in Positive;
                Going   : in Direction := Forward;
                Mapping : in Maps.Character_Mapping_Function)
   return Natural;
56.2/2
{AI95-00301-01} Each Index function searches, starting from From, for a slice of Source, with length Pattern'Length, that matches Pattern with respect to Mapping; the parameter Going indicates the direction of the lookup. If From is not in Source'Range, then Index_Error is propagated. If Going = Forward, then Index returns the smallest index I which is greater than or equal to From such that the slice of Source starting at I matches Pattern. If Going = Backward, then Index returns the largest index I such that the slice of Source starting at I matches Pattern and has an upper bound less than or equal to From. If there is no such slice, then 0 is returned. If Pattern is the null string, then Pattern_Error is propagated.
56.c/2
Discussion: There is no default parameter for From; the default value would need to depend on other parameters (the bounds of Source and the direction Going). It is better to use overloaded functions rather than a special value to represent the default.
56.d/2
There is no default value for the Mapping parameter that is a Character_Mapping_Function; if there were, a call would be ambiguous since there is also a default for the Mapping parameter that is a Character_Mapping. 
57
function Index (Source   : in String;
                Pattern  : in String;
                Going    : in Direction := Forward;
                Mapping  : in Maps.Character_Mapping
                              := Maps.Identity)
   return Natural;

function Index (Source   : in String;
                Pattern  : in String;
                Going    : in Direction := Forward;
                Mapping  : in Maps.Character_Mapping_Function)
   return Natural;
58/2
{AI95-00301-01} If Going = Forward, returns Each Index function searches for a slice of Source, with length Pattern'Length, that matches Pattern with respect to Mapping; the parameter Going indicates the direction of the lookup. If Going = Forward, then Index returns the smallest index I such that the slice of Source starting at I matches Pattern. If Going = Backward, then Index returns the largest index I such that the slice of Source starting at I matches Pattern. If there is no such slice, then 0 is returned. If Pattern is the null string then Pattern_Error is propagated.
58.1/2
      Index (Source, Pattern, Source'First, Forward, Mapping);
58.2/2
otherwise returns 
58.3/2
      Index (Source, Pattern, Source'Last, Backward, Mapping);
58.a/2
This paragraph was deleted.Discussion: There is no default value for the Mapping parameter that is a Character_Mapping_Function; if there were, a call would be ambiguous since there is also a default for the Mapping parameter that is a Character_Mapping. 
58.4/2
function Index (Source  : in String;
                Set     : in Maps.Character_Set;
                From    : in Positive;
                Test    : in Membership := Inside;
                Going   : in Direction := Forward)
   return Natural;
58.5/2
{AI95-00301-01} Index searches for the first or last occurrence of any of a set of characters (when Test=Inside), or any of the complement of a set of characters (when Test=Outside). If From is not in Source'Range, then Index_Error is propagated. Otherwise, it returns the smallest index I >= From (if Going=Forward) or the largest index I <= From (if Going=Backward) such that Source(I) satisfies the Test condition with respect to Set; it returns 0 if there is no such Character in Source.
59
function Index (Source : in String;
                Set    : in Maps.Character_Set;
                Test   : in Membership := Inside;
                Going  : in Direction  := Forward)
   return Natural;
60/2
{AI95-00301-01} If Going = Forward, returns Index searches for the first or last occurrence of any of a set of characters (when Test=Inside), or any of the complement of a set of characters (when Test=Outside). It returns the smallest index I (if Going=Forward) or the largest index I (if Going=Backward) such that Source(I) satisfies the Test condition with respect to Set; it returns 0 if there is no such Character in Source.
60.1/2
      Index (Source, Set, Source'First, Test, Forward);
60.2/2
otherwise returns 
60.3/2
      Index (Source, Set, Source'Last, Test, Backward);
60.4/2
function Index_Non_Blank (Source : in String;
                          From   : in Positive;
                          Going  : in Direction := Forward)
   return Natural;
60.5/2
{AI95-00301-01} Returns Index (Source, Maps.To_Set(Space), From, Outside, Going);
61
function Index_Non_Blank (Source : in String;
                          Going  : in Direction := Forward)
   return Natural;
62
Returns Index(Source, Maps.To_Set(Space), Outside, Going)
63
function Count (Source   : in String;
                Pattern  : in String;
                Mapping  : in Maps.Character_Mapping
                             := Maps.Identity)
   return Natural;

function Count (Source   : in String;
                Pattern  : in String;
                Mapping  : in Maps.Character_Mapping_Function)
   return Natural;
64
Returns the maximum number of nonoverlapping slices of Source that match Pattern with respect to Mapping. If Pattern is the null string then Pattern_Error is propagated.
64.a
Reason: We say `maximum number' because it is possible to slice a source string in different ways yielding different numbers of matches. For example if Source is "ABABABA" and Pattern is "ABA", then Count yields 2, although there is a partitioning of Source that yields just 1 match, for the middle slice. Saying `maximum number' is equivalent to saying that the pattern match starts either at the low index or the high index position. 
65
function Count (Source   : in String;
                Set      : in Maps.Character_Set)
   return Natural;
66
Returns the number of occurrences in Source of characters that are in Set.
67
procedure Find_Token (Source : in String;
                      Set    : in Maps.Character_Set;
                      Test   : in Membership;
                      First  : out Positive;
                      Last   : out Natural);
68/1
{8652/0049} {AI95-00128-01} Find_Token returns in First and Last the indices of the beginning and end of the first slice of Source all of whose elements satisfy the Test condition, and such that the elements (if any) immediately before and after the slice do not satisfy the Test condition. If no such slice exists, then the value returned for Last is zero, and the value returned for First is Source'First; however, if Source'First is not in Positive then Constraint_Error {Constraint_Error (raised by failure of run-time check)} is raised.
69
function Translate (Source  : in String;
                    Mapping : in Maps.Character_Mapping)
   return String;

function Translate (Source  : in String;
                    Mapping : in Maps.Character_Mapping_Function)
   return String;
70
Returns the string S whose length is Source'Length and such that S(I) is the character to which Mapping maps the corresponding element of Source, for I in 1..Source'Length.
71
procedure Translate (Source  : in out String;
                     Mapping : in Maps.Character_Mapping);

procedure Translate (Source  : in out String;
                     Mapping : in Maps.Character_Mapping_Function);
72
Equivalent to Source := Translate(Source, Mapping).
73
function Replace_Slice (Source   : in String;
                        Low      : in Positive;
                        High     : in Natural;
                        By       : in String)
   return String;
74/1
{8652/0049} {AI95-00128-01} If Low > Source'Last+1, or High < Source'First–1, then Index_Error is propagated. Otherwise:, if High >= Low then the returned string comprises Source(Source'First..Low–1) & By & Source(High+1..Source'Last), and if High < Low then the returned string is Insert(Source, Before=>Low, New_Item=>By).
74.1/1
74.2/1
75
procedure Replace_Slice (Source   : in out String;
                         Low      : in Positive;
                         High     : in Natural;
                         By       : in String;
                         Drop     : in Truncation := Error;
                         Justify  : in Alignment  := Left;
                         Pad      : in Character  := Space);
76
Equivalent to Move(Replace_Slice(Source, Low, High, By), Source, Drop, Justify, Pad).
77
function Insert (Source   : in String;
                 Before   : in Positive;
                 New_Item : in String)
   return String;
78
Propagates Index_Error if Before is not in Source'First .. Source'Last+1; otherwise returns Source(Source'First..Before–1) & New_Item & Source(Before..Source'Last), but with lower bound 1.
79
procedure Insert (Source   : in out String;
                  Before   : in Positive;
                  New_Item : in String;
                  Drop     : in Truncation := Error);
80
Equivalent to Move(Insert(Source, Before, New_Item), Source, Drop).
81
function Overwrite (Source   : in String;
                    Position : in Positive;
                    New_Item : in String)
   return String;
82
Propagates Index_Error if Position is not in Source'First .. Source'Last+1; otherwise returns the string obtained from Source by consecutively replacing characters starting at Position with corresponding characters from New_Item. If the end of Source is reached before the characters in New_Item are exhausted, the remaining characters from New_Item are appended to the string.
83
procedure Overwrite (Source   : in out String;
                     Position : in Positive;
                     New_Item : in String;
                     Drop     : in Truncation := Right);
84
Equivalent to Move(Overwrite(Source, Position, New_Item), Source, Drop).
85
function Delete (Source  : in String;
                 From    : in Positive;
                 Through : in Natural)
   return String;
86/1
{8652/0049} {AI95-00128-01} If From <= Through, the returned string is Replace_Slice(Source, From, Through, ""), otherwise it is Source with lower bound 1.
87
procedure Delete (Source  : in out String;
                  From    : in Positive;
                  Through : in Natural;
                  Justify : in Alignment := Left;
                  Pad     : in Character := Space);
88
Equivalent to Move(Delete(Source, From, Through), Source, Justify => Justify, Pad => Pad).
89
function Trim (Source : in String;
               Side   : in Trim_End)
  return String;
90
Returns the string obtained by removing from Source all leading Space characters (if Side = Left), all trailing Space characters (if Side = Right), or all leading and trailing Space characters (if Side = Both).
91
procedure Trim (Source  : in out String;
                Side    : in Trim_End;
                Justify : in Alignment := Left;
                Pad     : in Character := Space);
92
Equivalent to Move(Trim(Source, Side), Source, Justify=>Justify, Pad=>Pad).
93
function Trim (Source : in String;
               Left   : in Maps.Character_Set;
               Right  : in Maps.Character_Set)
   return String;
94
Returns the string obtained by removing from Source all leading characters in Left and all trailing characters in Right.
95
procedure Trim (Source  : in out String;
                Left    : in Maps.Character_Set;
                Right   : in Maps.Character_Set;
                Justify : in Alignment := Strings.Left;
                Pad     : in Character := Space);
96
Equivalent to Move(Trim(Source, Left, Right), Source, Justify => Justify, Pad=>Pad).
97
function Head (Source : in String;
               Count  : in Natural;
               Pad    : in Character := Space)
   return String;
98
Returns a string of length Count. If Count <= Source'Length, the string comprises the first Count characters of Source. Otherwise its contents are Source concatenated with Count–Source'Length Pad characters.
99
procedure Head (Source  : in out String;
                Count   : in Natural;
                Justify : in Alignment := Left;
                Pad     : in Character := Space);
100
Equivalent to Move(Head(Source, Count, Pad), Source, Drop=>Error, Justify=>Justify, Pad=>Pad).
101
function Tail (Source : in String;
               Count  : in Natural;
               Pad    : in Character := Space)
   return String;
102
Returns a string of length Count. If Count <= Source'Length, the string comprises the last Count characters of Source. Otherwise its contents are Count-Source'Length Pad characters concatenated with Source.
103
procedure Tail (Source  : in out String;
                Count   : in Natural;
                Justify : in Alignment := Left;
                Pad     : in Character := Space);
104
Equivalent to Move(Tail(Source, Count, Pad), Source, Drop=>Error, Justify=>Justify, Pad=>Pad).
105
function "*" (Left  : in Natural;
              Right : in Character) return String;

function "*" (Left  : in Natural;
              Right : in String) return String;
106/1
{8652/0049} {AI95-00128-01} These functions replicate a character or string a specified number of times. The first function returns a string whose length is Left and each of whose elements is Right. The second function returns a string whose length is Left*Right'Length and whose value is the null string if Left = 0 and otherwise is (Left–1)*Right & Right with lower bound 1 otherwise.
NOTES
107
9  In the Index and Count functions taking Pattern and Mapping parameters, the actual String parameter passed to Pattern should comprise characters occurring as target characters of the mapping. Otherwise the pattern will not match.
108
10  In the Insert subprograms, inserting at the end of a string is obtained by passing Source'Last+1 as the Before parameter.
109
11  {Constraint_Error (raised by failure of run-time check)} If a null Character_Mapping_Function is passed to any of the string handling subprograms, Constraint_Error is propagated. 

Incompatibilities With Ada 95

109.a/2
{AI95-00301-01} {incompatibilities with Ada 95} Overloaded versions of Index and Index_Non_Blank are newly added to Strings.Fixed. If Strings.Fixed is referenced in a use_clause, and an entity E with a defining_identifier of Index or Index_Non_Blank 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

109.b/2
{8652/0049} {AI95-00128-01} Corrigendum: Clarified that Find_Token may raise Constraint_Error if Source'First is not in Positive (which is only possible for a null string).
109.c/2
{8652/0049} {AI95-00128-01} Corrigendum: Clarified that Replace_Slice, Delete, and "*" always return a string with lower bound 1.

Contents   Index   References   Search   Previous   Next 
Ada-Europe Sponsored by Ada-Europe