| | | |
TOC -- / --.-- / --.--.-- | Index | Search | Syntax | Help

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)
       package Ada.Strings.Maps is
          pragma Preelaborate(Maps);
(4)
          -- Representation for a set of character values:
          type Character_Set is private;
(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)
          -- Representation for a character to character mapping:
          type Character_Mapping is private;
(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)

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

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

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.

| | | |
TOC -- / --.-- / --.--.-- | Index | Search | Syntax | Help

-- Email comments, additions, corrections, gripes, kudos, etc. to: