The Package Strings.Maps

The package Strings.Maps defines the types, operations, and other entities needed for character sets and character-to-character mappings.

Static Semantics

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

   -- Representation for a set of character values:
   type Character_Set is private;
   pragma Preelaborable_Initialization(Character_Set);

Null_Set : constant Character_Set;

   type Character_Range is
     record
        Low  : Character;
        High : Character;
     end record;
   -- Represents Character range Low..High

type Character_Ranges is array (Positive range <>) of Character_Range;

function To_Set (Ranges : in Character_Ranges)return Character_Set;

function To_Set (Span : in Character_Range)return Character_Set;

function To_Ranges (Set : in Character_Set) return Character_Ranges;

function "=" (Left, Right : in Character_Set) return Boolean;

   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;

   function Is_In (Element : in Character;
                   Set     : in Character_Set)
      return Boolean;

   function Is_Subset (Elements : in Character_Set;
                       Set      : in Character_Set)
      return Boolean;

   function "<=" (Left  : in Character_Set;
                  Right : in Character_Set)
      return Boolean renames Is_Subset;

-- Alternative representation for a set of character values:
subtype Character_Sequence is String;

function To_Set (Sequence : in Character_Sequence)return Character_Set;

function To_Set (Singleton : in Character) return Character_Set;

function To_Sequence (Set : in Character_Set) return Character_Sequence;

   -- Representation for a character to character mapping:
   type Character_Mapping is private;
   pragma Preelaborable_Initialization(Character_Mapping);

   function Value (Map     : in Character_Mapping;
                   Element : in Character)
      return Character;

Identity : constant Character_Mapping;

function To_Mapping (From, To : in Character_Sequence)
return Character_Mapping;

   function To_Domain (Map : in Character_Mapping)
      return Character_Sequence;
   function To_Range  (Map : in Character_Mapping)
      return Character_Sequence;

type Character_Mapping_Function is
access function (From : in Character) return Character;

private
... -- not specified by the language
end Ada.Strings.Maps;

An object Obj of type Character_Range represents the set of characters in the range Obj.Low .. Obj.High.

An object Obj of type Character_Ranges represents the union of the sets corresponding to Obj(I) for I in Obj'Range.

function To_Set (Ranges : in Character_Ranges) return Character_Set;

If Ranges'Length=0 then Null_Set is returned; otherwise, the returned value represents the set corresponding to Ranges.

function To_Set (Span : in Character_Range) return Character_Set;

function To_Ranges (Set : in Character_Set) return Character_Ranges;

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.

function "=" (Left, Right : in Character_Set) return Boolean;

The function "=" returns True if Left and Right represent identical sets, and False otherwise.

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

function Is_In (Element : in Character;
Set : in Character_Set);
return Boolean;

function Is_Subset (Elements : in Character_Set;
Set : in Character_Set)
return Boolean;

subtype Character_Sequence is String;

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.

function To_Set (Sequence : in Character_Sequence) return Character_Set;

function To_Set (Singleton : in Character) return Character_Set;

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.

function To_Sequence (Set : in Character_Set) return Character_Sequence;

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.

type Character_Mapping is private;

function Value (Map     : in Character_Mapping;
                Element : in Character)
   return Character;

The function Value returns the Character value to which Element maps with respect to the mapping represented by Map.

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.

String handling subprograms that deal with character mappings have parameters whose type is Character_Mapping.

Identity : constant Character_Mapping;

function To_Mapping (From, To : in Character_Sequence)
return Character_Mapping;

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.

function To_Domain (Map : in Character_Mapping) return Character_Sequence;

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.

function To_Range (Map : in Character_Mapping) return Character_Sequence;

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.

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.

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

Examples

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.

A.4.2 The Package Strings.Maps

Static Semantics

Examples