Annotated Ada Reference Manual — Legal Information

A.4.7 Wide_String Handling

1/2

{AI95-00302-03} Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants, and in the functions Strings.Wide_Hash, Strings.Wide_Fixed.Wide_Hash, Strings.Wide_Bounded.Wide_Hash, and Strings.Wide_Unbounded.Wide_Hash. They provide the same string-handling operations as the corresponding packages and functions for strings of Character elements.

Static Semantics

The package Strings.Wide_Maps has the following declaration.

package Ada.Strings.Wide_Maps is
pragma Preelaborate(Wide_Maps);

4/2

{AI95-00161-01}    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;
   pragma Preelaborable_Initialization(Wide_Character_Set);

Null_Set : constant Wide_Character_Set;

   type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

type Wide_Character_Ranges is array (Positive range <>)
of Wide_Character_Range;

function To_Set (Ranges : in Wide_Character_Ranges)
return Wide_Character_Set;

function To_Set (Span : in Wide_Character_Range)
return Wide_Character_Set;

function To_Ranges (Set : in Wide_Character_Set)
return Wide_Character_Ranges;

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

   function "not" (Right : in Wide_Character_Set)
      return Wide_Character_Set;
   function "and" (Left, Right : in Wide_Character_Set)
      return Wide_Character_Set;
   function "or"  (Left, Right : in Wide_Character_Set)
      return Wide_Character_Set;
   function "xor" (Left, Right : in Wide_Character_Set)
      return Wide_Character_Set;
   function "-"   (Left, Right : in Wide_Character_Set)
      return Wide_Character_Set;

   function Is_In (Element : in Wide_Character;
                   Set     : in Wide_Character_Set)
      return Boolean;

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

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

-- Alternative representation for a set of Wide_Character values:
subtype Wide_Character_Sequence is Wide_String;

function To_Set (Sequence : in Wide_Character_Sequence)
return Wide_Character_Set;

function To_Set (Singleton : in Wide_Character)
return Wide_Character_Set;

function To_Sequence (Set : in Wide_Character_Set)
return Wide_Character_Sequence;

20/2

{AI95-00161-01}    -- Representation for a Wide_Character to Wide_Character mapping:
   type Wide_Character_Mapping is private;
   pragma Preelaborable_Initialization(Wide_Character_Mapping);

   function Value (Map     : in Wide_Character_Mapping;
                   Element : in Wide_Character)
      return Wide_Character;

Identity : constant Wide_Character_Mapping;

function To_Mapping (From, To : in Wide_Character_Sequence)
return Wide_Character_Mapping;

function To_Domain (Map : in Wide_Character_Mapping)
return Wide_Character_Sequence;

function To_Range (Map : in Wide_Character_Mapping)
return Wide_Character_Sequence;

type Wide_Character_Mapping_Function is
access function (From : in Wide_Character) return Wide_Character;

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

The context clause for each of the packages Strings.Wide_Fixed, Strings.Wide_Bounded, and Strings.Wide_Unbounded identifies Strings.Wide_Maps instead of Strings.Maps.

28.1/3

{AI05-0223-1} Types Wide_Character_Set and Wide_Character_Mapping need finalization.

29/2

{AI95-00302-03} For each of the packages Strings.Fixed, Strings.Bounded, Strings.Unbounded, and Strings.Maps.Constants, and for functions Strings.Hash, Strings.Fixed.Hash, Strings.Bounded.Hash, and Strings.Unbounded.Hash, the corresponding wide string package has the same contents except that

Wide_Space replaces Space

Wide_Character replaces Character

Wide_String replaces String

Wide_Character_Set replaces Character_Set

Wide_Character_Mapping replaces Character_Mapping

Wide_Character_Mapping_Function replaces Character_Mapping_Function

Wide_Maps replaces Maps

Bounded_Wide_String replaces Bounded_String

Null_Bounded_Wide_String replaces Null_Bounded_String

To_Bounded_Wide_String replaces To_Bounded_String

To_Wide_String replaces To_String

40.1/2

{AI95-00301-01} Set_Bounded_Wide_String replaces Set_Bounded_String

Unbounded_Wide_String replaces Unbounded_String

Null_Unbounded_Wide_String replaces Null_Unbounded_String

Wide_String_Access replaces String_Access

To_Unbounded_Wide_String replaces To_Unbounded_String

44.1/2

{AI95-00301-01} Set_Unbounded_Wide_String replaces Set_Unbounded_String

The following additional declaration is present in Strings.Wide_Maps.Wide_Constants:

46/2

{AI95-00285-01} {AI95-00395-01} Character_Set : constant Wide_Maps.Wide_Character_Set;
--Contains each Wide_Character value WC such that
-- Characters.Conversions. Is_Character(WC) is True

46.1/2

{AI95-00395-01} Each Wide_Character_Set constant in the package Strings.Wide_Maps.Wide_Constants contains no values outside the Character portion of Wide_Character. Similarly, each Wide_Character_Mapping constant in this package is the identity mapping when applied to any element outside the Character portion of Wide_Character.

46.2/2

{AI95-00362-01} Pragma Pure is replaced by pragma Preelaborate in Strings.Wide_Maps.Wide_Constants.

NOTES

14 If a null Wide_Character_Mapping_Function is passed to any of the Wide_String handling subprograms, Constraint_Error is propagated.

48/2

15 {AI95-00395-01} Each Wide_Character_Set constant in the package Strings.Wide_Maps.Wide_Constants contains no values outside the Character portion of Wide_Character. Similarly, each Wide_Character_Mapping constant in this package is the identity mapping when applied to any element outside the Character portion of Wide_Character.

Incompatibilities With Ada 95

48.a/2

{AI95-00301-01} Various new operations are added to Strings.Wide_Fixed, Strings.Wide_Bounded, and Strings.Wide_Unbounded. If one of these packages is referenced in a use_clause, and an entity E with the same defining_identifier as a new entity is defined in a package that is also referenced in a use_clause, the entity E may no longer be use-visible, resulting in errors. This should be rare and is easily fixed if it does occur.

Extensions to Ada 95

48.b/2

{AI95-00161-01} Amendment Correction: Added pragma Preelaborable_Initialization to types Wide_Character_Set and Wide_Character_Mapping, so that they can be used to declare default-initialized objects in preelaborated units.

Wording Changes from Ada 95

48.c/2

{AI95-00285-01} Corrected the description of Character_Set.

48.d/2

{AI95-00302-03} Added wide versions of Strings.Hash and Strings.Unbounded.Hash.

48.e/2

{AI95-00362-01} Added wording so that Strings.Wide_Maps.Wide_Constants does not change to Pure.

48.f/2

{AI95-00395-01} The second Note is now normative text, since there is no way to derive it from the other rules. It's a little weird given the use of Unicode character classifications in Ada 2005; but changing it would be inconsistent with Ada 95 and a one-to-one mapping isn't necessarily correct anyway.

Wording Changes from Ada 2005

48.g/3

{AI05-0223-1} Correction: Identified Wide_Character_Set and Wide_Character_Mapping as needing finalization. It is likely that they are implemented with a controlled type, so this change is unlikely to make any difference in practice.

Ada 2005 and 2012 Editions sponsored in part by Ada-Europe