Annotated Ada Reference Manual — Legal Information
Contents   Index   References   Search   Previous   Next 

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(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, 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. 
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)}
NOTES
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. 
Contents   Index   References   Search   Previous   Next 
Ada-Europe Sponsored by Ada-Europe