Appendix G: Specification of the Ada String Libraries Used in this Book

This appendix, adapted from the Ada 95 Reference Manual, Section A.3, gives the specifications for the packages Ada.Characters.Handling, Ada.Strings, Ada.Strings.Maps, and Ada.Strings.Fixed. Not shown are Ada.Strings.Bounded and Ada.Strings.Unbounded, which have functionality similar to Ada.Strings.Fixed.
PACKAGE Ada.Characters.Handling IS
  PRAGMA Preelaborate( Handling);

    --Character classification  FUNCTIONs

  FUNCTION Is_Control           ( Item : IN Character) RETURN Boolean;
  FUNCTION Is_Graphic           ( Item : IN Character) RETURN Boolean;
  FUNCTION Is_Letter            ( Item : IN Character) RETURN Boolean;
  FUNCTION Is_Lower             ( Item : IN Character) RETURN Boolean;
  FUNCTION Is_Upper             ( Item : IN Character) RETURN Boolean;
  FUNCTION Is_Basic             ( Item : IN Character) RETURN Boolean;
  FUNCTION Is_Digit             ( Item : IN Character) RETURN Boolean;
  FUNCTION Is_Decimal_Digit     ( Item : IN Character) RETURN Boolean 
    RENAMES Is_Digit;
  FUNCTION Is_Hexadecimal_Digit ( Item : IN Character) RETURN Boolean;
  FUNCTION Is_Alphanumeric      ( Item : IN Character) RETURN Boolean;
  FUNCTION Is_Special           ( Item : IN Character) RETURN Boolean;

    --Conversion functions for Character and String

  FUNCTION To_Lower ( Item : IN Character) RETURN Character;
  FUNCTION To_Upper ( Item : IN Character) RETURN Character;
  FUNCTION To_Basic ( Item : IN Character) RETURN Character;

  FUNCTION To_Lower ( Item : IN String) RETURN String;
  FUNCTION To_Upper ( Item : IN String) RETURN String;
  FUNCTION To_Basic ( Item : IN String) RETURN String;

    --Classifications of and conversions between 
    --Character and ISO_646

  SUBTYPE ISO_646 IS
    Character RANGE Character'Val( 0) .. Character'Val( 127);

  FUNCTION Is_ISO_646 ( Item : IN Character) RETURN Boolean;
  FUNCTION Is_ISO_646 ( Item : IN String)    RETURN Boolean;

  FUNCTION To_ISO_646 ( Item       : IN Character;
                        Substitute : IN ISO_646 := ' ')
   RETURN ISO_646;

  FUNCTION To_ISO_646 ( Item       : IN String;
                       Substitute : IN ISO_646 := ' ')
   RETURN String;

    -- Classifications of and conversions between 
    -- Wide_Character and Character.

  FUNCTION Is_Character ( Item : IN Wide_Character) RETURN Boolean;
  FUNCTION Is_String    ( Item : IN Wide_String)    RETURN Boolean;

  FUNCTION To_Character ( Item       : IN Wide_Character;
                          Substitute : IN Character := ' ')
   RETURN Character;

  FUNCTION To_String    ( Item       : IN Wide_String;
                          Substitute : IN Character := ' ')
   RETURN String;

  FUNCTION To_Wide_Character ( Item : IN Character) 
    RETURN Wide_Character;

  FUNCTION To_Wide_String    ( Item : IN String)  RETURN Wide_String;

END Ada.Characters.Handling;


PACKAGE Ada.Strings IS
  PRAGMA Pure( Strings);

  Space      : constant Character      := ' ';
  Wide_Space : constant Wide_Character := ' ';

  Length_Error, Pattern_Error, Index_Error, Translation_Error : 
    EXCEPTION;

  TYPE Alignment  IS ( Left, Right, Center);
  TYPE Truncation IS ( Left, Right, Error);
  TYPE Membership IS ( Inside, Outside);
  TYPE Direction  IS ( Forward, Backward);
  TYPE Trim_End   IS ( Left, Right, Both);

END Ada.Strings;


PACKAGE Ada.Strings.Maps IS
  PRAGMA Preelaborate( Maps);

  -- Representation for a set of character values:
  TYPE Character_Set IS private;

  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;

  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;

WITH Ada.Strings.Maps;
PACKAGE Ada.Strings.Fixed IS
  PRAGMA Preelaborate( Fixed);

-- "Copy" PROCEDURE for strings of possibly different lengths

  PROCEDURE Move ( Source  : IN  String;
                   Target  : OUT String;
                   Drop    : IN  Truncation := Error;
                   Justify : IN  Alignment  := Left;
                   Pad     : IN  Character  := Space);

