The Package Strings.Maps

Annotated Ada Reference Manual (Ada 202y Draft 1) — Legal Information

A.4.2 The Package Strings.Maps

{AI12-0445-1} The package Strings.Maps defines the types, operations, and other entities necessary for character sets and character-to-character mappings.

Static Semantics

{AI95-00362-01} {AI12-0414-1} package Ada.Strings.Maps
with Pure is

{AI95-00161-01} {AI12-0399-1}    -- Representation for a set of character values:
   type Character_Set is private
      with Preelaborable_Initialization;

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;

{AI95-00161-01} {AI12-0399-1}    -- Representation for a character to character mapping:
   type Character_Mapping is private
      with Preelaborable_Initialization;

   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;

{AI05-0264-1} 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;

{AI05-0264-1} 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.

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.

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.

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.

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;

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

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.

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

Reason: Package Strings.Maps is not pure, since it declares an access-to-subprogram type.

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.

Extensions to Ada 95

{AI95-00161-01} 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.

Wording Changes from Ada 95

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