A.4 String Handling
This Reference Manual output has not been verified, and may contain omissions or errors. Report any problems on the tracking issue
This subclause presents the specifications of the package Strings and several child packages, which provide facilities for dealing with string data. Fixed-length, bounded-length, and unbounded-length strings are supported, for String, Wide_String, and Wide_Wide_String. The string-handling subprograms include searches for pattern strings and for characters in program-specified sets, translation (via a character-to-character mapping), and transformation (replacing, inserting, overwriting, and deleting of substrings).
Extensions to Ada 83
Wording Changes from Ada 95
A.4.1 The Package Strings
1The package Strings provides declarations common to the string handling packages.
Static Semantics
2The library package Strings has the following declaration:
package Ada.Strings
with Pure is
4/2Space : constant Character := ' ';
Wide_Space : constant Wide_Character := ' ';
Wide_Wide_Space : constant Wide_Wide_Character := ' ';
5Length_Error, Pattern_Error, Index_Error, Translation_Error : exception;
6type Alignment is (Left, Right, Center);
type Truncation is (Left, Right, Error);
type Membership is (Inside, Outside);
type Direction is (Forward, Backward);
type Trim_End is (Left, Right, Both);
end Ada.Strings;
Incompatibilities With Ada 95
use_clause, and an entity E with a defining_identifier of Wide_Wide_Space 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. A.4.2 The Package Strings.Maps
1/5The package Strings.Maps defines the types, operations, and other entities necessary for character sets and character-to-character mappings.
Static Semantics
2The library package Strings.Maps has the following declaration:
package Ada.Strings.Maps
with Pure is
4/5-- Representation for a set of character values:
type Character_Set is private
with Preelaborable_Initialization ;
5Null_Set : constant Character_Set;
6type Character_Range is
record
Low : Character;
High : Character;
end record;
-- Represents Character range Low..High
7type Character_Ranges is array (Positive range <>) of Character_Range;
8function To_Set (Ranges : in Character_Ranges)return Character_Set;
9function To_Set (Span : in Character_Range)return Character_Set;
10function To_Ranges (Set : in Character_Set) return Character_Ranges;
11function "=" (Left, Right : in Character_Set) return Boolean;
12function "not" (Right : in Character_Set) return Character_Set;
function "and" (Left, Right : in Character_Set) return Character_Set;
function "or" (Left, Right : in Character_Set) return Character_Set;
function "xor" (Left, Right : in Character_Set) return Character_Set;
function "-" (Left, Right : in Character_Set) return Character_Set;
13function Is_In (Element : in Character;
Set : in Character_Set)
return Boolean;
14function Is_Subset (Elements : in Character_Set;
Set : in Character_Set)
return Boolean;
15function "<=" (Left : in Character_Set;
Right : in Character_Set)
return Boolean renames Is_Subset;
16-- Alternative representation for a set of character values:
subtype Character_Sequence is String;
17function To_Set (Sequence : in Character_Sequence)return Character_Set;
18function To_Set (Singleton : in Character) return Character_Set;
19function To_Sequence (Set : in Character_Set) return Character_Sequence;
20/5-- Representation for a character to character mapping:
type Character_Mapping is private
with Preelaborable_Initialization ;
21function Value (Map : in Character_Mapping;
Element : in Character)
return Character;
22Identity : constant Character_Mapping;
23function To_Mapping (From, To : in Character_Sequence)
return Character_Mapping;
24function To_Domain (Map : in Character_Mapping)
return Character_Sequence;
function To_Range (Map : in Character_Mapping)
return Character_Sequence;
25type Character_Mapping_Function is
access function (From : in Character) return Character;
26private
... -- not specified by the language
end Ada.Strings.Maps;
An object of type Character_Set represents a set of characters.
Null_Set represents the set containing no characters.
An object Obj of type Character_Range represents the set of characters in the range Obj.Low .. Obj.High.
An object Obj of type Character_Ranges represents the union of the sets corresponding to Obj(I) for I in Obj'Range.
function To_Set (Ranges : in Character_Ranges) return Character_Set;
If Ranges'Length=0 then Null_Set is returned; otherwise, the returned value represents the set corresponding to Ranges.
function To_Set (Span : in Character_Range) return Character_Set;
The returned value represents the set containing each character in Span.
function To_Ranges (Set : in Character_Set) return Character_Ranges;
If Set = Null_Set, then an empty Character_Ranges array is returned; otherwise, the shortest array of contiguous ranges of Character values in Set, in increasing order of Low, is returned.
function "=" (Left, Right : in Character_Set) return Boolean;
The function "=" returns True if Left and Right represent identical sets, and False otherwise.
Each of the logical operators "not", "and", "or", and "xor" returns a Character_Set value that represents the set obtained by applying the corresponding operation to the set(s) represented by the parameter(s) of the operator. "–"(Left, Right) is equivalent to "and"(Left, "not"(Right)).
function Is_In (Element : in Character;
Set : in Character_Set);
return Boolean;
Is_In returns True if Element is in Set, and False otherwise.
function Is_Subset (Elements : in Character_Set;
Set : in Character_Set)
return Boolean;
Is_Subset returns True if Elements is a subset of Set, and False otherwise.
subtype Character_Sequence is String;
The Character_Sequence subtype is used to portray a set of character values and also to identify the domain and range of a character mapping.
function To_Set (Sequence : in Character_Sequence) return Character_Set;
function To_Set (Singleton : in Character) return Character_Set;
Sequence portrays the set of character values that it explicitly contains (ignoring duplicates). Singleton portrays the set comprising a single Character. Each of the To_Set functions returns a Character_Set value that represents the set portrayed by Sequence or Singleton.
function To_Sequence (Set : in Character_Set) return Character_Sequence;
The function To_Sequence returns a Character_Sequence value containing each of the characters in the set represented by Set, in ascending order with no duplicates.
type Character_Mapping is private;
An object of type Character_Mapping represents a Character-to-Character mapping.
function Value (Map : in Character_Mapping;
Element : in Character)
return Character;
The function Value returns the Character value to which Element maps with respect to the mapping represented by Map.
A character C matches a pattern character P with respect to a given Character_Mapping value Map if Value(Map, C) = P. A string S matches a pattern string P with respect to a given Character_Mapping if their lengths are the same and if each character in S matches its corresponding character in the pattern string P.
String handling subprograms that deal with character mappings have parameters whose type is Character_Mapping.
Identity : constant Character_Mapping;
Identity maps each Character to itself.
function To_Mapping (From, To : in Character_Sequence)
return Character_Mapping;
To_Mapping produces a Character_Mapping such that each element of From maps to the corresponding element of To, and each other character maps to itself. If From'Length /= To'Length, or if some character is repeated in From, then Translation_Error is propagated.
function To_Domain (Map : in Character_Mapping) return Character_Sequence;
To_Domain returns the shortest Character_Sequence value D such that each character not in D maps to itself, and such that the characters in D are in ascending order. The lower bound of D is 1.
function To_Range (Map : in Character_Mapping) return Character_Sequence;
{8652/0048} To_Range returns the Character_Sequence value R, such that if D = To_Domain(Map), then R has the same bounds as D, and D(I) maps to R(I) for each I in D'Range.
An object F of type Character_Mapping_Function maps a Character value C to the Character value F.all(C), which is said to match C with respect to mapping function F.
Examples
67/5Example of use of Strings.Maps.To_Mapping:
To_Mapping("ABCD", "ZZAB") returns a Character_Mapping that maps 'A' and 'B' to 'Z', 'C' to 'A', 'D' to 'B', and each other Character to itself.
Extensions to Ada 95
pragma Preelaborable_Initialization to types Character_Set and Character_Mapping, so that they can be used to declare default-initialized objects in preelaborated units.Wording Changes from Ada 95
A.4.3 Fixed-Length String Handling
1The 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.
For each function that returns a String, the lower bound of the returned value is 1.
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
4The library package Strings.Fixed has the following declaration:
with Ada.Strings.Maps;
package Ada.Strings.Fixed
with Preelaborate, Nonblocking, Global => in out synchronized is
6-- "Copy" procedure for strings of possibly different lengths
7procedure Move (Source : in String;
Target : out String;
Drop : in Truncation := Error;
Justify : in Alignment := Left;
Pad : in Character := Space);
8-- Search subprograms
8.1/2function 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/2function Index (Source : in String;
Pattern : in String;
From : in Positive;
Going : in Direction := Forward;
Mapping : in Maps.Character_Mapping_Function)
return Natural;
9function Index (Source : in String;
Pattern : in String;
Going : in Direction := Forward;
Mapping : in Maps.Character_Mapping
:= Maps.Identity)
return Natural;
10function Index (Source : in String;
Pattern : in String;
Going : in Direction := Forward;
Mapping : in Maps.Character_Mapping_Function)
return Natural;
10.1/2function Index (Source : in String;
Set : in Maps.Character_Set;
From : in Positive;
Test : in Membership := Inside;
Going : in Direction := Forward)
return Natural;
11function Index (Source : in String;
Set : in Maps.Character_Set;
Test : in Membership := Inside;
Going : in Direction := Forward)
return Natural;
11.1/2function Index_Non_Blank (Source : in String;
From : in Positive;
Going : in Direction := Forward)
return Natural;
12function Index_Non_Blank (Source : in String;
Going : in Direction := Forward)
return Natural;
13function Count (Source : in String;
Pattern : in String;
Mapping : in Maps.Character_Mapping
:= Maps.Identity)
return Natural;
14function Count (Source : in String;
Pattern : in String;
Mapping : in Maps.Character_Mapping_Function)
return Natural;
15function Count (Source : in String;
Set : in Maps.Character_Set)
return Natural;
15.1/3procedure Find_Token (Source : in String;
Set : in Maps.Character_Set;
From : in Positive;
Test : in Membership;
First : out Positive;
Last : out Natural);
16procedure Find_Token (Source : in String;
Set : in Maps.Character_Set;
Test : in Membership;
First : out Positive;
Last : out Natural);
17-- String translation subprograms
18function Translate (Source : in String;
Mapping : in Maps.Character_Mapping)
return String;
19procedure Translate (Source : in out String;
Mapping : in Maps.Character_Mapping);
20function Translate (Source : in String;
Mapping : in Maps.Character_Mapping_Function)
return String;
21procedure Translate (Source : in out String;
Mapping : in Maps.Character_Mapping_Function);
22-- String transformation subprograms
23function Replace_Slice (Source : in String;
Low : in Positive;
High : in Natural;
By : in String)
return String;
24procedure 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);
25function Insert (Source : in String;
Before : in Positive;
New_Item : in String)
return String;
26procedure Insert (Source : in out String;
Before : in Positive;
New_Item : in String;
Drop : in Truncation := Error);
27function Overwrite (Source : in String;
Position : in Positive;
New_Item : in String)
return String;
28procedure Overwrite (Source : in out String;
Position : in Positive;
New_Item : in String;
Drop : in Truncation := Right);
29function Delete (Source : in String;
From : in Positive;
Through : in Natural)
return String;
30procedure 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;
32procedure Trim (Source : in out String;
Side : in Trim_End;
Justify : in Alignment := Left;
Pad : in Character := Space);
33function Trim (Source : in String;
Left : in Maps.Character_Set;
Right : in Maps.Character_Set)
return String;
34procedure Trim (Source : in out String;
Left : in Maps.Character_Set;
Right : in Maps.Character_Set;
Justify : in Alignment := Strings.Left;
Pad : in Character := Space);
35function Head (Source : in String;
Count : in Natural;
Pad : in Character := Space)
return String;
36procedure Head (Source : in out String;
Count : in Natural;
Justify : in Alignment := Left;
Pad : in Character := Space);
37function Tail (Source : in String;
Count : in Natural;
Pad : in Character := Space)
return String;
38procedure Tail (Source : in out String;
Count : in Natural;
Justify : in Alignment := Left;
Pad : in Character := Space);
39--String constructor functions
40function "*" (Left : in Natural;
Right : in Character) return String;
41function "*" (Left : in Natural;
Right : in String) return String;
42end Ada.Strings.Fixed;
The effects of the above subprograms are as follows.
procedure Move (Source : in String;
Target : out String;
Drop : in Truncation := Error;
Justify : in Alignment := Left;
Pad : in Character := Space);
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:
- If Justify=Left, then Source is copied into the first Source'Length characters of Target.
- If Justify=Right, then Source is copied into the last Source'Length characters of Target.
- 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.
- Pad is copied to each Target character not otherwise assigned.
If Source is longer than Target, then the effect is based on Drop.
- If Drop=Left, then the rightmost Target'Length characters of Source are copied into Target.
- If Drop=Right, then the leftmost Target'Length characters of Source are copied into Target.
- 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:
- 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.
- 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.
- Otherwise, Length_Error is propagated.
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;
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 Source is the null string, Index returns 0; otherwise, 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.
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;
If Going = Forward, returns
Index (Source, Pattern, Source'First, Forward, Mapping);
otherwise, returns
Index (Source, Pattern, Source'Last, Backward, Mapping);
function Index (Source : in String;
Set : in Maps.Character_Set;
From : in Positive;
Test : in Membership := Inside;
Going : in Direction := Forward)
return Natural;
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 Source is the null string, Index returns 0; otherwise, 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.
function Index (Source : in String;
Set : in Maps.Character_Set;
Test : in Membership := Inside;
Going : in Direction := Forward)
return Natural;
If Going = Forward, returns
Index (Source, Set, Source'First, Test, Forward);
otherwise, returns
Index (Source, Set, Source'Last, Test, Backward);
60.4/2function Index_Non_Blank (Source : in String;
From : in Positive;
Going : in Direction := Forward)
return Natural;
Returns Index (Source, Maps.To_Set(Space), From, Outside, Going);
function Index_Non_Blank (Source : in String;
Going : in Direction := Forward)
return Natural;
Returns Index(Source, Maps.To_Set(Space), Outside, Going)
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;
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.
function Count (Source : in String;
Set : in Maps.Character_Set)
return Natural;
Returns the number of occurrences in Source of characters that are in Set.
procedure Find_Token (Source : in String;
Set : in Maps.Character_Set;
From : in Positive;
Test : in Membership;
First : out Positive;
Last : out Natural);
If Source is not the null string and From is not in Source'Range, then Index_Error is raised. Otherwise, First is set to the index of the first character in Source(From .. Source'Last) that satisfies the Test condition. Last is set to the largest index such that all characters in Source(First .. Last) satisfy the Test condition. If no characters in Source(From .. Source'Last) satisfy the Test condition, First is set to From, and Last is set to 0.
procedure Find_Token (Source : in String;
Set : in Maps.Character_Set;
Test : in Membership;
First : out Positive;
Last : out Natural);
{8652/0049} Equivalent to Find_Token (Source, Set, Source'First, Test, First, Last).
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;
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.
procedure Translate (Source : in out String;
Mapping : in Maps.Character_Mapping);
procedure Translate (Source : in out String;
Mapping : in Maps.Character_Mapping_Function);
Equivalent to Source := Translate(Source, Mapping).
function Replace_Slice (Source : in String;
Low : in Positive;
High : in Natural;
By : in String)
return String;
{8652/0049} If Low > Source'Last+1, or High < Source'First–1, then Index_Error is propagated. Otherwise:
- {8652/0049} If High >= Low, then the returned string comprises Source(Source'First..Low–1) & By & Source(High+1..Source'Last), but with lower bound 1.
- {8652/0049} If High < Low, then the returned string is Insert(Source, Before=>Low, New_Item=>By).
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);
Equivalent to Move(Replace_Slice(Source, Low, High, By), Source, Drop, Justify, Pad).
function Insert (Source : in String;
Before : in Positive;
New_Item : in String)
return String;
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.
procedure Insert (Source : in out String;
Before : in Positive;
New_Item : in String;
Drop : in Truncation := Error);
Equivalent to Move(Insert(Source, Before, New_Item), Source, Drop).
function Overwrite (Source : in String;
Position : in Positive;
New_Item : in String)
return String;
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.
procedure Overwrite (Source : in out String;
Position : in Positive;
New_Item : in String;
Drop : in Truncation := Right);
Equivalent to Move(Overwrite(Source, Position, New_Item), Source, Drop).
function Delete (Source : in String;
From : in Positive;
Through : in Natural)
return String;
{8652/0049} If From <= Through, the returned string is Replace_Slice(Source, From, Through, ""); otherwise, it is Source with lower bound 1.
procedure Delete (Source : in out String;
From : in Positive;
Through : in Natural;
Justify : in Alignment := Left;
Pad : in Character := Space);
Equivalent to Move(Delete(Source, From, Through), Source, Justify => Justify, Pad => Pad).
function Trim (Source : in String;
Side : in Trim_End)
return String;
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).
procedure Trim (Source : in out String;
Side : in Trim_End;
Justify : in Alignment := Left;
Pad : in Character := Space);
Equivalent to Move(Trim(Source, Side), Source, Justify=>Justify, Pad=>Pad).
function Trim (Source : in String;
Left : in Maps.Character_Set;
Right : in Maps.Character_Set)
return String;
Returns the string obtained by removing from Source all leading characters in Left and all trailing characters in Right.
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);
Equivalent to Move(Trim(Source, Left, Right), Source, Justify => Justify, Pad=>Pad).
function Head (Source : in String;
Count : in Natural;
Pad : in Character := Space)
return String;
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.
procedure Head (Source : in out String;
Count : in Natural;
Justify : in Alignment := Left;
Pad : in Character := Space);
Equivalent to Move(Head(Source, Count, Pad), Source, Drop=>Error, Justify=>Justify, Pad=>Pad).
function Tail (Source : in String;
Count : in Natural;
Pad : in Character := Space)
return String;
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.
procedure Tail (Source : in out String;
Count : in Natural;
Justify : in Alignment := Left;
Pad : in Character := Space);
Equivalent to Move(Tail(Source, Count, Pad), Source, Drop=>Error, Justify=>Justify, Pad=>Pad).
function "*" (Left : in Natural;
Right : in Character) return String;
function "*" (Left : in Natural;
Right : in String) return String;
{8652/0049} 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.
Incompatibilities With Ada 95
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
Incompatibilities With Ada 2005
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. Wording Changes from Ada 2005
A.4.4 Bounded-Length String Handling
1/5The 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 necessary to reflect the variability in length. Additionally, since the Bounded_String type is private, appropriate constructor and selector operations are provided.
Static Semantics
2The library package Strings.Bounded has the following declaration:
with Ada.Strings.Maps;
package Ada.Strings.Bounded
with Preelaborate, Nonblocking, Global => in out synchronized is
4generic
Max : Positive; -- Maximum length of a Bounded_String
package Generic_Bounded_Length is
5Max_Length : constant Positive := Max;
6type Bounded_String is private;
7Null_Bounded_String : constant Bounded_String;
8subtype Length_Range is Natural range 0 .. Max_Length;
9function Length (Source : in Bounded_String) return Length_Range;
10-- Conversion, Concatenation, and Selection functions
11function To_Bounded_String (Source : in String;
Drop : in Truncation := Error)
return Bounded_String;
12function To_String (Source : in Bounded_String) return String;
12.1/2procedure Set_Bounded_String
(Target : out Bounded_String;
Source : in String;
Drop : in Truncation := Error);
13function Append (Left, Right : in Bounded_String;
Drop : in Truncation := Error)
return Bounded_String;
14function Append (Left : in Bounded_String;
Right : in String;
Drop : in Truncation := Error)
return Bounded_String;
15function Append (Left : in String;
Right : in Bounded_String;
Drop : in Truncation := Error)
return Bounded_String;
16function Append (Left : in Bounded_String;
Right : in Character;
Drop : in Truncation := Error)
return Bounded_String;
17function Append (Left : in Character;
Right : in Bounded_String;
Drop : in Truncation := Error)
return Bounded_String;
18procedure Append (Source : in out Bounded_String;
New_Item : in Bounded_String;
Drop : in Truncation := Error);
19procedure Append (Source : in out Bounded_String;
New_Item : in String;
Drop : in Truncation := Error);
20procedure Append (Source : in out Bounded_String;
New_Item : in Character;
Drop : in Truncation := Error);
21function "&" (Left, Right : in Bounded_String)
return Bounded_String;
22function "&" (Left : in Bounded_String; Right : in String)
return Bounded_String;
23function "&" (Left : in String; Right : in Bounded_String)
return Bounded_String;
24function "&" (Left : in Bounded_String; Right : in Character)
return Bounded_String;
25function "&" (Left : in Character; Right : in Bounded_String)
return Bounded_String;
26function Element (Source : in Bounded_String;
Index : in Positive)
return Character;
27procedure Replace_Element (Source : in out Bounded_String;
Index : in Positive;
By : in Character);
28function Slice (Source : in Bounded_String;
Low : in Positive;
High : in Natural)
return String;
28.1/2function Bounded_Slice
(Source : in Bounded_String;
Low : in Positive;
High : in Natural)
return Bounded_String;
28.2/2procedure Bounded_Slice
(Source : in Bounded_String;
Target : out Bounded_String;
Low : in Positive;
High : in Natural);
29function "=" (Left, Right : in Bounded_String) return Boolean;
function "=" (Left : in Bounded_String; Right : in String)
return Boolean;
30function "=" (Left : in String; Right : in Bounded_String)
return Boolean;
31function "<" (Left, Right : in Bounded_String) return Boolean;
32function "<" (Left : in Bounded_String; Right : in String)
return Boolean;
33function "<" (Left : in String; Right : in Bounded_String)
return Boolean;
34function "<=" (Left, Right : in Bounded_String) return Boolean;
35function "<=" (Left : in Bounded_String; Right : in String)
return Boolean;
36function "<=" (Left : in String; Right : in Bounded_String)
return Boolean;
37function ">" (Left, Right : in Bounded_String) return Boolean;
38function ">" (Left : in Bounded_String; Right : in String)
return Boolean;
39function ">" (Left : in String; Right : in Bounded_String)
return Boolean;
40function ">=" (Left, Right : in Bounded_String) return Boolean;
41function ">=" (Left : in Bounded_String; Right : in String)
return Boolean;
42function ">=" (Left : in String; Right : in Bounded_String)
return Boolean;
43/2-- Search subprograms
43.1/2function 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/2function Index (Source : in Bounded_String;
Pattern : in String;
From : in Positive;
Going : in Direction := Forward;
Mapping : in Maps.Character_Mapping_Function)
return Natural;
44function Index (Source : in Bounded_String;
Pattern : in String;
Going : in Direction := Forward;
Mapping : in Maps.Character_Mapping
:= Maps.Identity)
return Natural;
45function Index (Source : in Bounded_String;
Pattern : in String;
Going : in Direction := Forward;
Mapping : in Maps.Character_Mapping_Function)
return Natural;
45.1/2function Index (Source : in Bounded_String;
Set : in Maps.Character_Set;
From : in Positive;
Test : in Membership := Inside;
Going : in Direction := Forward)
return Natural;
46function Index (Source : in Bounded_String;
Set : in Maps.Character_Set;
Test : in Membership := Inside;
Going : in Direction := Forward)
return Natural;
46.1/2function Index_Non_Blank (Source : in Bounded_String;
From : in Positive;
Going : in Direction := Forward)
return Natural;
47function Index_Non_Blank (Source : in Bounded_String;
Going : in Direction := Forward)
return Natural;
48function Count (Source : in Bounded_String;
Pattern : in String;
Mapping : in Maps.Character_Mapping
:= Maps.Identity)
return Natural;
49function Count (Source : in Bounded_String;
Pattern : in String;
Mapping : in Maps.Character_Mapping_Function)
return Natural;
50function Count (Source : in Bounded_String;
Set : in Maps.Character_Set)
return Natural;
50.1/3procedure Find_Token (Source : in Bounded_String;
Set : in Maps.Character_Set;
From : in Positive;
Test : in Membership;
First : out Positive;
Last : out Natural);
51procedure Find_Token (Source : in Bounded_String;
Set : in Maps.Character_Set;
Test : in Membership;
First : out Positive;
Last : out Natural);
52-- String translation subprograms
53function Translate (Source : in Bounded_String;
Mapping : in Maps.Character_Mapping)
return Bounded_String;
54procedure Translate (Source : in out Bounded_String;
Mapping : in Maps.Character_Mapping);
55function Translate (Source : in Bounded_String;
Mapping : in Maps.Character_Mapping_Function)
return Bounded_String;
56procedure Translate (Source : in out Bounded_String;
Mapping : in Maps.Character_Mapping_Function);
57-- String transformation subprograms
58function Replace_Slice (Source : in Bounded_String;
Low : in Positive;
High : in Natural;
By : in String;
Drop : in Truncation := Error)
return Bounded_String;
59procedure Replace_Slice (Source : in out Bounded_String;
Low : in Positive;
High : in Natural;
By : in String;
Drop : in Truncation := Error);
60function Insert (Source : in Bounded_String;
Before : in Positive;
New_Item : in String;
Drop : in Truncation := Error)
return Bounded_String;
61procedure Insert (Source : in out Bounded_String;
Before : in Positive;
New_Item : in String;
Drop : in Truncation := Error);
62function Overwrite (Source : in Bounded_String;
Position : in Positive;
New_Item : in String;
Drop : in Truncation := Error)
return Bounded_String;
63procedure Overwrite (Source : in out Bounded_String;
Position : in Positive;
New_Item : in String;
Drop : in Truncation := Error);
64function Delete (Source : in Bounded_String;
From : in Positive;
Through : in Natural)
return Bounded_String;
65procedure Delete (Source : in out Bounded_String;
From : in Positive;
Through : in Natural);
66--String selector subprograms
67function Trim (Source : in Bounded_String;
Side : in Trim_End)
return Bounded_String;
procedure Trim (Source : in out Bounded_String;
Side : in Trim_End);
68function Trim (Source : in Bounded_String;
Left : in Maps.Character_Set;
Right : in Maps.Character_Set)
return Bounded_String;
69procedure Trim (Source : in out Bounded_String;
Left : in Maps.Character_Set;
Right : in Maps.Character_Set);
70function Head (Source : in Bounded_String;
Count : in Natural;
Pad : in Character := Space;
Drop : in Truncation := Error)
return Bounded_String;
71procedure Head (Source : in out Bounded_String;
Count : in Natural;
Pad : in Character := Space;
Drop : in Truncation := Error);
72function Tail (Source : in Bounded_String;
Count : in Natural;
Pad : in Character := Space;
Drop : in Truncation := Error)
return Bounded_String;
73procedure Tail (Source : in out Bounded_String;
Count : in Natural;
Pad : in Character := Space;
Drop : in Truncation := Error);
74--String constructor subprograms
75function "*" (Left : in Natural;
Right : in Character)
return Bounded_String;
76function "*" (Left : in Natural;
Right : in String)
return Bounded_String;
77function "*" (Left : in Natural;
Right : in Bounded_String)
return Bounded_String;
78function Replicate (Count : in Natural;
Item : in Character;
Drop : in Truncation := Error)
return Bounded_String;
79function Replicate (Count : in Natural;
Item : in String;
Drop : in Truncation := Error)
return Bounded_String;
80function Replicate (Count : in Natural;
Item : in Bounded_String;
Drop : in Truncation := Error)
return Bounded_String;
81private
... -- not specified by the language
end Generic_Bounded_Length;
82end 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)).
procedure Set_Bounded_String
(Target : out Bounded_String;
Source : in String;
Drop : in Truncation := Error);
Equivalent to Target := To_Bounded_String (Source, Drop);
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;
{8652/0049} 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.
function Bounded_Slice
(Source : in Bounded_String;
Low : in Positive;
High : in Natural)
return Bounded_String;
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).
procedure Bounded_Slice
(Source : in Bounded_String;
Target : out Bounded_String;
Low : in Positive;
High : in Natural);
Equivalent to Target := Bounded_Slice (Source, Low, High);
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.
{8652/0049} 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
106Bounded string objects should not be implemented by implicit pointers and dynamic allocation.
type Bounded_String_Internals (Length : Length_Range := 0) is
record
Data : String(1..Length);
end record;
106.ctype Bounded_String is
record
Data : Bounded_String_Internals; -- Unconstrained
end record;
106.dNull_Bounded_String : constant Bounded_String :=
(Data => (Length => 0,
Data => (1..0 => ' ')));
Inconsistencies With Ada 95
Incompatibilities With Ada 95
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
Incompatibilities With Ada 2005
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. A.4.5 Unbounded-Length String Handling
1/5The 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 necessary to reflect the flexibility in length. Since the Unbounded_String type is private, relevant constructor and selector operations are provided.
Static Semantics
2The library package Strings.Unbounded has the following declaration:
with Ada.Strings.Maps;
package Ada.Strings.Unbounded
with Preelaborate, Nonblocking, Global => in out synchronized is
4/5type Unbounded_String is private
with Preelaborable_Initialization ;
5Null_Unbounded_String : constant Unbounded_String;
6function Length (Source : in Unbounded_String) return Natural;
7type String_Access is access all String;
procedure Free (X : in out String_Access);
8-- Conversion, Concatenation, and Selection functions
9function To_Unbounded_String (Source : in String)
return Unbounded_String;
10function To_Unbounded_String (Length : in Natural)
return Unbounded_String;
11function To_String (Source : in Unbounded_String) return String;
11.1/2procedure Set_Unbounded_String
(Target : out Unbounded_String;
Source : in String);
12procedure Append (Source : in out Unbounded_String;
New_Item : in Unbounded_String);
13procedure Append (Source : in out Unbounded_String;
New_Item : in String);
14procedure Append (Source : in out Unbounded_String;
New_Item : in Character);
15function "&" (Left, Right : in Unbounded_String)
return Unbounded_String;
16function "&" (Left : in Unbounded_String; Right : in String)
return Unbounded_String;
17function "&" (Left : in String; Right : in Unbounded_String)
return Unbounded_String;
18function "&" (Left : in Unbounded_String; Right : in Character)
return Unbounded_String;
19function "&" (Left : in Character; Right : in Unbounded_String)
return Unbounded_String;
20function Element (Source : in Unbounded_String;
Index : in Positive)
return Character;
21procedure Replace_Element (Source : in out Unbounded_String;
Index : in Positive;
By : in Character);
22function Slice (Source : in Unbounded_String;
Low : in Positive;
High : in Natural)
return String;
22.1/2function Unbounded_Slice
(Source : in Unbounded_String;
Low : in Positive;
High : in Natural)
return Unbounded_String;
22.2/2procedure Unbounded_Slice
(Source : in Unbounded_String;
Target : out Unbounded_String;
Low : in Positive;
High : in Natural);
23function "=" (Left, Right : in Unbounded_String) return Boolean;
24function "=" (Left : in Unbounded_String; Right : in String)
return Boolean;
25function "=" (Left : in String; Right : in Unbounded_String)
return Boolean;
26function "<" (Left, Right : in Unbounded_String) return Boolean;
27function "<" (Left : in Unbounded_String; Right : in String)
return Boolean;
28function "<" (Left : in String; Right : in Unbounded_String)
return Boolean;
29function "<=" (Left, Right : in Unbounded_String) return Boolean;
30function "<=" (Left : in Unbounded_String; Right : in String)
return Boolean;
31function "<=" (Left : in String; Right : in Unbounded_String)
return Boolean;
32function ">" (Left, Right : in Unbounded_String) return Boolean;
33function ">" (Left : in Unbounded_String; Right : in String)
return Boolean;
34function ">" (Left : in String; Right : in Unbounded_String)
return Boolean;
35function ">=" (Left, Right : in Unbounded_String) return Boolean;
36function ">=" (Left : in Unbounded_String; Right : in String)
return Boolean;
37function ">=" (Left : in String; Right : in Unbounded_String)
return Boolean;
38-- Search subprograms
38.1/2function Index (Source : in Unbounded_String;
Pattern : in String;
From : in Positive;
Going : in Direction := Forward;
Mapping : in Maps.Character_Mapping := Maps.Identity)
return Natural;
38.2/2function Index (Source : in Unbounded_String;
Pattern : in String;
From : in Positive;
Going : in Direction := Forward;
Mapping : in Maps.Character_Mapping_Function)
return Natural;
39function Index (Source : in Unbounded_String;
Pattern : in String;
Going : in Direction := Forward;
Mapping : in Maps.Character_Mapping
:= Maps.Identity)
return Natural;
40function Index (Source : in Unbounded_String;
Pattern : in String;
Going : in Direction := Forward;
Mapping : in Maps.Character_Mapping_Function)
return Natural;
40.1/2function Index (Source : in Unbounded_String;
Set : in Maps.Character_Set;
From : in Positive;
Test : in Membership := Inside;
Going : in Direction := Forward)
return Natural;
41function Index (Source : in Unbounded_String;
Set : in Maps.Character_Set;
Test : in Membership := Inside;
Going : in Direction := Forward) return Natural;
41.1/2function Index_Non_Blank (Source : in Unbounded_String;
From : in Positive;
Going : in Direction := Forward)
return Natural;
42function Index_Non_Blank (Source : in Unbounded_String;
Going : in Direction := Forward)
return Natural;
43function Count (Source : in Unbounded_String;
Pattern : in String;
Mapping : in Maps.Character_Mapping
:= Maps.Identity)
return Natural;
44function Count (Source : in Unbounded_String;
Pattern : in String;
Mapping : in Maps.Character_Mapping_Function)
return Natural;
45function Count (Source : in Unbounded_String;
Set : in Maps.Character_Set)
return Natural;
45.1/3procedure Find_Token (Source : in Unbounded_String;
Set : in Maps.Character_Set;
From : in Positive;
Test : in Membership;
First : out Positive;
Last : out Natural);
46procedure Find_Token (Source : in Unbounded_String;
Set : in Maps.Character_Set;
Test : in Membership;
First : out Positive;
Last : out Natural);
47-- String translation subprograms
48function Translate (Source : in Unbounded_String;
Mapping : in Maps.Character_Mapping)
return Unbounded_String;
49procedure Translate (Source : in out Unbounded_String;
Mapping : in Maps.Character_Mapping);
50function Translate (Source : in Unbounded_String;
Mapping : in Maps.Character_Mapping_Function)
return Unbounded_String;
51procedure Translate (Source : in out Unbounded_String;
Mapping : in Maps.Character_Mapping_Function);
52-- String transformation subprograms
53function Replace_Slice (Source : in Unbounded_String;
Low : in Positive;
High : in Natural;
By : in String)
return Unbounded_String;
54procedure Replace_Slice (Source : in out Unbounded_String;
Low : in Positive;
High : in Natural;
By : in String);
55function Insert (Source : in Unbounded_String;
Before : in Positive;
New_Item : in String)
return Unbounded_String;
56procedure Insert (Source : in out Unbounded_String;
Before : in Positive;
New_Item : in String);
57function Overwrite (Source : in Unbounded_String;
Position : in Positive;
New_Item : in String)
return Unbounded_String;
58procedure Overwrite (Source : in out Unbounded_String;
Position : in Positive;
New_Item : in String);
59function Delete (Source : in Unbounded_String;
From : in Positive;
Through : in Natural)
return Unbounded_String;
60procedure Delete (Source : in out Unbounded_String;
From : in Positive;
Through : in Natural);
61function Trim (Source : in Unbounded_String;
Side : in Trim_End)
return Unbounded_String;
62procedure Trim (Source : in out Unbounded_String;
Side : in Trim_End);
63function Trim (Source : in Unbounded_String;
Left : in Maps.Character_Set;
Right : in Maps.Character_Set)
return Unbounded_String;
64procedure Trim (Source : in out Unbounded_String;
Left : in Maps.Character_Set;
Right : in Maps.Character_Set);
65function Head (Source : in Unbounded_String;
Count : in Natural;
Pad : in Character := Space)
return Unbounded_String;
66procedure Head (Source : in out Unbounded_String;
Count : in Natural;
Pad : in Character := Space);
67function Tail (Source : in Unbounded_String;
Count : in Natural;
Pad : in Character := Space)
return Unbounded_String;
68procedure Tail (Source : in out Unbounded_String;
Count : in Natural;
Pad : in Character := Space);
69function "*" (Left : in Natural;
Right : in Character)
return Unbounded_String;
70function "*" (Left : in Natural;
Right : in String)
return Unbounded_String;
71function "*" (Left : in Natural;
Right : in Unbounded_String)
return Unbounded_String;
72private
... -- not specified by the language
end Ada.Strings.Unbounded;
The type Unbounded_String needs finalization (see 7.6).
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 (nonprivate) 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.
The procedure Set_Unbounded_String sets Target to an Unbounded_String that represents Source.
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.
The function Unbounded_Slice returns the slice at positions Low through High in the string represented by Source as an Unbounded_String. The procedure Unbounded_Slice sets Target to the Unbounded_String representing the slice at positions Low through High in the string represented by Source. Both subprograms propagate 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 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
88No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.
Incompatibilities With Ada 95
use_clause, and an entity E with the same defining_identifier as a new entity in Strings.Unbounded 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. Extensions to Ada 95
pragma Preelaborable_Initialization to type Unbounded_String, so that it can be used to declare default-initialized objects in preelaborated units. Incompatibilities With Ada 2005
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. A.4.6 String-Handling Sets and Mappings
1The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.
Static Semantics
2The library package Strings.Maps.Constants has the following declaration:
package Ada.Strings.Maps.Constants
with Pure is
4Control_Set : constant Character_Set;
Graphic_Set : constant Character_Set;
Letter_Set : constant Character_Set;
Lower_Set : constant Character_Set;
Upper_Set : constant Character_Set;
Basic_Set : constant Character_Set;
Decimal_Digit_Set : constant Character_Set;
Hexadecimal_Digit_Set : constant Character_Set;
Alphanumeric_Set : constant Character_Set;
Special_Set : constant Character_Set;
ISO_646_Set : constant Character_Set;
5Lower_Case_Map : constant Character_Mapping;
--Maps to lower case for letters, else identity
Upper_Case_Map : constant Character_Mapping;
--Maps to upper case for letters, else identity
Basic_Map : constant Character_Mapping;
--Maps to basic letter for letters, else identity
6private
... -- not specified by the language
end Ada.Strings.Maps.Constants;
Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling (see A.3.2).
Extensions to Ada 95
Wording Changes from Ada 2005
A.4.7 Wide_String Handling
1/3Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants, and in the library functions Strings.Wide_Hash, Strings.Wide_Fixed.Wide_Hash, Strings.Wide_Bounded.Wide_Hash, Strings.Wide_Unbounded.Wide_Hash, Strings.Wide_Hash_Case_Insensitive, Strings.Wide_Fixed.Wide_Hash_Case_Insensitive, Strings.Wide_Bounded.Wide_Hash_Case_Insensitive, Strings.Wide_Unbounded.Wide_Hash_Case_Insensitive, Strings.Wide_Equal_Case_Insensitive, Strings.Wide_Fixed.Wide_Equal_Case_Insensitive, Strings.Wide_Bounded.Wide_Equal_Case_Insensitive, and Strings.Wide_Unbounded.Wide_Equal_Case_Insensitive. They provide the same string-handling operations as the corresponding packages and functions for strings of Character elements.
Static Semantics
2The package Strings.Wide_Maps has the following declaration.
package Ada.Strings.Wide_Maps
with Preelaborate, Nonblocking, Global => in out synchronized is
4/5-- Representation for a set of Wide_Character values:
type Wide_Character_Set is private
with Preelaborable_Initialization ;
5Null_Set : constant Wide_Character_Set;
6type Wide_Character_Range is
record
Low : Wide_Character;
High : Wide_Character;
end record;
-- Represents Wide_Character range Low..High
7type Wide_Character_Ranges is array (Positive range <>)
of Wide_Character_Range;
8function To_Set (Ranges : in Wide_Character_Ranges)
return Wide_Character_Set;
9function To_Set (Span : in Wide_Character_Range)
return Wide_Character_Set;
10function To_Ranges (Set : in Wide_Character_Set)
return Wide_Character_Ranges;
11function "=" (Left, Right : in Wide_Character_Set) return Boolean;
12function "not" (Right : in Wide_Character_Set)
return Wide_Character_Set;
function "and" (Left, Right : in Wide_Character_Set)
return Wide_Character_Set;
function "or" (Left, Right : in Wide_Character_Set)
return Wide_Character_Set;
function "xor" (Left, Right : in Wide_Character_Set)
return Wide_Character_Set;
function "-" (Left, Right : in Wide_Character_Set)
return Wide_Character_Set;
13function Is_In (Element : in Wide_Character;
Set : in Wide_Character_Set)
return Boolean;
14function Is_Subset (Elements : in Wide_Character_Set;
Set : in Wide_Character_Set)
return Boolean;
15function "<=" (Left : in Wide_Character_Set;
Right : in Wide_Character_Set)
return Boolean renames Is_Subset;
16-- Alternative representation for a set of Wide_Character values:
subtype Wide_Character_Sequence is Wide_String;
17function To_Set (Sequence : in Wide_Character_Sequence)
return Wide_Character_Set;
18function To_Set (Singleton : in Wide_Character)
return Wide_Character_Set;
19function To_Sequence (Set : in Wide_Character_Set)
return Wide_Character_Sequence;
20/5-- Representation for a Wide_Character to Wide_Character mapping:
type Wide_Character_Mapping is private
with Preelaborable_Initialization ;
21function Value (Map : in Wide_Character_Mapping;
Element : in Wide_Character)
return Wide_Character;
22Identity : constant Wide_Character_Mapping;
23function To_Mapping (From, To : in Wide_Character_Sequence)
return Wide_Character_Mapping;
24function To_Domain (Map : in Wide_Character_Mapping)
return Wide_Character_Sequence;
25function To_Range (Map : in Wide_Character_Mapping)
return Wide_Character_Sequence;
26type Wide_Character_Mapping_Function is
access function (From : in Wide_Character) return Wide_Character;
27private
... -- not specified by the language
end Ada.Strings.Wide_Maps;
The context clause for each of the packages Strings.Wide_Fixed, Strings.Wide_Bounded, and Strings.Wide_Unbounded identifies Strings.Wide_Maps instead of Strings.Maps.
Types Wide_Character_Set and Wide_Character_Mapping need finalization.
For each of the packages Strings.Fixed, Strings.Bounded, Strings.Unbounded, and Strings.Maps.Constants, and for library functions Strings.Hash, Strings.Fixed.Hash, Strings.Bounded.Hash, Strings.Unbounded.Hash, Strings.Hash_Case_Insensitive, Strings.Fixed.Hash_Case_Insensitive, Strings.Bounded.Hash_Case_Insensitive, Strings.Unbounded.Hash_Case_Insensitive, Strings.Equal_Case_Insensitive, Strings.Fixed.Equal_Case_Insensitive, Strings.Bounded.Equal_Case_Insensitive, and Strings.Unbounded.Equal_Case_Insensitive, the corresponding wide string package or function has the same contents except that
- Wide_Space replaces Space
- Wide_Character replaces Character
- Wide_String replaces String
- Wide_Character_Set replaces Character_Set
- Wide_Character_Mapping replaces Character_Mapping
- Wide_Character_Mapping_Function replaces Character_Mapping_Function
- Wide_Maps replaces Maps
- Bounded_Wide_String replaces Bounded_String
- Null_Bounded_Wide_String replaces Null_Bounded_String
- To_Bounded_Wide_String replaces To_Bounded_String
- To_Wide_String replaces To_String
- Set_Bounded_Wide_String replaces Set_Bounded_String
- Unbounded_Wide_String replaces Unbounded_String
- Null_Unbounded_Wide_String replaces Null_Unbounded_String
- Wide_String_Access replaces String_Access
- To_Unbounded_Wide_String replaces To_Unbounded_String
- Set_Unbounded_Wide_String replaces Set_Unbounded_String
The following additional declaration is present in Strings.Wide_Maps.Wide_Constants:
Character_Set : constant Wide_Maps.Wide_Character_Set;
--Contains each Wide_Character value WC such that
--Characters.Conversions.Is_Character(WC) is True
Each Wide_Character_Set constant in the package Strings.Wide_Maps.Wide_Constants contains no values outside the Character portion of Wide_Character. Similarly, each Wide_Character_Mapping constant in this package is the identity mapping when applied to any element outside the Character portion of Wide_Character.
Aspect Pure is replaced by aspects Preelaborate, Nonblocking, Global => in out synchronized in Strings.Wide_Maps.Wide_Constants.
Incompatibilities With Ada 95
use_clause, and an entity E with the same defining_identifier as a new entity 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. Extensions to Ada 95
pragma Preelaborable_Initialization to types Wide_Character_Set and Wide_Character_Mapping, so that they can be used to declare default-initialized objects in preelaborated units. Wording Changes from Ada 95
Extensions to Ada 2005
Wording Changes from Ada 2005
A.4.8 Wide_Wide_String Handling
1/3Facilities for handling strings of Wide_Wide_Character elements are found in the packages Strings.Wide_Wide_Maps, Strings.Wide_Wide_Fixed, Strings.Wide_Wide_Bounded, Strings.Wide_Wide_Unbounded, and Strings.Wide_Wide_Maps.Wide_Wide_Constants, and in the library functions Strings.Wide_Wide_Hash, Strings.Wide_Wide_Fixed.Wide_Wide_Hash, Strings.Wide_Wide_Bounded.Wide_Wide_Hash, Strings.Wide_Wide_Unbounded.Wide_Wide_Hash, Strings.Wide_Wide_Hash_Case_Insensitive, Strings.Wide_Wide_Fixed.Wide_Wide_Hash_Case_Insensitive, Strings.Wide_Wide_Bounded.Wide_Wide_Hash_Case_Insensitive, Strings.Wide_Wide_Unbounded.Wide_Wide_Hash_Case_Insensitive, Strings.Wide_Wide_Equal_Case_Insensitive, Strings.Wide_Wide_Fixed.Wide_Wide_Equal_Case_Insensitive, Strings.Wide_Wide_Bounded.Wide_Wide_Equal_Case_Insensitive, and Strings.Wide_Wide_Unbounded.Wide_Wide_Equal_Case_Insensitive. They provide the same string-handling operations as the corresponding packages and functions for strings of Character elements.
Static Semantics
2/2The library package Strings.Wide_Wide_Maps has the following declaration.
package Ada.Strings.Wide_Wide_Maps
with Preelaborate, Nonblocking, Global => in out synchronized is
4/5-- Representation for a set of Wide_Wide_Character values:
type Wide_Wide_Character_Set is private
with Preelaborable_Initialization ;
5/2Null_Set : constant Wide_Wide_Character_Set;
6/2type Wide_Wide_Character_Range is
record
Low : Wide_Wide_Character;
High : Wide_Wide_Character;
end record;
-- Represents Wide_Wide_Character range Low..High
7/2type Wide_Wide_Character_Ranges is array (Positive range <>)
of Wide_Wide_Character_Range;
8/2function To_Set (Ranges : in Wide_Wide_Character_Ranges)
return Wide_Wide_Character_Set;
9/2function To_Set (Span : in Wide_Wide_Character_Range)
return Wide_Wide_Character_Set;
10/2function To_Ranges (Set : in Wide_Wide_Character_Set)
return Wide_Wide_Character_Ranges;
11/2function "=" (Left, Right : in Wide_Wide_Character_Set) return Boolean;
12/2function "not" (Right : in Wide_Wide_Character_Set)
return Wide_Wide_Character_Set;
function "and" (Left, Right : in Wide_Wide_Character_Set)
return Wide_Wide_Character_Set;
function "or" (Left, Right : in Wide_Wide_Character_Set)
return Wide_Wide_Character_Set;
function "xor" (Left, Right : in Wide_Wide_Character_Set)
return Wide_Wide_Character_Set;
function "-" (Left, Right : in Wide_Wide_Character_Set)
return Wide_Wide_Character_Set;
13/2function Is_In (Element : in Wide_Wide_Character;
Set : in Wide_Wide_Character_Set)
return Boolean;
14/2function Is_Subset (Elements : in Wide_Wide_Character_Set;
Set : in Wide_Wide_Character_Set)
return Boolean;
15/2function "<=" (Left : in Wide_Wide_Character_Set;
Right : in Wide_Wide_Character_Set)
return Boolean renames Is_Subset;
16/2-- Alternative representation for a set of Wide_Wide_Character values:
subtype Wide_Wide_Character_Sequence is Wide_Wide_String;
17/2function To_Set (Sequence : in Wide_Wide_Character_Sequence)
return Wide_Wide_Character_Set;
18/2function To_Set (Singleton : in Wide_Wide_Character)
return Wide_Wide_Character_Set;
19/2function To_Sequence (Set : in Wide_Wide_Character_Set)
return Wide_Wide_Character_Sequence;
20/5-- Representation for a Wide_Wide_Character to Wide_Wide_Character
-- mapping:
type Wide_Wide_Character_Mapping is private
with Preelaborable_Initialization ;
21/2function Value (Map : in Wide_Wide_Character_Mapping;
Element : in Wide_Wide_Character)
return Wide_Wide_Character;
22/2Identity : constant Wide_Wide_Character_Mapping;
23/2function To_Mapping (From, To : in Wide_Wide_Character_Sequence)
return Wide_Wide_Character_Mapping;
24/2function To_Domain (Map : in Wide_Wide_Character_Mapping)
return Wide_Wide_Character_Sequence;
25/2function To_Range (Map : in Wide_Wide_Character_Mapping)
return Wide_Wide_Character_Sequence;
26/2type Wide_Wide_Character_Mapping_Function is
access function (From : in Wide_Wide_Character)
return Wide_Wide_Character;
27/2private
... -- not specified by the language
end Ada.Strings.Wide_Wide_Maps;
The context clause for each of the packages Strings.Wide_Wide_Fixed, Strings.Wide_Wide_Bounded, and Strings.Wide_Wide_Unbounded identifies Strings.Wide_Wide_Maps instead of Strings.Maps.
Types Wide_Wide_Character_Set and Wide_Wide_Character_Mapping need finalization.
For each of the packages Strings.Fixed, Strings.Bounded, Strings.Unbounded, and Strings.Maps.Constants, and for library functions Strings.Hash, Strings.Fixed.Hash, Strings.Bounded.Hash, Strings.Unbounded.Hash, Strings.Hash_Case_Insensitive, Strings.Fixed.Hash_Case_Insensitive, Strings.Bounded.Hash_Case_Insensitive, Strings.Unbounded.Hash_Case_Insensitive, Strings.Equal_Case_Insensitive, Strings.Fixed.Equal_Case_Insensitive, Strings.Bounded.Equal_Case_Insensitive, and Strings.Unbounded.Equal_Case_Insensitive, the corresponding wide wide string package or function has the same contents except that
- Wide_Wide_Space replaces Space
- Wide_Wide_Character replaces Character
- Wide_Wide_String replaces String
- Wide_Wide_Character_Set replaces Character_Set
- Wide_Wide_Character_Mapping replaces Character_Mapping
- Wide_Wide_Character_Mapping_Function replaces Character_Mapping_Function
- Wide_Wide_Maps replaces Maps
- Bounded_Wide_Wide_String replaces Bounded_String
- Null_Bounded_Wide_Wide_String replaces Null_Bounded_String
- To_Bounded_Wide_Wide_String replaces To_Bounded_String
- To_Wide_Wide_String replaces To_String
- Set_Bounded_Wide_Wide_String replaces Set_Bounded_String
- Unbounded_Wide_Wide_String replaces Unbounded_String
- Null_Unbounded_Wide_Wide_String replaces Null_Unbounded_String
- Wide_Wide_String_Access replaces String_Access
- To_Unbounded_Wide_Wide_String replaces To_Unbounded_String
- Set_Unbounded_Wide_Wide_String replaces Set_Unbounded_String
The following additional declarations are present in Strings.Wide_Wide_Maps.Wide_Wide_Constants:
Character_Set : constant Wide_Wide_Maps.Wide_Wide_Character_Set;
-- Contains each Wide_Wide_Character value WWC such that
-- Characters.Conversions.Is_Character(WWC) is True
Wide_Character_Set : constant Wide_Wide_Maps.Wide_Wide_Character_Set;
-- Contains each Wide_Wide_Character value WWC such that
-- Characters.Conversions.Is_Wide_Character(WWC) is True
Each Wide_Wide_Character_Set constant in the package Strings.Wide_Wide_Maps.Wide_Wide_Constants contains no values outside the Character portion of Wide_Wide_Character. Similarly, each Wide_Wide_Character_Mapping constant in this package is the identity mapping when applied to any element outside the Character portion of Wide_Wide_Character.
Aspect Pure is replaced by aspects Preelaborate, Nonblocking, Global => in out synchronized in Strings.Wide_Wide_Maps.Wide_Wide_Constants.
Extensions to Ada 95
Extensions to Ada 2005
Wording Changes from Ada 2005
A.4.9 String Hashing
Static Semantics
1/2The library function Strings.Hash has the following declaration:
with Ada.Containers;
function Ada.Strings.Hash (Key : String) return Containers.Hash_Type
with Pure ;
Returns an implementation-defined value which is a function of the value of Key. If A and B are strings such that A equals B, Hash(A) equals Hash(B).
The library function Strings.Fixed.Hash has the following declaration:
with Ada.Containers, Ada.Strings.Hash;
function Ada.Strings.Fixed.Hash (Key : String) return Containers.Hash_Type
renames Ada.Strings.Hash;
The generic library function Strings.Bounded.Hash has the following declaration:
with Ada.Containers;
generic
with package Bounded is
new Ada.Strings.Bounded.Generic_Bounded_Length (<>);
function Ada.Strings.Bounded.Hash (Key : Bounded.Bounded_String)
return Containers.Hash_Type
with Preelaborate, Nonblocking, Global => in out synchronized ;
Equivalent to Strings.Hash (Bounded.To_String (Key));
The library function Strings.Unbounded.Hash has the following declaration:
with Ada.Containers;
function Ada.Strings.Unbounded.Hash (Key : Unbounded_String)
return Containers.Hash_Type
with Preelaborate, Nonblocking, Global => in out synchronized ;
Equivalent to Strings.Hash (To_String (Key));
The library function Strings.Hash_Case_Insensitive has the following declaration:
with Ada.Containers;
function Ada.Strings.Hash_Case_Insensitive (Key : String)
return Containers.Hash_Type
with Pure ;
Returns an implementation-defined value which is a function of the value of Key, converted to lower case. If A and B are strings such that Strings.Equal_Case_Insensitive (A, B) (see A.4.10) is True, then Hash_Case_Insensitive(A) equals Hash_Case_Insensitive(B).
The library function Strings.Fixed.Hash_Case_Insensitive has the following declaration:
with Ada.Containers, Ada.Strings.Hash_Case_Insensitive;
function Ada.Strings.Fixed.Hash_Case_Insensitive (Key : String)
return Containers.Hash_Type renames Ada.Strings.Hash_Case_Insensitive;
The generic library function Strings.Bounded.Hash_Case_Insensitive has the following declaration:
with Ada.Containers;
generic
with package Bounded is
new Ada.Strings.Bounded.Generic_Bounded_Length (<>);
function Ada.Strings.Bounded.Hash_Case_Insensitive
(Key : Bounded.Bounded_String) return Containers.Hash_Type
with Preelaborate, Nonblocking, Global => in out synchronized ;
Equivalent to Strings.Hash_Case_Insensitive (Bounded.To_String (Key));
The library function Strings.Unbounded.Hash_Case_Insensitive has the following declaration:
with Ada.Containers;
function Ada.Strings.Unbounded.Hash_Case_Insensitive
(Key : Unbounded_String) return Containers.Hash_Type
with Preelaborate, Nonblocking, Global => in out synchronized ;
Equivalent to Strings.Hash_Case_Insensitive (To_String (Key));
Implementation Advice
12/2The Hash functions should be good hash functions, returning a wide spread of values for different string values. It should be unlikely for similar strings to return the same value.
Extensions to Ada 95
Extensions to Ada 2005
A.4.10 String Comparison
Static Semantics
1/3The library function Strings.Equal_Case_Insensitive has the following declaration:
function Ada.Strings.Equal_Case_Insensitive (Left, Right : String)
return Boolean with Pure ;
Returns True if the strings consist of the same sequence of characters after applying locale-independent simple case folding, as defined by documents referenced in Clause 2 of ISO/IEC 10646:2020 . Otherwise, returns False. This function uses the same method as is used to determine whether two identifiers are the same.
The library function Strings.Fixed.Equal_Case_Insensitive has the following declaration:
with Ada.Strings.Equal_Case_Insensitive;
function Ada.Strings.Fixed.Equal_Case_Insensitive
(Left, Right : String) return Boolean
renames Ada.Strings.Equal_Case_Insensitive;
The generic library function Strings.Bounded.Equal_Case_Insensitive has the following declaration:
generic
with package Bounded is
new Ada.Strings.Bounded.Generic_Bounded_Length (<>);
function Ada.Strings.Bounded.Equal_Case_Insensitive
(Left, Right : Bounded.Bounded_String) return Boolean
with Preelaborate, Nonblocking, Global => in out synchronized ;
Equivalent to Strings.Equal_Case_Insensitive (Bounded.To_String (Left), Bounded.To_String (Right));
The library function Strings.Unbounded.Equal_Case_Insensitive has the following declaration:
function Ada.Strings.Unbounded.Equal_Case_Insensitive
(Left, Right : Unbounded_String) return Boolean
with Preelaborate, Nonblocking, Global => in out synchronized ;
Equivalent to Strings.Equal_Case_Insensitive (To_String (Left), To_String (Right));
The library function Strings.Less_Case_Insensitive has the following declaration:
function Ada.Strings.Less_Case_Insensitive (Left, Right : String)
return Boolean with Pure ;
Performs a lexicographic comparison of strings Left and Right, converted to lower case.
The library function Strings.Fixed.Less_Case_Insensitive has the following declaration:
with Ada.Strings.Less_Case_Insensitive;
function Ada.Strings.Fixed.Less_Case_Insensitive
(Left, Right : String) return Boolean
renames Ada.Strings.Less_Case_Insensitive;
The generic library function Strings.Bounded.Less_Case_Insensitive has the following declaration:
generic
with package Bounded is
new Ada.Strings.Bounded.Generic_Bounded_Length (<>);
function Ada.Strings.Bounded.Less_Case_Insensitive
(Left, Right : Bounded.Bounded_String) return Boolean
with Preelaborate, Nonblocking, Global => in out synchronized ;
Equivalent to Strings.Less_Case_Insensitive (Bounded.To_String (Left), Bounded.To_String (Right));
The library function Strings.Unbounded.Less_Case_Insensitive has the following declaration:
function Ada.Strings.Unbounded.Less_Case_Insensitive
(Left, Right : Unbounded_String) return Boolean
with Preelaborate, Nonblocking, Global => in out synchronized ;
Equivalent to Strings.Less_Case_Insensitive (To_String (Left), To_String (Right));
Extensions to Ada 2005
A.4.11 String Encoding
1/3Facilities for encoding, decoding, and converting strings in various character encoding schemes are provided by packages Strings.UTF_Encoding, Strings.UTF_Encoding.Conversions, Strings.UTF_Encoding.Strings, Strings.UTF_Encoding.Wide_Strings, and Strings.UTF_Encoding.Wide_Wide_Strings.
Static Semantics
2/3The encoding library packages have the following declarations:
package Ada.Strings.UTF_Encoding
with Pure is
4/3-- Declarations common to the string encoding packages
type Encoding_Scheme is (UTF_8, UTF_16BE, UTF_16LE);
5/3subtype UTF_String is String;
6/3subtype UTF_8_String is String;
7/3subtype UTF_16_Wide_String is Wide_String;
8/3Encoding_Error : exception;
9/3BOM_8 : constant UTF_8_String :=
Character'Val(16#EF#) &
Character'Val(16#BB#) &
Character'Val(16#BF#);
10/3BOM_16BE : constant UTF_String :=
Character'Val(16#FE#) &
Character'Val(16#FF#);
11/3BOM_16LE : constant UTF_String :=
Character'Val(16#FF#) &
Character'Val(16#FE#);
12/3BOM_16 : constant UTF_16_Wide_String :=
(1 => Wide_Character'Val(16#FEFF#));
13/3function Encoding (Item : UTF_String;
Default : Encoding_Scheme := UTF_8)
return Encoding_Scheme;
14/3end Ada.Strings.UTF_Encoding;
15/5package Ada.Strings.UTF_Encoding.Conversions
with Pure is
16/3-- Conversions between various encoding schemes
function Convert (Item : UTF_String;
Input_Scheme : Encoding_Scheme;
Output_Scheme : Encoding_Scheme;
Output_BOM : Boolean := False) return UTF_String;
17/3function Convert (Item : UTF_String;
Input_Scheme : Encoding_Scheme;
Output_BOM : Boolean := False)
return UTF_16_Wide_String;
18/3function Convert (Item : UTF_8_String;
Output_BOM : Boolean := False)
return UTF_16_Wide_String;
19/3function Convert (Item : UTF_16_Wide_String;
Output_Scheme : Encoding_Scheme;
Output_BOM : Boolean := False) return UTF_String;
20/3function Convert (Item : UTF_16_Wide_String;
Output_BOM : Boolean := False) return UTF_8_String;
21/3end Ada.Strings.UTF_Encoding.Conversions;
22/5package Ada.Strings.UTF_Encoding.Strings
with Pure is
23/3-- Encoding / decoding between String and various encoding schemes
function Encode (Item : String;
Output_Scheme : Encoding_Scheme;
Output_BOM : Boolean := False) return UTF_String;
24/3function Encode (Item : String;
Output_BOM : Boolean := False) return UTF_8_String;
25/3function Encode (Item : String;
Output_BOM : Boolean := False)
return UTF_16_Wide_String;
26/3function Decode (Item : UTF_String;
Input_Scheme : Encoding_Scheme) return String;
27/3function Decode (Item : UTF_8_String) return String;
28/3function Decode (Item : UTF_16_Wide_String) return String;
29/3end Ada.Strings.UTF_Encoding.Strings;
30/5package Ada.Strings.UTF_Encoding.Wide_Strings
with Pure is
31/3-- Encoding / decoding between Wide_String and various encoding schemes
function Encode (Item : Wide_String;
Output_Scheme : Encoding_Scheme;
Output_BOM : Boolean := False) return UTF_String;
32/3function Encode (Item : Wide_String;
Output_BOM : Boolean := False) return UTF_8_String;
33/3function Encode (Item : Wide_String;
Output_BOM : Boolean := False)
return UTF_16_Wide_String;
34/3function Decode (Item : UTF_String;
Input_Scheme : Encoding_Scheme) return Wide_String;
35/3function Decode (Item : UTF_8_String) return Wide_String;
36/3function Decode (Item : UTF_16_Wide_String) return Wide_String;
37/3end Ada.Strings.UTF_Encoding.Wide_Strings;
38/5package Ada.Strings.UTF_Encoding.Wide_Wide_Strings
with Pure is
39/3-- Encoding / decoding between Wide_Wide_String and various encoding schemes
function Encode (Item : Wide_Wide_String;
Output_Scheme : Encoding_Scheme;
Output_BOM : Boolean := False) return UTF_String;
40/3function Encode (Item : Wide_Wide_String;
Output_BOM : Boolean := False) return UTF_8_String;
41/3function Encode (Item : Wide_Wide_String;
Output_BOM : Boolean := False)
return UTF_16_Wide_String;
42/3function Decode (Item : UTF_String;
Input_Scheme : Encoding_Scheme) return Wide_Wide_String;
43/3function Decode (Item : UTF_8_String) return Wide_Wide_String;
44/3function Decode (Item : UTF_16_Wide_String) return Wide_Wide_String;
45/3end Ada.Strings.UTF_Encoding.Wide_Wide_Strings;
The type Encoding_Scheme defines encoding schemes. UTF_8 corresponds to the UTF-8 encoding scheme defined by Annex D of ISO/IEC 10646. UTF_16BE corresponds to the UTF-16 encoding scheme defined by Annex C of ISO/IEC 10646 in 8 bit, big-endian order; and UTF_16LE corresponds to the UTF-16 encoding scheme in 8 bit, little-endian order.
The subtype UTF_String is used to represent a String of 8-bit values containing a sequence of values encoded in one of three ways (UTF-8, UTF-16BE, or UTF-16LE). The subtype UTF_8_String is used to represent a String of 8-bit values containing a sequence of values encoded in UTF-8. The subtype UTF_16_Wide_String is used to represent a Wide_String of 16-bit values containing a sequence of values encoded in UTF-16.
The BOM_8, BOM_16BE, BOM_16LE, and BOM_16 constants correspond to values used at the start of a string to indicate the encoding.
Each of the Encode functions takes a String, Wide_String, or Wide_Wide_String Item parameter that is assumed to be an array of unencoded characters. Each of the Convert functions takes a UTF_String, UTF_8_String, or UTF_16_String Item parameter that is assumed to contain characters whose position values correspond to a valid encoding sequence according to the encoding scheme required by the function or specified by its Input_Scheme parameter.
Each of the Convert and Encode functions returns a UTF_String, UTF_8_String, or UTF_16_String value whose characters have position values that correspond to the encoding of the Item parameter according to the encoding scheme required by the function or specified by its Output_Scheme parameter. For UTF_8, no overlong encoding is returned. A BOM is included at the start of the returned string if the Output_BOM parameter is set to True. The lower bound of the returned string is 1.
Each of the Decode functions takes a UTF_String, UTF_8_String, or UTF_16_String Item parameter which is assumed to contain characters whose position values correspond to a valid encoding sequence according to the encoding scheme required by the function or specified by its Input_Scheme parameter, and returns the corresponding String, Wide_String, or Wide_Wide_String value. The lower bound of the returned string is 1.
For each of the Convert and Decode functions, an initial BOM in the input that matches the expected encoding scheme is ignored, and a different initial BOM causes Encoding_Error to be propagated.
The exception Encoding_Error is also propagated in the following situations:
- By a Convert or Decode function when a UTF encoded string contains an invalid encoding sequence.
- By a Convert or Decode function when the expected encoding is UTF-16BE or UTF-16LE and the input string has an odd length.
- By a Decode function yielding a String when the decoding of a sequence results in a code point whose value exceeds 16#FF#.
- By a Decode function yielding a Wide_String when the decoding of a sequence results in a code point whose value exceeds 16#FFFF#.
- By an Encode function taking a Wide_String as input when an invalid character appears in the input. In particular, the characters whose position is in the range 16#D800# .. 16#DFFF# are invalid because they conflict with UTF-16 surrogate encodings, and the characters whose position is 16#FFFE# or 16#FFFF# are also invalid because they conflict with BOM codes.
function Encoding (Item : UTF_String;
Default : Encoding_Scheme := UTF_8)
return Encoding_Scheme;
Inspects a UTF_String value to determine whether it starts with a BOM for UTF-8, UTF-16BE, or UTF_16LE. If so, returns the scheme corresponding to the BOM; otherwise, returns the value of Default.
function Convert (Item : UTF_String;
Input_Scheme : Encoding_Scheme;
Output_Scheme : Encoding_Scheme;
Output_BOM : Boolean := False) return UTF_String;
Returns the value of Item (originally encoded in UTF-8, UTF-16LE, or UTF-16BE as specified by Input_Scheme) encoded in one of these three schemes as specified by Output_Scheme.
function Convert (Item : UTF_String;
Input_Scheme : Encoding_Scheme;
Output_BOM : Boolean := False)
return UTF_16_Wide_String;
Returns the value of Item (originally encoded in UTF-8, UTF-16LE, or UTF-16BE as specified by Input_Scheme) encoded in UTF-16.
function Convert (Item : UTF_8_String;
Output_BOM : Boolean := False)
return UTF_16_Wide_String;
Returns the value of Item (originally encoded in UTF-8) encoded in UTF-16.
function Convert (Item : UTF_16_Wide_String;
Output_Scheme : Encoding_Scheme;
Output_BOM : Boolean := False) return UTF_String;
Returns the value of Item (originally encoded in UTF-16) encoded in UTF-8, UTF-16LE, or UTF-16BE as specified by Output_Scheme.
function Convert (Item : UTF_16_Wide_String;
Output_BOM : Boolean := False) return UTF_8_String;
Returns the value of Item (originally encoded in UTF-16) encoded in UTF-8.
function Encode (Item : String;
Output_Scheme : Encoding_Scheme;
Output_BOM : Boolean := False) return UTF_String;
Returns the value of Item encoded in UTF-8, UTF-16LE, or UTF-16BE as specified by Output_Scheme.
function Encode (Item : String;
Output_BOM : Boolean := False) return UTF_8_String;
Returns the value of Item encoded in UTF-8.
function Encode (Item : String;
Output_BOM : Boolean := False) return UTF_16_Wide_String;
Returns the value of Item encoded in UTF_16.
function Decode (Item : UTF_String;
Input_Scheme : Encoding_Scheme) return String;
Returns the result of decoding Item, which is encoded in UTF-8, UTF-16LE, or UTF-16BE as specified by Input_Scheme.
function Decode (Item : UTF_8_String) return String;
Returns the result of decoding Item, which is encoded in UTF-8.
function Decode (Item : UTF_16_Wide_String) return String;
Returns the result of decoding Item, which is encoded in UTF-16.
function Encode (Item : Wide_String;
Output_Scheme : Encoding_Scheme;
Output_BOM : Boolean := False) return UTF_String;
Returns the value of Item encoded in UTF-8, UTF-16LE, or UTF-16BE as specified by Output_Scheme.
function Encode (Item : Wide_String;
Output_BOM : Boolean := False) return UTF_8_String;
Returns the value of Item encoded in UTF-8.
function Encode (Item : Wide_String;
Output_BOM : Boolean := False) return UTF_16_Wide_String;
Returns the value of Item encoded in UTF_16.
function Decode (Item : UTF_String;
Input_Scheme : Encoding_Scheme) return Wide_String;
Returns the result of decoding Item, which is encoded in UTF-8, UTF-16LE, or UTF-16BE as specified by Input_Scheme.
function Decode (Item : UTF_8_String) return Wide_String;
Returns the result of decoding Item, which is encoded in UTF-8.
function Decode (Item : UTF_16_Wide_String) return Wide_String;
Returns the result of decoding Item, which is encoded in UTF-16.
function Encode (Item : Wide_Wide_String;
Output_Scheme : Encoding_Scheme;
Output_BOM : Boolean := False) return UTF_String;
Returns the value of Item encoded in UTF-8, UTF-16LE, or UTF-16BE as specified by Output_Scheme.
function Encode (Item : Wide_Wide_String;
Output_BOM : Boolean := False) return UTF_8_String;
Returns the value of Item encoded in UTF-8.
function Encode (Item : Wide_Wide_String;
Output_BOM : Boolean := False) return UTF_16_Wide_String;
Returns the value of Item encoded in UTF_16.
function Decode (Item : UTF_String;
Input_Scheme : Encoding_Scheme) return Wide_Wide_String;
Returns the result of decoding Item, which is encoded in UTF-8, UTF-16LE, or UTF-16BE as specified by Input_Scheme.
function Decode (Item : UTF_8_String) return Wide_Wide_String;
Returns the result of decoding Item, which is encoded in UTF-8.
function Decode (Item : UTF_16_Wide_String) return Wide_Wide_String;
Returns the result of decoding Item, which is encoded in UTF-16.
Implementation Advice
107/3If an implementation supports other encoding schemes, another similar child of Ada.Strings should be defined.
Extensions to Ada 2005
Wording Changes from Ada 2012
A.4.12 Universal Text Buffers
1/5A universal text buffer can be used to save and retrieve text of any language-defined string type. The types used to save and retrieve the text can be different.
Static Semantics
2/5The text buffer library packages have the following declarations:
with Ada.Strings.UTF_Encoding.Wide_Wide_Strings;
package Ada.Strings.Text_Buffers
with Pure is
4/5type Text_Buffer_Count is range 0 .. implementation-defined;
5/5New_Line_Count : constant Text_Buffer_Count := implementation-defined;
6/5type Root_Buffer_Type is abstract tagged private
with Default_Initial_Condition =>
Current_Indent (Root_Buffer_Type) = 0;
7/5procedure Put (
Buffer : in out Root_Buffer_Type;
Item : in String) is abstract;
8/5procedure Wide_Put (
Buffer : in out Root_Buffer_Type;
Item : in Wide_String) is abstract;
9/5procedure Wide_Wide_Put (
Buffer : in out Root_Buffer_Type;
Item : in Wide_Wide_String) is abstract;
10/5procedure Put_UTF_8 (
Buffer : in out Root_Buffer_Type;
Item : in UTF_Encoding.UTF_8_String) is abstract;
11/5procedure Wide_Put_UTF_16 (
Buffer : in out Root_Buffer_Type;
Item : in UTF_Encoding.UTF_16_Wide_String) is abstract;
12/5procedure New_Line (Buffer : in out Root_Buffer_Type) is abstract;
13/5Standard_Indent : constant Text_Buffer_Count := 3;
14/5function Current_Indent (
Buffer : Root_Buffer_Type) return Text_Buffer_Count;
15/5procedure Increase_Indent (
Buffer : in out Root_Buffer_Type;
Amount : in Text_Buffer_Count := Standard_Indent)
with Post'Class =>
Current_Indent (Buffer) = Current_Indent (Buffer)'Old + Amount;
16/5procedure Decrease_Indent (
Buffer : in out Root_Buffer_Type;
Amount : in Text_Buffer_Count := Standard_Indent)
with Pre'Class =>
Current_Indent (Buffer) >= Amount
or else raise Constraint_Error,
Post'Class =>
Current_Indent (Buffer) =
Current_Indent (Buffer)'Old - Amount;
17/5private
... -- not specified by the language
end Ada.Strings.Text_Buffers;
18/5package Ada.Strings.Text_Buffers.Unbounded
with Preelaborate, Nonblocking, Global => null is
19/5type Buffer_Type is new Root_Buffer_Type with private;
20/5function Get (
Buffer : in out Buffer_Type)
return String
with Post'Class =>
Get'Result'First = 1 and then Current_Indent (Buffer) = 0;
21/5function Wide_Get (
Buffer : in out Buffer_Type)
return Wide_String
with Post'Class =>
Wide_Get'Result'First = 1 and then Current_Indent (Buffer) = 0;
22/5function Wide_Wide_Get (
Buffer : in out Buffer_Type)
return Wide_Wide_String
with Post'Class =>
Wide_Wide_Get'Result'First = 1
and then Current_Indent (Buffer) = 0;
23/5function Get_UTF_8 (
Buffer : in out Buffer_Type)
return UTF_Encoding.UTF_8_String
with Post'Class =>
Get_UTF_8'Result'First = 1 and then Current_Indent (Buffer) = 0;
24/5function Wide_Get_UTF_16 (
Buffer : in out Buffer_Type)
return UTF_Encoding.UTF_16_Wide_String
with Post'Class =>
Wide_Get_UTF_16'Result'First = 1
and then Current_Indent (Buffer) = 0;
25/5private
... -- not specified by the language, but will include nonabstract
-- overridings of all inherited subprograms that require overriding.
end Ada.Strings.Text_Buffers.Unbounded;
26/5package Ada.Strings.Text_Buffers.Bounded
with Pure, Nonblocking, Global => null is
27/5type Buffer_Type (Max_Characters : Text_Buffer_Count)
is new Root_Buffer_Type with private
with Default_Initial_Condition => not Text_Truncated (Buffer_Type);
28/5function Text_Truncated (Buffer : in Buffer_Type) return Boolean;
29/5-- Get, Wide_Get, Wide_Wide_Get, Get_UTF_8, and Wide_Get_UTF_16
-- are declared here just as in the Unbounded child.
30/5private
... -- not specified by the language, but will include nonabstract
-- overridings of all inherited subprograms that require overriding.
end Ada.Strings.Text_Buffers.Bounded;
Character_Count returns the number of characters currently stored in a text buffer.
New_Line stores New_Line_Count characters that represent a new line into a text buffer. Current_Indent returns the current indentation associated with the buffer, with zero meaning there is no indentation in effect; Increase_Indent and Decrease_Indent increase or decrease the indentation associated with the buffer.
A call to Put, Wide_Put, Wide_Wide_Put, Put_UTF_8, or Wide_Put_UTF_16 stores a sequence of characters into the text buffer, preceded by Current_Indent(Buffer) spaces (Wide_Wide_Characters with position 32) if there is at least one character in Item and it would have been the first character on the current line.
A call to function Get, Wide_Get, Wide_Wide_Get, Get_UTF_8, or Wide_Get_UTF_16 returns the same sequence of characters as was present in the calls that stored the characters into the buffer, if representable. For a call to Get, if any character in the sequence is not defined in Character, the result is implementation defined. Similarly, for a call to Wide_Get, if any character in the sequence is not defined in Wide_Character, the result is implementation defined. As part of a call on any of the Get functions, the buffer is reset to an empty state, with no stored characters.
In the case of a Buf of type Text_Buffers.Bounded.Buffer_Type, Text_Truncated (Buf) returns True if the various Put procedures together have attempted to store more than Buf.Max_Characters into Buf. If this function returns True, then the various Get functions return a representation of only the first Buf.Max_Characters characters that were stored in Buf.
Implementation Advice
36/5Bounded buffer objects should be implemented without dynamic allocation.