Next: , Previous: A.4.1, Up: A.4


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

     {00362AI95−00362−01} package Ada.Strings.Maps is
        pragma Pure(Maps);

4/2

     {00161AI95−00161−01}    −− Representation for 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 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

     {00161AI95−00161−01}    −− Representation for 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/00488652/0048} {00151AI95−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

 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

 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

{00161AI95−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

{00362AI95−00362−01} Strings.Maps is now Pure, so it can be used in pure units.
Wording Changes from Ada 95

67.c/2

{8652/00488652/0048} {00151AI95−00151−01} Corrigendum: Corrected the definition of the range of the result of To_Range, since the Ada 95 definition makes no sense.