-- Search subprograms

  FUNCTION Index ( Source   : IN String;
                   Pattern  : IN String;
                   Going    : IN Direction := Forward;
                   Mapping  : IN Maps.Character_Mapping
                               := Maps.Identity)
    RETURN Natural;

  FUNCTION Index ( Source   : IN String;
                   Pattern  : IN String;
                   Going    : IN Direction := Forward;
                   Mapping  : IN Maps.Character_Mapping_Function)
    RETURN Natural;

  FUNCTION Index ( Source : IN String;
                   Set    : IN Maps.Character_Set;
                   Test   : IN Membership := Inside;
                   Going  : IN Direction  := Forward)
    RETURN Natural;

  FUNCTION Index_Non_Blank ( Source : IN String;
                             Going  : IN Direction := Forward)
    RETURN Natural;

   FUNCTION Count ( Source   : IN String;
                    Pattern  : IN String;
                    Mapping  : IN Maps.Character_Mapping
                                := Maps.Identity)
    RETURN Natural;

  FUNCTION Count ( Source   : IN String;
                   Pattern  : IN String;
                   Mapping  : IN Maps.Character_Mapping_Function)
    RETURN Natural;

  FUNCTION Count ( Source   : IN String;
                   Set      : IN Maps.Character_Set)
    RETURN Natural;

  PROCEDURE Find_Token ( Source : IN String;
                         Set    : IN Maps.Character_Set;
                         Test   : IN Membership;
                         First  : OUT Positive;
                         Last   : OUT Natural);

    -- String translation subprograms

  FUNCTION Translate ( Source  : IN String;
                       Mapping : IN Maps.Character_Mapping)
    RETURN String;

  PROCEDURE Translate ( Source  : IN out String;
                        Mapping : IN Maps.Character_Mapping);

  FUNCTION Translate ( Source  : IN String;
                       Mapping : IN Maps.Character_Mapping_Function)
    RETURN String;

  PROCEDURE Translate ( Source  : IN out String;
                        Mapping : IN Maps.Character_Mapping_Function);

    -- String transformation subprograms

  FUNCTION Replace_Slice ( Source   : IN String;
                           Low      : IN Positive;
                           High     : IN Natural;
                           By       : IN String)
    RETURN String;

  PROCEDURE Replace_Slice ( Source   : IN out String;
                            Low      : IN Positive;
                            High     : IN Natural;
                            By       : IN String;
                            Drop     : IN Truncation := Error;
                            Justify  : IN Alignment  := Left;
                            Pad      : IN Character  := Space);

  FUNCTION Insert ( Source   : IN String;
                    Before   : IN Positive;
                    New_Item : IN String)
    RETURN String;

  PROCEDURE Insert ( Source   : IN out String;
                     Before   : IN Positive;
                     New_Item : IN String;
                     Drop     : IN Truncation := Error);

  FUNCTION Overwrite ( Source   : IN String;
                       Position : IN Positive;
                       New_Item : IN String)
    RETURN String;

  PROCEDURE Overwrite ( Source   : IN out String;
                        Position : IN Positive;
                        New_Item : IN String;
                        Drop     : IN Truncation := Right);

  FUNCTION Delete ( Source  : IN String;
                    From    : IN Positive;
                    Through : IN Natural)
     RETURN String;

  PROCEDURE Delete ( Source  : IN out String;
                     From    : IN Positive;
                     Through : IN Natural;
                     Justify : IN Alignment := Left;
                     Pad     : IN Character := Space);

--String selector subprograms
  FUNCTION Trim ( Source : IN String;
                  Side   : IN Trim_End)
    RETURN String;

  PROCEDURE Trim ( Source  : IN out String;
                   Side    : IN Trim_End;
                   Justify : IN Alignment := Left;
                   Pad     : IN Character := Space);

  FUNCTION Trim ( Source : IN String;
                  Left   : IN Maps.Character_Set;
                  Right  : IN Maps.Character_Set)
    RETURN String;

  PROCEDURE Trim ( Source  : IN out String;
                   Left    : IN Maps.Character_Set;
                   Right   : IN Maps.Character_Set;
                   Justify : IN Alignment := Strings.Left;
                   Pad     : IN Character := Space);

  FUNCTION Head ( Source : IN String;
                  Count  : IN Natural;
                  Pad    : IN Character := Space)
    RETURN String;

  PROCEDURE Head ( Source  : IN out String;
                   Count   : IN Natural;
                   Justify : IN Alignment := Left;
                   Pad     : IN Character := Space);

  FUNCTION Tail ( Source : IN String;
                  Count  : IN Natural;
                  Pad    : IN Character := Space)
    RETURN String;

  PROCEDURE Tail ( Source  : IN out String;
                   Count   : IN Natural;
                   Justify : IN Alignment := Left;
                   Pad     : IN Character := Space);

    --String constructor  FUNCTIONs

  FUNCTION "*" ( Left  : IN Natural;
                 Right : IN Character) RETURN String;

  FUNCTION "*" ( Left  : IN Natural;
                 Right : IN String) RETURN String;

END Ada.Strings.Fixed;