- (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.
- (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
(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;
(11)
function Index (Source : in String;
Set : in Maps.Character_Set;
Test : in Membership := Inside;
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)
- If Justify=Left, then Source is copied into the first
Source'Length characters of Target.
- (47)
- If Justify=Right, then Source is copied into the last
Source'Length characters of Target.
- (48)
- If Justify=Center, then Source is copied into the middle
Source'Length characters of Target. In this case, if the
difference in length between Target and Source is odd,
then the extra Pad character is on the right.
- (49)
- Pad is copied to each Target character not otherwise
assigned.
- (50)
If Source is longer than Target, then the effect is based on
Drop.
- (51)
- If Drop=Left, then the rightmost Target'Length characters
of Source are copied into Target.
- (52)
- If Drop=Right, then the leftmost Target'Length characters
of Source are copied into Target.
- (53)
- If Drop=Error, then the effect depends on the value of
the Justify parameter and also on whether any characters
in Source other than Pad would fail to be copied:
- (54)
- If Justify=Left, and if each of the rightmost
Source'Length-Target'Length characters in Source
is Pad, then the leftmost Target'Length characters
of Source are copied to Target.
- (55)
- If Justify=Right, and if each of the leftmost
Source'Length-Target'Length characters in Source
is Pad, then the rightmost Target'Length
characters of Source are copied to Target.
- (56)
- Otherwise, Length_Error is propagated.
(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)
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.
(59)
function Index (Source : in String;
Set : in Maps.Character_Set;
Test : in Membership := Inside;
Going : in Direction := Forward)
return Natural;
- (60)
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.
(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.
(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)
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.
(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)
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).
(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)
If From <= Through, the returned string is Replace_Slice(Source,
From, Through, ""), otherwise it is Source.
(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)
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 is (Left-1)*Right & Right otherwise.
-
- (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) If a null Character_Mapping_Function is passed to any of the string
handling subprograms, Constraint_Error is propagated.
-- Email comments, additions, corrections, gripes, kudos, etc. to:
Magnus Kempe -- Magnus.Kempe@di.epfl.ch
Copyright statement
Page last generated: 95-03-12