A.4.2 The Package Strings.Maps
1
The package Strings.Maps defines the types, operations,
and other entities needed for character sets and character-to-character
mappings.
Static Semantics
2
The library package
Strings.Maps has the following declaration:
3/2
{
AI95-00362-01}
package Ada.Strings.Maps
is
pragma Pure Preelaborate(Maps);
4/2
{
AI95-00161-01}
--
Representation for a set of character values:
type Character_Set
is private;
pragma Preelaborable_Initialization(Character_Set);5
Null_Set :
constant Character_Set;
6
type Character_Range
is
record
Low : Character;
High : Character;
end record;
--
Represents Character range Low..High
7
type Character_Ranges
is array (Positive
range <>)
of Character_Range;
8
function To_Set (Ranges :
in Character_Ranges)
return Character_Set;
9
function To_Set (Span :
in Character_Range)
return Character_Set;
10
function To_Ranges (Set :
in Character_Set)
return Character_Ranges;
11
function "=" (Left, Right : in Character_Set) return Boolean;
12
function "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;
13
function Is_In (Element :
in Character;
Set :
in Character_Set)
return Boolean;
14
function Is_Subset (Elements :
in Character_Set;
Set :
in Character_Set)
return Boolean;
15
function "<=" (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;
17
function To_Set (Sequence :
in Character_Sequence)
return Character_Set;
18
function To_Set (Singleton :
in Character)
return Character_Set;
19
function To_Sequence (Set :
in Character_Set)
return Character_Sequence;
20/2
{
AI95-00161-01}
--
Representation for a character to character mapping:
type Character_Mapping
is private;
pragma Preelaborable_Initialization(Character_Mapping);21
function Value (Map :
in Character_Mapping;
Element :
in Character)
return Character;
22
Identity :
constant Character_Mapping;
23
function To_Mapping (From, To :
in Character_Sequence)
return Character_Mapping;
24
function To_Domain (Map :
in Character_Mapping)
return Character_Sequence;
function To_Range (Map :
in Character_Mapping)
return Character_Sequence;
25
type Character_Mapping_Function
is
access function (From :
in Character)
return Character;
26
private
... -- not specified by the language
end Ada.Strings.Maps;
27
An object of type Character_Set represents a set
of characters.
28
Null_Set represents the set containing no characters.
29
An object Obj of type Character_Range represents
the set of characters in the range Obj.Low .. Obj.High.
30
An object Obj of type Character_Ranges represents
the union of the sets corresponding to Obj(I) for I in Obj'Range.
31
function To_Set (Ranges : in Character_Ranges) return Character_Set;
32
If Ranges'Length=0
then Null_Set is returned; otherwise the returned value represents the
set corresponding to Ranges.
33
function To_Set (Span : in Character_Range) return Character_Set;
34
The returned value represents the set containing
each character in Span.
35
function To_Ranges (Set : in Character_Set) return Character_Ranges;
36
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.
37
function "=" (Left, Right : in Character_Set) return Boolean;
38
The function
"=" returns True if Left and Right represent identical sets,
and False otherwise.
39
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)).
39.a
Reason: The set minus operator is provided
for efficiency.
40
function Is_In (Element : in Character;
Set : in Character_Set);
return Boolean;
41
Is_In returns
True if Element is in Set, and False otherwise.
42
function Is_Subset (Elements : in Character_Set;
Set : in Character_Set)
return Boolean;
43
Is_Subset returns
True if Elements is a subset of Set, and False otherwise.
44
subtype Character_Sequence is String;
45
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.
45.a
Reason: Although a named subtype is redundant
— the predefined type String could have been used for the parameter
to To_Set and To_Mapping below — the use of a differently named
subtype identifies the intended purpose of the parameter.
46
function To_Set (Sequence : in Character_Sequence) return Character_Set;
function To_Set (Singleton : in Character) return Character_Set;
47
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.
48
function To_Sequence (Set : in Character_Set) return Character_Sequence;
49
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.
50
type Character_Mapping is private;
51
An object of
type Character_Mapping represents a Character-to-Character mapping.
52
function Value (Map : in Character_Mapping;
Element : in Character)
return Character;
53
The function
Value returns the Character value to which Element maps with respect
to the mapping represented by Map.
54
{match (a character
to a pattern character)} A character C
matches a pattern character P with respect to a given Character_Mapping
value Map if Value(Map, C) = P.
{match
(a string to a pattern string)} 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.
54.a
Discussion: In an earlier version of
the string handling packages, the definition of matching was symmetrical,
namely C matches P if Value(Map,C) = Value(Map,P). However, applying
the mapping to the pattern was confusing according to some reviewers.
Furthermore, if the symmetrical version is needed, it can be achieved
by applying the mapping to the pattern (via translation) prior to passing
it as a parameter.
55
String handling subprograms that deal with character
mappings have parameters whose type is Character_Mapping.
56
Identity : constant Character_Mapping;
57
Identity maps
each Character to itself.
58
function To_Mapping (From, To : in Character_Sequence)
return Character_Mapping;
59
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.
60
function To_Domain (Map : in Character_Mapping) return Character_Sequence;
61
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.
62
function To_Range (Map : in Character_Mapping) return Character_Sequence;
63/1
{
8652/0048}
{
AI95-00151-01}
To_Range returns the Character_Sequence value R,
with
lower bound 1 and upper bound Map'Length, such that if D = To_Domain(Map)
,
then R has the same bounds as D, and then
D(I) maps to R(I) for each I in D'Range.
64
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.
{match
(a character to a pattern character, with respect to a character mapping
function)} 65
7 Character_Mapping and Character_Mapping_Function
are used both for character equivalence mappings in the search subprograms
(such as for case insensitivity) and as transformational mappings in
the Translate subprograms.
66
8 To_Domain(Identity) and To_Range(Identity)
each returns the null string.
66.a
Reason: Package Strings.Maps is not pure,
since it declares an access-to-subprogram type.
Examples
67
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
67.a/2
{
AI95-00161-01}
{extensions to Ada 95} Amendment
Correction: Added pragma Preelaborable_Initialization
to types Character_Set and Character_Mapping, so that they can be used
to declare default-initialized objects in preelaborated units.67.b/2
{
AI95-00362-01}
Strings.Maps is now Pure, so it can be used in
pure units. Wording Changes from Ada 95
67.c/2
{
8652/0048}
{
AI95-00151-01}
Corrigendum: Corrected the definition of
the range of the result of To_Range, since the Ada 95 definition makes
no sense.
Sponsored by Ada-Europe