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

     package Ada.Strings.Maps is
        pragma Pure(Maps);

4/2

        −− 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

        −− 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)).

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.

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
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.

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

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.      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.
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.