File: RM-A.txt

package info (click to toggle)
ada-reference-manual 20021112web-3
links: PTS
area: main
in suites: etch, etch-m68k, lenny, sarge
size: 18,652 kB
ctags: 8,921
sloc: makefile: 52; sh: 20
file content (6526 lines) | stat: -rw-r--r-- 278,174 bytes


                                   Annex A
                                 (normative)

                       Predefined Language Environment


1     This Annex contains the specifications of library units that shall be
provided by every implementation. There are three root library units: Ada,
Interfaces, and System; other library units are children of these:

2/1    
 

      Standard - A.1
       Ada - A.2
         Asynchronous_Task_Control - D.11
         Calendar - 9.6
         Characters - A.3.1
           Handling - A.3.2
           Latin_1 - A.3.3
         Command_Line - A.15
         Decimal - F.2
         Direct_IO - A.8.4
         Dynamic_Priorities - D.5
         Exceptions - 11.4.1
         Finalization - 7.6
         Float_Text_IO - A.10.9
         Float_Wide_Text_IO - A.11
         Integer_Text_IO - A.10.8
         Integer_Wide_Text_IO - A.11
         Interrupts - C.3.2
           Names - C.3.2
         IO_Exceptions - A.13
         Numerics - A.5
           Complex_Elementary_Functions - G.1.2
           Complex_Types - G.1.1
           Discrete_Random - A.5.2
           Elementary_Functions - A.5.1
           Float_Random - A.5.2
           Generic_Complex_Elementary_Functions
                 - G.1.2
           Generic_Complex_Types - G.1.1
           Generic_Elementary_Functions - A.5.1
         Real_Time - D.8
         Sequential_IO - A.8.1
         Storage_IO - A.9
         Streams - 13.13.1
           Stream_IO - A.12.1


      Standard (...continued)
       Ada (...continued)
         Strings - A.4.1
           Bounded - A.4.4
           Fixed - A.4.3
           Maps - A.4.2
             Constants - A.4.6
           Unbounded - A.4.5
           Wide_Bounded - A.4.7
           Wide_Fixed - A.4.7
           Wide_Maps - A.4.7
             Wide_Constants - A.4.7
           Wide_Unbounded - A.4.7
         Synchronous_Task_Control - D.10
         Tags - 3.9
         Task_Attributes - C.7.2
         Task_Identification - C.7.1
         Text_IO - A.10.1
           Complex_IO - G.1.3
           Editing - F.3.3
           Text_Streams - A.12.2
         Unchecked_Conversion - 13.9
         Unchecked_Deallocation - 13.11.2
         Wide_Text_IO - A.11
           Complex_IO - G.1.3
           Editing - F.3.4
           Text_Streams - A.12.3

       Interfaces - B.2
         C - B.3
           Pointers - B.3.2
           Strings - B.3.1
         COBOL - B.4
         Fortran - B.5

       System - 13.7
         Address_To_Access_Conversions - 13.7.2
         Machine_Code - 13.8
         RPC - E.5
         Storage_Elements - 13.7.1
         Storage_Pools - 13.11


                         Implementation Requirements

3     The implementation shall ensure that each language defined subprogram is
reentrant in the sense that concurrent calls on the same subprogram perform as
specified, so long as all parameters that could be passed by reference denote
nonoverlapping objects.


                         Implementation Permissions

4     The implementation may restrict the replacement of language-defined
compilation units. The implementation may restrict children of
language-defined library units (other than Standard).


A.1 The Package Standard


1     This clause outlines the specification of the package Standard
containing all predefined identifiers in the language. The corresponding
package body is not specified by the language.

2     The operators that are predefined for the types declared in the package
Standard are given in comments since they are implicitly declared. Italics are
used for pseudo-names of anonymous types (such as root_real) and for undefined
information (such as implementation-defined).


                              Static Semantics

3     The library package Standard has the following declaration:

4     package Standard is
         pragma Pure(Standard);

5        type Boolean is (False, True);

6        -- The predefined relational operators for this type are as follows:

7/1      -- function "="   (Left, Right : Boolean'Base) return Boolean;
         -- function "/="  (Left, Right : Boolean'Base) return Boolean;
         -- function "<"   (Left, Right : Boolean'Base) return Boolean;
         -- function "<="  (Left, Right : Boolean'Base) return Boolean;
         -- function ">"   (Left, Right : Boolean'Base) return Boolean;
         -- function ">="  (Left, Right : Boolean'Base) return Boolean;

8        -- The predefined logical operators and the predefined logical
         -- negation operator are as follows:

9/1      -- function "and" (Left, Right : Boolean'Base) return Boolean;
         -- function "or"  (Left, Right : Boolean'Base) return Boolean;
         -- function "xor" (Left, Right : Boolean'Base) return Boolean;

10/1     -- function "not" (Right : Boolean'Base) return Boolean;

11       -- The integer type root_integer is predefined.
         -- The corresponding universal type is universal_integer.

12       type Integer is range implementation-defined;

13       subtype Natural  is Integer range 0 .. Integer'Last;
         subtype Positive is Integer range 1 .. Integer'Last;

14       -- The predefined operators for type Integer are as follows:

15       -- function "="  (Left, Right : Integer'Base) return Boolean;
         -- function "/=" (Left, Right : Integer'Base) return Boolean;
         -- function "<"  (Left, Right : Integer'Base) return Boolean;
         -- function "<=" (Left, Right : Integer'Base) return Boolean;
         -- function ">"  (Left, Right : Integer'Base) return Boolean;
         -- function ">=" (Left, Right : Integer'Base) return Boolean;

16       -- function "+"   (Right : Integer'Base) return Integer'Base;
         -- function "-"   (Right : Integer'Base) return Integer'Base;
         -- function "abs" (Right : Integer'Base) return Integer'Base;

17       -- function "+"   (Left, Right : Integer'Base) return Integer'Base;
         -- function "-"   (Left, Right : Integer'Base) return Integer'Base;
         -- function "*"   (Left, Right : Integer'Base) return Integer'Base;
         -- function "/"   (Left, Right : Integer'Base) return Integer'Base;
         -- function "rem" (Left, Right : Integer'Base) return Integer'Base;
         -- function "mod" (Left, Right : Integer'Base) return Integer'Base;

18       -- function "**"  (Left : Integer'Base; Right : Natural)
         --                  return Integer'Base;

19       -- The specification of each operator for the type
         -- root_integer, or for any additional predefined integer
         -- type, is obtained by replacing Integer by the name of the type
         -- in the specification of the corresponding operator of the type
         -- Integer. The right operand of the exponentiation operator
         -- remains as subtype Natural.

20       -- The floating point type root_real is predefined.
         -- The corresponding universal type is universal_real.

21       type Float is digits implementation-defined;

22       -- The predefined operators for this type are as follows:

23       -- function "="   (Left, Right : Float) return Boolean;
         -- function "/="  (Left, Right : Float) return Boolean;
         -- function "<"   (Left, Right : Float) return Boolean;
         -- function "<="  (Left, Right : Float) return Boolean;
         -- function ">"   (Left, Right : Float) return Boolean;
         -- function ">="  (Left, Right : Float) return Boolean;

24       -- function "+"   (Right : Float) return Float;
         -- function "-"   (Right : Float) return Float;
         -- function "abs" (Right : Float) return Float;

25       -- function "+"   (Left, Right : Float) return Float;
         -- function "-"   (Left, Right : Float) return Float;
         -- function "*"   (Left, Right : Float) return Float;
         -- function "/"   (Left, Right : Float) return Float;

26       -- function "**"  (Left : Float; Right : Integer'Base) return Float;

27       -- The specification of each operator for the type root_real, or for
         -- any additional predefined floating point type, is obtained by
         -- replacing Float by the name of the type in the specification of the
         -- corresponding operator of the type Float.

28       -- In addition, the following operators are predefined for the root
         -- numeric types:

29       function "*" (Left : root_integer; Right : root_real)
           return root_real;

30       function "*" (Left : root_real;    Right : root_integer)
           return root_real;

31       function "/" (Left : root_real;    Right : root_integer)
           return root_real;

32       -- The type universal_fixed is predefined.
         -- The only multiplying operators defined between
         -- fixed point types are

33       function "*" (Left : universal_fixed; Right : universal_fixed)
           return universal_fixed;

34       function "/" (Left : universal_fixed; Right : universal_fixed)
           return universal_fixed;

35          -- The declaration of type Character is based on the standard ISO 8859-1 character set.
      
            -- There are no character literals corresponding to the positions for control characters.
            -- They are indicated in italics in this definition. See 3.5.2.
      
         type Character is
           (nul,      soh,     stx,     etx,       eot,     enq,    ack,     
      bel,   --0 (16#00#) .. 7 (16#07#)
            bs,       ht,      lf,      vt,        ff,      cr,     so,      
      si,    --8 (16#08#) .. 15 (16#0F#)
      
            dle,      dc1,     dc2,     dc3,       dc4,     nak,    syn,     
      etb,   --16 (16#10#) .. 23 (16#17#)
            can,      em,      sub,     esc,       fs,      gs,     rs,      
      us,    --24 (16#18#) .. 31 (16#1F#)
      
            ' ',      '!',     '"',     '#',       '$',     '%',    '&',     
      ''',   --32 (16#20#) .. 39 (16#27#)
            '(',      ')',     '*',     '+',       ',',     '-',    '.',     
      '/',   --40 (16#28#) .. 47 (16#2F#)
      
            '0',      '1',     '2',     '3',       '4',     '5',    '6',     
      '7',   --48 (16#30#) .. 55 (16#37#)
            '8',      '9',     ':',     ';',       '<',     '=',    '>',     
      '?',   --56 (16#38#) .. 63 (16#3F#)
      
            '@',      'A',     'B',     'C',       'D',     'E',    'F',     
      'G',   --64 (16#40#) .. 71 (16#47#)
            'H',      'I',     'J',     'K',       'L',     'M',    'N',     
      'O',   --72 (16#48#) .. 79 (16#4F#)
      
            'P',      'Q',     'R',     'S',       'T',     'U',    'V',     
      'W',   --80 (16#50#) .. 87 (16#57#)
            'X',      'Y',     'Z',     '[',       '\',     ']',    '^',     
      '_',   --88 (16#58#) .. 95 (16#5F#)
      
            '`',      'a',     'b',     'c',       'd',     'e',    'f',     
      'g',   --96 (16#60#) .. 103 (16#67#)
            'h',      'i',     'j',     'k',       'l',     'm',    'n',     
      'o',   --104 (16#68#) .. 111 (16#6F#)
      
            'p',      'q',     'r',     's',       't',     'u',    'v',     
      'w',   --112 (16#70#) .. 119 (16#77#)
            'x',      'y',     'z',     '{',       '|',     '}',    '~',     
      del,   --120 (16#78#) .. 127 (16#7F#)
      
            reserved_128,      reserved_129,       bph,     nbh,                     
      --128 (16#80#) .. 131 (16#83#)
            reserved_132,      nel,     ssa,       esa,                              
      --132 (16#84#) .. 135 (16#87#)
            hts,      htj,     vts,     pld,       plu,     ri,     ss2,     
      ss3,   --136 (16#88#) .. 143 (16#8F#)
      
            dcs,      pu1,     pu2,     sts,       cch,     mw,     spa,     
      epa,   --144 (16#90#) .. 151 (16#97#)
            sos,      reserved_153,     sci,       csi,                              
      --152 (16#98#) .. 155 (16#9B#)
            st,       osc,     pm,      apc,                                         
      --156 (16#9C#) .. 159 (16#9F#)
      
            ' ',      '',     '',     '',       '',     '',    '',     
      '',   --160 (16#A0#) .. 167 (16#A7#)
            '',      '',     '',     '',       '',     '',    '',     
      '',   --168 (16#A8#) .. 175 (16#AF#)
      
            '',      '',     '',     '',       '',     '',    '',     
      '',   --176 (16#B0#) .. 183 (16#B7#)
            '',      '',     '',     '',       '',     '',    '',     
      '',   --184 (16#B8#) .. 191 (16#BF#)
      
            '',      '',     '',     '',       '',     '',    '',     
      '',   --192 (16#C0#) .. 199 (16#C7#)
            '',      '',     '',     '',       '',     '',    '',     
      '',   --200 (16#C8#) .. 207 (16#CF#)
      
            '',      '',     '',     '',       '',     '',    '',     
      '',   --208 (16#D0#) .. 215 (16#D7#)
            '',      '',     '',     '',       '',     '',    '',     
      '',   --216 (16#D8#) .. 223 (16#DF#)
      
            '',      '',     '',     '',       '',     '',    '',     
      '',   --224 (16#E0#) .. 231 (16#E7#)
            '',      '',     '',     '',       '',     '',    '',     
      '',   --232 (16#E8#) .. 239 (16#EF#)
      
            '',      '',     '',     '',       '',     '',    '',     
      '',   --240 (16#F0#) .. 247 (16#F7#)
            '',      '',     '',     '',       '',     '',    '',     
      '',   --248 (16#F8#) .. 255 (16#FF#)

36       -- The predefined operators for the type Character are the same as for
         -- any enumeration type.
      
         -- The declaration of type Wide_Character is based on the standard ISO 10646 BMP character set.
         -- The first 256 positions have the same contents as type Character. See 3.5.2
      .
      
         type Wide_Character is (nul, soh ... FFFE, FFFF);
      
         package ASCII is ... end ASCII;  --Obsolescent; see J.5
      
      

37       -- Predefined string types:
      
         type String is array(Positive range <>) of Character;
         pragma Pack(String);

38       -- The predefined operators for this type are as follows:

39       --     function "="  (Left, Right: String) return Boolean;
         --     function "/=" (Left, Right: String) return Boolean;
         --     function "<"  (Left, Right: String) return Boolean;
         --     function "<=" (Left, Right: String) return Boolean;
         --     function ">"  (Left, Right: String) return Boolean;
         --     function ">=" (Left, Right: String) return Boolean;

40       --     function "&" (Left: String;    Right: String)    return String;
         --     function "&" (Left: Character; Right: String)    return String;
         --     function "&" (Left: String;    Right: Character) return String;
         --     function "&" (Left: Character; Right: Character) return String;

41       type Wide_String is array(Positive range <>) of Wide_Character;
         pragma Pack(Wide_String);

42       -- The predefined operators for this type correspond to those for String

43       type Duration
       is delta implementation-defined range implementation-defined;

44          -- The predefined operators for the type Duration are the same as for
            -- any fixed point type.

45       -- The predefined exceptions:

46       Constraint_Error: exception;
         Program_Error   : exception;
         Storage_Error   : exception;
         Tasking_Error   : exception;

47    end Standard;

48    Standard has no private part.

49    In each of the types Character and Wide_Character, the character
literals for the space character (position 32) and the non-breaking space
character (position 160) correspond to different values. Unless indicated
otherwise, each occurrence of the character literal ' ' in this International
Standard refers to the space character. Similarly, the character literals for
hyphen (position 45) and soft hyphen (position 173) correspond to different
values. Unless indicated otherwise, each occurrence of the character literal
'-' in this International Standard refers to the hyphen character.


                              Dynamic Semantics

50    Elaboration of the body of Standard has no effect.


                         Implementation Permissions

51    An implementation may provide additional predefined integer types and
additional predefined floating point types. Not all of these types need have
names.


                            Implementation Advice

52    If an implementation provides additional named predefined integer types,
then the names should end with ``Integer'' as in ``Long_Integer''. If an
implementation provides additional named predefined floating point types, then
the names should end with ``Float'' as in ``Long_Float''.

      NOTES

53    1  Certain aspects of the predefined entities cannot be completely
      described in the language itself. For example, although the enumeration
      type Boolean can be written showing the two enumeration literals False
      and True, the short-circuit control forms cannot be expressed in the
      language.

54    2  As explained in 8.1, ``Declarative Region'' and 10.1.4, ``
      The Compilation Process'', the declarative region of the package
      Standard encloses every library unit and consequently the main
      subprogram; the declaration of every library unit is assumed to occur
      within this declarative region. Library_items are assumed to be ordered
      in such a way that there are no forward semantic dependences. However,
      as explained in 8.3, ``Visibility'', the only library units that are
      visible within a given compilation unit are the library units named by
      all with_clauses that apply to the given unit, and moreover, within the
      declarative region of a given library unit, that library unit itself.

55    3  If all block_statements of a program are named, then the name of each
      program unit can always be written as an expanded name starting with
      Standard (unless Standard is itself hidden). The name of a library unit
      cannot be a homograph of a name (such as Integer) that is already
      declared in Standard.

56    4  The exception Standard.Numeric_Error is defined in J.6.


A.2 The Package Ada



                              Static Semantics

1     The following language-defined library package exists:

2     package Ada is
          pragma Pure(Ada);
      end Ada;

3     Ada serves as the parent of most of the other language-defined library
units; its declaration is empty (except for the pragma Pure).


                               Legality Rules

4     In the standard mode, it is illegal to compile a child of package Ada.


A.3 Character Handling


1     This clause presents the packages related to character processing: an
empty pure package Characters and child packages Characters.Handling and
Characters.Latin_1. The package Characters.Handling provides classification
and conversion functions for Character data, and some simple functions for
dealing with Wide_Character data. The child package Characters.Latin_1
declares a set of constants initialized to values of type Character.


A.3.1 The Package Characters



                              Static Semantics

1     The library package Characters has the following declaration:

2     package Ada.Characters is
        pragma Pure(Characters);
      end Ada.Characters;


A.3.2 The Package Characters.Handling



                              Static Semantics

1     The library package Characters.Handling has the following declaration:

2     package Ada.Characters.Handling is
        pragma Preelaborate(Handling);

3     --Character classification functions

4       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;

5     --Conversion functions for Character and String

6       function To_Lower (Item : in Character) return Character;
        function To_Upper (Item : in Character) return Character;
        function To_Basic (Item : in Character) return Character;

7       function To_Lower (Item : in String) return String;
        function To_Upper (Item : in String) return String;
        function To_Basic (Item : in String) return String;

8     --Classifications of and conversions between Character and ISO 646

9       subtype ISO_646 is
          Character range Character'Val(0) .. Character'Val(127);

10      function Is_ISO_646 (Item : in Character) return Boolean;
        function Is_ISO_646 (Item : in String)    return Boolean;

11      function To_ISO_646 (Item       : in Character;
                             Substitute : in ISO_646 := ' ')
          return ISO_646;

12      function To_ISO_646 (Item       : in String;
                             Substitute : in ISO_646 := ' ')
          return String;

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

14      function Is_Character (Item : in Wide_Character) return Boolean;
        function Is_String    (Item : in Wide_String)    return Boolean;

15      function To_Character (Item       : in Wide_Character;
                               Substitute : in Character := ' ')
          return Character;

16      function To_String    (Item       : in Wide_String;
                               Substitute : in Character := ' ')
          return String;

17      function To_Wide_Character
       (Item : in Character) return Wide_Character;

18      function To_Wide_String    (Item : in String)    return Wide_String;

19    end Ada.Characters.Handling;

20    In the description below for each function that returns a Boolean
result, the effect is described in terms of the conditions under which the
value True is returned. If these conditions are not met, then the function
returns False.

21    Each of the following classification functions has a formal Character
parameter, Item, and returns a Boolean result.

22    Is_Control
              True if Item is a control character. A control character is a
              character whose position is in one of the ranges 0..31 or
              127..159.

23    Is_Graphic
              True if Item is a graphic character. A graphic character is a
              character whose position is in one of the ranges 32..126 or
              160..255.

24    Is_Letter
              True if Item is a letter. A letter is a character that is in one
              of the ranges 'A'..'Z' or 'a'..'z', or whose position is in one
              of the ranges 192..214, 216..246, or 248..255.

25    Is_Lower
              True if Item is a lower-case letter. A lower-case letter is a
              character that is in the range 'a'..'z', or whose position is in
              one of the ranges 223..246 or 248..255.

26    Is_Upper
              True if Item is an upper-case letter. An upper-case letter is a
              character that is in the range 'A'..'Z' or whose position is in
              one of the ranges 192..214 or 216.. 222.

27    Is_Basic
              True if Item is a basic letter. A basic letter is a character
              that is in one of the ranges 'A'..'Z' and 'a'..'z', or that is
              one of the following: '', '', '', '', '', '', or ''.

28    Is_Digit
              True if Item is a decimal digit. A decimal digit is a character
              in the range '0'..'9'.

29    Is_Decimal_Digit
              A renaming of Is_Digit.

30    Is_Hexadecimal_Digit
              True if Item is a hexadecimal digit. A hexadecimal digit is a
              character that is either a decimal digit or that is in one of
              the ranges 'A' .. 'F' or 'a' .. 'f'.

31    Is_Alphanumeric
              True if Item is an alphanumeric character. An alphanumeric
              character is a character that is either a letter or a decimal
              digit.

32    Is_Special
              True if Item is a special graphic character. A special graphic
              character is a graphic character that is not alphanumeric.

33    Each of the names To_Lower, To_Upper, and To_Basic refers to two
functions: one that converts from Character to Character, and the other that
converts from String to String. The result of each Character-to-Character
function is described below, in terms of the conversion applied to Item, its
formal Character parameter. The result of each String-to-String conversion is
obtained by applying to each element of the function's String parameter the
corresponding Character-to-Character conversion; the result is the null String
if the value of the formal parameter is the null String. The lower bound of
the result String is 1.

34    To_Lower
              Returns the corresponding lower-case value for Item if
              Is_Upper(Item), and returns Item otherwise.

35    To_Upper
              Returns the corresponding upper-case value for Item if
              Is_Lower(Item) and Item has an upper-case form, and returns Item
              otherwise. The lower case letters '' and '' do not have upper
              case forms.

36    To_Basic
              Returns the letter corresponding to Item but with no diacritical
              mark, if Item is a letter but not a basic letter; returns Item
              otherwise.

37    The following set of functions test for membership in the ISO 646
character range, or convert between ISO 646 and Character.

38    Is_ISO_646
              The function whose formal parameter, Item, is of type Character
              returns True if Item is in the subtype ISO_646.

39    Is_ISO_646
              The function whose formal parameter, Item, is of type String
              returns True if Is_ISO_646(Item(I)) is True for each I in
              Item'Range.

40    To_ISO_646
              The function whose first formal parameter, Item, is of type
              Character returns Item if Is_ISO_646(Item), and returns the
              Substitute ISO_646 character otherwise.

41    To_ISO_646
              The function whose first formal parameter, Item, is of type
              String returns the String whose Range is 1..Item'Length and each
              of whose elements is given by To_ISO_646 of the corresponding
              element in Item.

42    The following set of functions test Wide_Character values for membership
in Character, or convert between corresponding characters of Wide_Character
and Character.

43    Is_Character
              Returns True if Wide_Character'Pos(Item) <=
              Character'Pos(Character'Last).

44    Is_String
              Returns True if Is_Character(Item(I)) is True for each I in
              Item'Range.

45    To_Character
              Returns the Character corresponding to Item if
              Is_Character(Item), and returns the Substitute Character
              otherwise.

46    To_String
              Returns the String whose range is 1..Item'Length and each of
              whose elements is given by To_Character of the corresponding
              element in Item.

47    To_Wide_Character
              Returns the Wide_Character X such that Character'Pos(Item) =
              Wide_Character'Pos(X).

48    To_Wide_String
              Returns the Wide_String whose range is 1..Item'Length and each
              of whose elements is given by To_Wide_Character of the
              corresponding element in Item.


                            Implementation Advice

49    If an implementation provides a localized definition of Character or
Wide_Character, then the effects of the subprograms in Characters.Handling
should reflect the localizations. See also 3.5.2.

      NOTES

50    5  A basic letter is a letter without a diacritical mark.

51    6  Except for the hexadecimal digits, basic letters, and ISO_646
      characters, the categories identified in the classification functions
      form a strict hierarchy:

    52    - Control characters

    53    - Graphic characters

    54       - Alphanumeric characters

    55           - Letters

    56               - Upper-case letters

    57               - Lower-case letters

    58           - Decimal digits

    59       - Special graphic characters


A.3.3 The Package Characters.Latin_1


1     The package Characters.Latin_1 declares constants for characters in ISO
8859-1.


                              Static Semantics

2     The library package Characters.Latin_1 has the following declaration:

3     package Ada.Characters.Latin_1 is
          pragma Pure(Latin_1);

4     -- Control characters:

5         NUL                  : constant Character := Character'Val(0);
          SOH                  : constant Character := Character'Val(1);
          STX                  : constant Character := Character'Val(2);
          ETX                  : constant Character := Character'Val(3);
          EOT                  : constant Character := Character'Val(4);
          ENQ                  : constant Character := Character'Val(5);
          ACK                  : constant Character := Character'Val(6);
          BEL                  : constant Character := Character'Val(7);
          BS                   : constant Character := Character'Val(8);
          HT                   : constant Character := Character'Val(9);
          LF                   : constant Character := Character'Val(10);
          VT                   : constant Character := Character'Val(11);
          FF                   : constant Character := Character'Val(12);
          CR                   : constant Character := Character'Val(13);
          SO                   : constant Character := Character'Val(14);
          SI                   : constant Character := Character'Val(15);

6         DLE                  : constant Character := Character'Val(16);
          DC1                  : constant Character := Character'Val(17);
          DC2                  : constant Character := Character'Val(18);
          DC3                  : constant Character := Character'Val(19);
          DC4                  : constant Character := Character'Val(20);
          NAK                  : constant Character := Character'Val(21);
          SYN                  : constant Character := Character'Val(22);
          ETB                  : constant Character := Character'Val(23);
          CAN                  : constant Character := Character'Val(24);
          EM                   : constant Character := Character'Val(25);
          SUB                  : constant Character := Character'Val(26);
          ESC                  : constant Character := Character'Val(27);
          FS                   : constant Character := Character'Val(28);
          GS                   : constant Character := Character'Val(29);
          RS                   : constant Character := Character'Val(30);
          US                   : constant Character := Character'Val(31);

7     -- ISO 646 graphic characters:

8         Space
                      : constant Character := ' ';  -- Character'Val(32)
          Exclamation
                : constant Character := '!';  -- Character'Val(33)
          Quotation
                  : constant Character := '"';  -- Character'Val(34)
          Number_Sign
                : constant Character := '#';  -- Character'Val(35)
          Dollar_Sign
                : constant Character := '$';  -- Character'Val(36)
          Percent_Sign
               : constant Character := '%';  -- Character'Val(37)
          Ampersand
                  : constant Character := '&';  -- Character'Val(38)
          Apostrophe
                 : constant Character := ''';  -- Character'Val(39)
          Left_Parenthesis
           : constant Character := '(';  -- Character'Val(40)
          Right_Parenthesis
          : constant Character := ')';  -- Character'Val(41)
          Asterisk
                   : constant Character := '*';  -- Character'Val(42)
          Plus_Sign
                  : constant Character := '+';  -- Character'Val(43)
          Comma
                      : constant Character := ',';  -- Character'Val(44)
          Hyphen
                     : constant Character := '-';  -- Character'Val(45)
          Minus_Sign           : Character renames Hyphen;
          Full_Stop
                  : constant Character := '.';  -- Character'Val(46)
          Solidus
                    : constant Character := '/';  -- Character'Val(47)

9         -- Decimal digits '0' though '9' are at positions 48 through 57

10        Colon
                      : constant Character := ':';  -- Character'Val(58)
          Semicolon
                  : constant Character := ';';  -- Character'Val(59)
          Less_Than_Sign
             : constant Character := '<';  -- Character'Val(60)
          Equals_Sign
                : constant Character := '=';  -- Character'Val(61)
          Greater_Than_Sign
          : constant Character := '>';  -- Character'Val(62)
          Question
                   : constant Character := '?';  -- Character'Val(63)
          Commercial_At
              : constant Character := '@';  -- Character'Val(64)

11        -- Letters 'A' through 'Z' are at positions 65 through 90

12        Left_Square_Bracket
        : constant Character := '[';  -- Character'Val(91)
          Reverse_Solidus
            : constant Character := '\';  -- Character'Val(92)
          Right_Square_Bracket
       : constant Character := ']';  -- Character'Val(93)
          Circumflex
                 : constant Character := '^';  -- Character'Val(94)
          Low_Line
                   : constant Character := '_';  -- Character'Val(95)

13        Grave
                      : constant Character := '`';  -- Character'Val(96)
          LC_A
                       : constant Character := 'a';  -- Character'Val(97)
          LC_B
                       : constant Character := 'b';  -- Character'Val(98)
          LC_C
                       : constant Character := 'c';  -- Character'Val(99)
          LC_D
                       : constant Character := 'd';  -- Character'Val(100)
          LC_E
                       : constant Character := 'e';  -- Character'Val(101)
          LC_F
                       : constant Character := 'f';  -- Character'Val(102)
          LC_G
                       : constant Character := 'g';  -- Character'Val(103)
          LC_H
                       : constant Character := 'h';  -- Character'Val(104)
          LC_I
                       : constant Character := 'i';  -- Character'Val(105)
          LC_J
                       : constant Character := 'j';  -- Character'Val(106)
          LC_K
                       : constant Character := 'k';  -- Character'Val(107)
          LC_L
                       : constant Character := 'l';  -- Character'Val(108)
          LC_M
                       : constant Character := 'm';  -- Character'Val(109)
          LC_N
                       : constant Character := 'n';  -- Character'Val(110)
          LC_O
                       : constant Character := 'o';  -- Character'Val(111)

14        LC_P
                       : constant Character := 'p';  -- Character'Val(112)
          LC_Q
                       : constant Character := 'q';  -- Character'Val(113)
          LC_R
                       : constant Character := 'r';  -- Character'Val(114)
          LC_S
                       : constant Character := 's';  -- Character'Val(115)
          LC_T
                       : constant Character := 't';  -- Character'Val(116)
          LC_U
                       : constant Character := 'u';  -- Character'Val(117)
          LC_V
                       : constant Character := 'v';  -- Character'Val(118)
          LC_W
                       : constant Character := 'w';  -- Character'Val(119)
          LC_X
                       : constant Character := 'x';  -- Character'Val(120)
          LC_Y
                       : constant Character := 'y';  -- Character'Val(121)
          LC_Z
                       : constant Character := 'z';  -- Character'Val(122)
          Left_Curly_Bracket
         : constant Character := '{';  -- Character'Val(123)
          Vertical_Line
              : constant Character := '|';  -- Character'Val(124)
          Right_Curly_Bracket
        : constant Character := '}';  -- Character'Val(125)
          Tilde
                      : constant Character := '~';  -- Character'Val(126)
          DEL                  : constant Character := Character'Val(127);

15    -- ISO 6429 control characters:

16        IS4                  : Character renames FS;
          IS3                  : Character renames GS;
          IS2                  : Character renames RS;
          IS1                  : Character renames US;

17        Reserved_128         : constant Character := Character'Val(128);
          Reserved_129         : constant Character := Character'Val(129);
          BPH                  : constant Character := Character'Val(130);
          NBH                  : constant Character := Character'Val(131);
          Reserved_132         : constant Character := Character'Val(132);
          NEL                  : constant Character := Character'Val(133);
          SSA                  : constant Character := Character'Val(134);
          ESA                  : constant Character := Character'Val(135);
          HTS                  : constant Character := Character'Val(136);
          HTJ                  : constant Character := Character'Val(137);
          VTS                  : constant Character := Character'Val(138);
          PLD                  : constant Character := Character'Val(139);
          PLU                  : constant Character := Character'Val(140);
          RI                   : constant Character := Character'Val(141);
          SS2                  : constant Character := Character'Val(142);
          SS3                  : constant Character := Character'Val(143);

18        DCS                  : constant Character := Character'Val(144);
          PU1                  : constant Character := Character'Val(145);
          PU2                  : constant Character := Character'Val(146);
          STS                  : constant Character := Character'Val(147);
          CCH                  : constant Character := Character'Val(148);
          MW                   : constant Character := Character'Val(149);
          SPA                  : constant Character := Character'Val(150);
          EPA                  : constant Character := Character'Val(151);

19        SOS                  : constant Character := Character'Val(152);
          Reserved_153         : constant Character := Character'Val(153);
          SCI                  : constant Character := Character'Val(154);
          CSI                  : constant Character := Character'Val(155);
          ST                   : constant Character := Character'Val(156);
          OSC                  : constant Character := Character'Val(157);
          PM                   : constant Character := Character'Val(158);
          APC                  : constant Character := Character'Val(159);

20    -- Other graphic characters:

21    -- Character positions 160 (16#A0#) .. 175 (16#AF#):
          No_Break_Space
                    : constant Character := ' ';  --Character'Val(160)
          NBSP                        : Character renames No_Break_Space;
          Inverted_Exclamation
              : constant Character := '';  --Character'Val(161)
          Cent_Sign
                         : constant Character := '';  --Character'Val(162)
          Pound_Sign
                        : constant Character := '';  --Character'Val(163)
          Currency_Sign
                     : constant Character := '';  --Character'Val(164)
          Yen_Sign
                          : constant Character := '';  --Character'Val(165)
          Broken_Bar
                        : constant Character := '';  --Character'Val(166)
          Section_Sign
                      : constant Character := '';  --Character'Val(167)
          Diaeresis
                         : constant Character := '';  --Character'Val(168)
          Copyright_Sign
                    : constant Character := '';  --Character'Val(169)
          Feminine_Ordinal_Indicator
        : constant Character := '';  --Character'Val(170)
          Left_Angle_Quotation
              : constant Character := '';  --Character'Val(171)
          Not_Sign
                          : constant Character := '';  --Character'Val(172)
          Soft_Hyphen
                       : constant Character := '';  --Character'Val(173)
          Registered_Trade_Mark_Sign
        : constant Character := '';  --Character'Val(174)
          Macron
                            : constant Character := '';  --Character'Val(175)

22    -- Character positions 176 (16#B0#) .. 191 (16#BF#):
          Degree_Sign
                       : constant Character := '';  --Character'Val(176)
          Ring_Above                  : Character renames Degree_Sign;
          Plus_Minus_Sign
                   : constant Character := '';  --Character'Val(177)
          Superscript_Two
                   : constant Character := '';  --Character'Val(178)
          Superscript_Three
                 : constant Character := '';  --Character'Val(179)
          Acute
                             : constant Character := '';  --Character'Val(180)
          Micro_Sign
                        : constant Character := '';  --Character'Val(181)
          Pilcrow_Sign
                      : constant Character := '';  --Character'Val(182)
          Paragraph_Sign              : Character renames Pilcrow_Sign;
          Middle_Dot
                        : constant Character := '';  --Character'Val(183)
          Cedilla
                           : constant Character := '';  --Character'Val(184)
          Superscript_One
                   : constant Character := '';  --Character'Val(185)
          Masculine_Ordinal_Indicator
       : constant Character := '';  --Character'Val(186)
          Right_Angle_Quotation
             : constant Character := '';  --Character'Val(187)
          Fraction_One_Quarter
              : constant Character := '';  --Character'Val(188)
          Fraction_One_Half
                 : constant Character := '';  --Character'Val(189)
          Fraction_Three_Quarters
           : constant Character := '';  --Character'Val(190)
          Inverted_Question
                 : constant Character := '';  --Character'Val(191)

23    -- Character positions 192 (16#C0#) .. 207 (16#CF#):
          UC_A_Grave
                        : constant Character := '';  --Character'Val(192)
          UC_A_Acute
                        : constant Character := '';  --Character'Val(193)
          UC_A_Circumflex
                   : constant Character := '';  --Character'Val(194)
          UC_A_Tilde
                        : constant Character := '';  --Character'Val(195)
          UC_A_Diaeresis
                    : constant Character := '';  --Character'Val(196)
          UC_A_Ring
                         : constant Character := '';  --Character'Val(197)
          UC_AE_Diphthong
                   : constant Character := '';  --Character'Val(198)
          UC_C_Cedilla
                      : constant Character := '';  --Character'Val(199)
          UC_E_Grave
                        : constant Character := '';  --Character'Val(200)
          UC_E_Acute
                        : constant Character := '';  --Character'Val(201)
          UC_E_Circumflex
                   : constant Character := '';  --Character'Val(202)
          UC_E_Diaeresis
                    : constant Character := '';  --Character'Val(203)
          UC_I_Grave
                        : constant Character := '';  --Character'Val(204)
          UC_I_Acute
                        : constant Character := '';  --Character'Val(205)
          UC_I_Circumflex
                   : constant Character := '';  --Character'Val(206)
          UC_I_Diaeresis
                    : constant Character := '';  --Character'Val(207)

24    -- Character positions 208 (16#D0#) .. 223 (16#DF#):
          UC_Icelandic_Eth
                  : constant Character := '';  --Character'Val(208)
          UC_N_Tilde
                        : constant Character := '';  --Character'Val(209)
          UC_O_Grave
                        : constant Character := '';  --Character'Val(210)
          UC_O_Acute
                        : constant Character := '';  --Character'Val(211)
          UC_O_Circumflex
                   : constant Character := '';  --Character'Val(212)
          UC_O_Tilde
                        : constant Character := '';  --Character'Val(213)
          UC_O_Diaeresis
                    : constant Character := '';  --Character'Val(214)
          Multiplication_Sign
               : constant Character := '';  --Character'Val(215)
          UC_O_Oblique_Stroke
               : constant Character := '';  --Character'Val(216)
          UC_U_Grave
                        : constant Character := '';  --Character'Val(217)
          UC_U_Acute
                        : constant Character := '';  --Character'Val(218)
          UC_U_Circumflex
                   : constant Character := '';  --Character'Val(219)
          UC_U_Diaeresis
                    : constant Character := '';  --Character'Val(220)
          UC_Y_Acute
                        : constant Character := '';  --Character'Val(221)
          UC_Icelandic_Thorn
                : constant Character := '';  --Character'Val(222)
          LC_German_Sharp_S
                 : constant Character := '';  --Character'Val(223)

25    -- Character positions 224 (16#E0#) .. 239 (16#EF#):
          LC_A_Grave
                        : constant Character := '';  --Character'Val(224)
          LC_A_Acute
                        : constant Character := '';  --Character'Val(225)
          LC_A_Circumflex
                   : constant Character := '';  --Character'Val(226)
          LC_A_Tilde
                        : constant Character := '';  --Character'Val(227)
          LC_A_Diaeresis
                    : constant Character := '';  --Character'Val(228)
          LC_A_Ring
                         : constant Character := '';  --Character'Val(229)
          LC_AE_Diphthong
                   : constant Character := '';  --Character'Val(230)
          LC_C_Cedilla
                      : constant Character := '';  --Character'Val(231)
          LC_E_Grave
                        : constant Character := '';  --Character'Val(232)
          LC_E_Acute
                        : constant Character := '';  --Character'Val(233)
          LC_E_Circumflex
                   : constant Character := '';  --Character'Val(234)
          LC_E_Diaeresis
                    : constant Character := '';  --Character'Val(235)
          LC_I_Grave
                        : constant Character := '';  --Character'Val(236)
          LC_I_Acute
                        : constant Character := '';  --Character'Val(237)
          LC_I_Circumflex
                   : constant Character := '';  --Character'Val(238)
          LC_I_Diaeresis
                    : constant Character := '';  --Character'Val(239)

26    -- Character positions 240 (16#F0#) .. 255 (16#FF#):
          LC_Icelandic_Eth
                  : constant Character := '';  --Character'Val(240)
          LC_N_Tilde
                        : constant Character := '';  --Character'Val(241)
          LC_O_Grave
                        : constant Character := '';  --Character'Val(242)
          LC_O_Acute
                        : constant Character := '';  --Character'Val(243)
          LC_O_Circumflex
                   : constant Character := '';  --Character'Val(244)
          LC_O_Tilde
                        : constant Character := '';  --Character'Val(245)
          LC_O_Diaeresis
                    : constant Character := '';  --Character'Val(246)
          Division_Sign
                     : constant Character := '';  --Character'Val(247)
          LC_O_Oblique_Stroke
               : constant Character := '';  --Character'Val(248)
          LC_U_Grave
                        : constant Character := '';  --Character'Val(249)
          LC_U_Acute
                        : constant Character := '';  --Character'Val(250)
          LC_U_Circumflex
                   : constant Character := '';  --Character'Val(251)
          LC_U_Diaeresis
                    : constant Character := '';  --Character'Val(252)
          LC_Y_Acute
                        : constant Character := '';  --Character'Val(253)
          LC_Icelandic_Thorn
                : constant Character := '';  --Character'Val(254)
          LC_Y_Diaeresis
                    : constant Character := '';  --Character'Val(255)
      end Ada.Characters.Latin_1;


                         Implementation Permissions

27    An implementation may provide additional packages as children of
Ada.Characters, to declare names for the symbols of the local character set or
other character sets.


A.4 String Handling


1     This clause presents the specifications of the package Strings and
several child packages, which provide facilities for dealing with string data.
Fixed-length, bounded-length, and unbounded-length strings are supported, for
both String and Wide_String. The string-handling subprograms include searches
for pattern strings and for characters in program-specified sets, translation
(via a character-to-character mapping), and transformation (replacing,
inserting, overwriting, and deleting of substrings).


A.4.1 The Package Strings


1     The package Strings provides declarations common to the string handling
packages.


                              Static Semantics

2     The library package Strings has the following declaration:

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

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

5        Length_Error, Pattern_Error, Index_Error, Translation_Error
       : exception;

6        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;




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

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.


A.4.3 Fixed-Length String Handling


1     The language-defined package Strings.Fixed provides string-handling
subprograms for fixed-length strings; that is, for values of type
Standard.String. Several of these subprograms are procedures that modify the
contents of a String that is passed as an out or an in out parameter; each has
additional parameters to control the effect when the logical length of the
result differs from the parameter's length.

2     For each function that returns a String, the lower bound of the returned
value is 1.

3     The basic model embodied in the package is that a fixed-length string
comprises significant characters and possibly padding (with space characters)
on either or both ends. When a shorter string is copied to a longer string,
padding is inserted, and when a longer string is copied to a shorter one,
padding is stripped. The Move procedure in Strings.Fixed, which takes a String
as an out parameter, allows the programmer to control these effects. Similar
control is provided by the string transformation procedures.


                              Static Semantics

4     The library package Strings.Fixed has the following declaration:

5     with Ada.Strings.Maps;
      package Ada.Strings.Fixed is
         pragma Preelaborate(Fixed);

6     -- "Copy" procedure for strings of possibly different lengths

7        procedure Move (Source  : in  String;
                         Target  : out String;
                         Drop    : in  Truncation := Error;
                         Justify : in  Alignment  := Left;
                         Pad     : in  Character  := Space);

8     -- Search subprograms

9        function Index (Source   : in String;
                         Pattern  : in String;
                         Going    : in Direction := Forward;
                         Mapping  : in Maps.Character_Mapping
                                      := Maps.Identity)
            return Natural;

10       function Index (Source   : in String;
                         Pattern  : in String;
                         Going    : in Direction := Forward;
                         Mapping  : in Maps.Character_Mapping_Function)
            return Natural;

11       function Index (Source : in String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership := Inside;
                         Going  : in Direction  := Forward)
            return Natural;

12       function Index_Non_Blank (Source : in String;
                                   Going  : in Direction := Forward)
            return Natural;

13       function Count (Source   : in String;
                         Pattern  : in String;
                         Mapping  : in Maps.Character_Mapping
                                       := Maps.Identity)
            return Natural;

14       function Count (Source   : in String;
                         Pattern  : in String;
                         Mapping  : in Maps.Character_Mapping_Function)
            return Natural;

15       function Count (Source   : in String;
                         Set      : in Maps.Character_Set)
            return Natural;

16       procedure Find_Token (Source : in String;
                               Set    : in Maps.Character_Set;
                               Test   : in Membership;
                               First  : out Positive;
                               Last   : out Natural);

17    -- String translation subprograms

18       function Translate (Source  : in String;
                             Mapping : in Maps.Character_Mapping)
            return String;

19       procedure Translate (Source  : in out String;
                              Mapping : in Maps.Character_Mapping);

20       function Translate (Source  : in String;
                             Mapping : in Maps.Character_Mapping_Function)
            return String;

21       procedure Translate (Source  : in out String;
                              Mapping : in Maps.Character_Mapping_Function);

22    -- String transformation subprograms

23       function Replace_Slice (Source   : in String;
                                 Low      : in Positive;
                                 High     : in Natural;
                                 By       : in String)
            return String;

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

25       function Insert (Source   : in String;
                          Before   : in Positive;
                          New_Item : in String)
            return String;

26       procedure Insert (Source   : in out String;
                           Before   : in Positive;
                           New_Item : in String;
                           Drop     : in Truncation := Error);

27       function Overwrite (Source   : in String;
                             Position : in Positive;
                             New_Item : in String)
            return String;

28       procedure Overwrite (Source   : in out String;
                              Position : in Positive;
                              New_Item : in String;
                              Drop     : in Truncation := Right);

29       function Delete (Source  : in String;
                          From    : in Positive;
                          Through : in Natural)
            return String;

30       procedure Delete (Source  : in out String;
                           From    : in Positive;
                           Through : in Natural;
                           Justify : in Alignment := Left;
                           Pad     : in Character := Space);

31     --String selector subprograms
         function Trim (Source : in String;
                        Side   : in Trim_End)
            return String;

32       procedure Trim (Source  : in out String;
                         Side    : in Trim_End;
                         Justify : in Alignment := Left;
                         Pad     : in Character := Space);

33       function Trim (Source : in String;
                        Left   : in Maps.Character_Set;
                        Right  : in Maps.Character_Set)
            return String;

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

35       function Head (Source : in String;
                        Count  : in Natural;
                        Pad    : in Character := Space)
            return String;

36       procedure Head (Source  : in out String;
                         Count   : in Natural;
                         Justify : in Alignment := Left;
                         Pad     : in Character := Space);

37       function Tail (Source : in String;
                        Count  : in Natural;
                        Pad    : in Character := Space)
            return String;

38       procedure Tail (Source  : in out String;
                         Count   : in Natural;
                         Justify : in Alignment := Left;
                         Pad     : in Character := Space);

39    --String constructor functions

40       function "*" (Left  : in Natural;
                       Right : in Character) return String;

41       function "*" (Left  : in Natural;
                       Right : in String) return String;

42    end Ada.Strings.Fixed;

43    The effects of the above subprograms are as follows.

44    procedure Move (Source  : in  String;
                      Target  : out String;
                      Drop    : in  Truncation := Error;
                      Justify : in  Alignment  := Left;
                      Pad     : in  Character  := Space);

    45    The Move procedure copies characters from Source to Target. If
          Source has the same length as Target, then the effect is to assign
          Source to Target. If Source is shorter than Target then:

        46    If Justify=Left, then Source is copied into the first
              Source'Length characters of Target.

        47    If Justify=Right, then Source is copied into the last
              Source'Length characters of Target.

        48    If Justify=Center, then Source is copied into the middle
              Source'Length characters of Target. In this case, if the
              difference in length between Target and Source is odd, then the
              extra Pad character is on the right.

        49    Pad is copied to each Target character not otherwise assigned.

    50    If Source is longer than Target, then the effect is based on Drop.

        51    If Drop=Left, then the rightmost Target'Length characters of
              Source are copied into Target.

        52    If Drop=Right, then the leftmost Target'Length characters of
              Source are copied into Target.

        53    If Drop=Error, then the effect depends on the value of the
              Justify parameter and also on whether any characters in Source
              other than Pad would fail to be copied:

            54    If Justify=Left, and if each of the rightmost
                  Source'Length-Target'Length characters in Source is Pad,
                  then the leftmost Target'Length characters of Source are
                  copied to Target.

            55    If Justify=Right, and if each of the leftmost
                  Source'Length-Target'Length characters in Source is Pad,
                  then the rightmost Target'Length characters of Source are
                  copied to Target.

            56    Otherwise, Length_Error is propagated.

57    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;

    58    Each Index function searches for a slice of Source, with length
          Pattern'Length, that matches Pattern with respect to Mapping; the
          parameter Going indicates the direction of the lookup. If Going =
          Forward, then Index returns the smallest index I such that the slice
          of Source starting at I matches Pattern. If Going = Backward, then
          Index returns the largest index I such that the slice of Source
          starting at I matches Pattern. If there is no such slice, then 0 is
          returned. If Pattern is the null string then Pattern_Error is
          propagated.

59    function Index (Source : in String;
                      Set    : in Maps.Character_Set;
                      Test   : in Membership := Inside;
                      Going  : in Direction  := Forward)
         return Natural;

    60    Index searches for the first or last occurrence of any of a set of
          characters (when Test=Inside), or any of the complement of a set of
          characters (when Test=Outside). It returns the smallest index I (if
          Going=Forward) or the largest index I (if Going=Backward) such that
          Source(I) satisfies the Test condition with respect to Set; it
          returns 0 if there is no such Character in Source.

61    function Index_Non_Blank (Source : in String;
                                Going  : in Direction := Forward)
         return Natural;

    62    Returns Index(Source, Maps.To_Set(Space), Outside, Going)

63    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;

    64    Returns the maximum number of nonoverlapping slices of Source that
          match Pattern with respect to Mapping. If Pattern is the null string
          then Pattern_Error is propagated.

65    function Count (Source   : in String;
                      Set      : in Maps.Character_Set)
         return Natural;

    66    Returns the number of occurrences in Source of characters that are
          in Set.

67    procedure Find_Token (Source : in String;
                            Set    : in Maps.Character_Set;
                            Test   : in Membership;
                            First  : out Positive;
                            Last   : out Natural);

    68/1  Find_Token returns in First and Last the indices of the beginning
          and end of the first slice of Source all of whose elements satisfy
          the Test condition, and such that the elements (if any) immediately
          before and after the slice do not satisfy the Test condition. If no
          such slice exists, then the value returned for Last is zero, and the
          value returned for First is Source'First; however, if Source'First
          is not in Positive then Constraint_Error is raised.

69    function Translate (Source  : in String;
                          Mapping : in Maps.Character_Mapping)
         return String;
      
      function Translate (Source  : in String;
                          Mapping : in Maps.Character_Mapping_Function)
         return String;

    70    Returns the string S whose length is Source'Length and such that
          S(I) is the character to which Mapping maps the corresponding
          element of Source, for I in 1..Source'Length.

71    procedure Translate (Source  : in out String;
                           Mapping : in Maps.Character_Mapping);
      
      procedure Translate (Source  : in out String;
                           Mapping : in Maps.Character_Mapping_Function);

    72    Equivalent to Source := Translate(Source, Mapping).

73    function Replace_Slice (Source   : in String;
                              Low      : in Positive;
                              High     : in Natural;
                              By       : in String)
         return String;

    74/1  If Low > Source'Last+1, or High < Source'First-1, then Index_Error
          is propagated. Otherwise:

        74.1/1 If High >= Low, then the returned string comprises
              Source(Source'First..Low-1) & By & Source(High+1..Source'Last),
              but with lower bound 1.

        74.2/1 If High < Low, then the returned string is Insert(Source,
              Before=>Low, New_Item=>By).

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

    76    Equivalent to Move(Replace_Slice(Source, Low, High, By), Source,
          Drop, Justify, Pad).

77    function Insert (Source   : in String;
                       Before   : in Positive;
                       New_Item : in String)
         return String;

    78    Propagates Index_Error if Before is not in Source'First ..
          Source'Last+1; otherwise returns Source(Source'First..Before-1) &
          New_Item & Source(Before..Source'Last), but with lower bound 1.

79    procedure Insert (Source   : in out String;
                        Before   : in Positive;
                        New_Item : in String;
                        Drop     : in Truncation := Error);

    80    Equivalent to Move(Insert(Source, Before, New_Item), Source, Drop).

81    function Overwrite (Source   : in String;
                          Position : in Positive;
                          New_Item : in String)
         return String;

    82    Propagates Index_Error if Position is not in Source'First ..
          Source'Last+1; otherwise returns the string obtained from Source by
          consecutively replacing characters starting at Position with
          corresponding characters from New_Item. If the end of Source is
          reached before the characters in New_Item are exhausted, the
          remaining characters from New_Item are appended to the string.

83    procedure Overwrite (Source   : in out String;
                           Position : in Positive;
                           New_Item : in String;
                           Drop     : in Truncation := Right);

    84    Equivalent to Move(Overwrite(Source, Position, New_Item), Source,
          Drop).

85    function Delete (Source  : in String;
                       From    : in Positive;
                       Through : in Natural)
         return String;

    86/1  If From <= Through, the returned string is Replace_Slice(Source,
          From, Through, ""), otherwise it is Source with lower bound 1.

87    procedure Delete (Source  : in out String;
                        From    : in Positive;
                        Through : in Natural;
                        Justify : in Alignment := Left;
                        Pad     : in Character := Space);

    88    Equivalent to Move(Delete(Source, From, Through), Source, Justify =>
          Justify, Pad => Pad).

89    function Trim (Source : in String;
                     Side   : in Trim_End)
        return String;

    90    Returns the string obtained by removing from Source all leading
          Space characters (if Side = Left), all trailing Space characters (if
          Side = Right), or all leading and trailing Space characters (if Side
          = Both).

91    procedure Trim (Source  : in out String;
                      Side    : in Trim_End;
                      Justify : in Alignment := Left;
                      Pad     : in Character := Space);

    92    Equivalent to Move(Trim(Source, Side), Source, Justify=>Justify,
          Pad=>Pad).

93    function Trim (Source : in String;
                     Left   : in Maps.Character_Set;
                     Right  : in Maps.Character_Set)
         return String;

    94    Returns the string obtained by removing from Source all leading
          characters in Left and all trailing characters in Right.

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

    96    Equivalent to Move(Trim(Source, Left, Right), Source, Justify =>
          Justify, Pad=>Pad).

97    function Head (Source : in String;
                     Count  : in Natural;
                     Pad    : in Character := Space)
         return String;

    98    Returns a string of length Count. If Count <= Source'Length, the
          string comprises the first Count characters of Source. Otherwise its
          contents are Source concatenated with Count-Source'Length Pad
          characters.

99    procedure Head (Source  : in out String;
                      Count   : in Natural;
                      Justify : in Alignment := Left;
                      Pad     : in Character := Space);

    100   Equivalent to Move(Head(Source, Count, Pad), Source, Drop=>Error,
          Justify=>Justify, Pad=>Pad).

101   function Tail (Source : in String;
                     Count  : in Natural;
                     Pad    : in Character := Space)
         return String;

    102   Returns a string of length Count. If Count <= Source'Length, the
          string comprises the last Count characters of Source. Otherwise its
          contents are Count-Source'Length Pad characters concatenated with
          Source.

103   procedure Tail (Source  : in out String;
                      Count   : in Natural;
                      Justify : in Alignment := Left;
                      Pad     : in Character := Space);

    104   Equivalent to Move(Tail(Source, Count, Pad), Source, Drop=>Error,
          Justify=>Justify, Pad=>Pad).

105   function "*" (Left  : in Natural;
                    Right : in Character) return String;
      
      function "*" (Left  : in Natural;
                    Right : in String) return String;

    106/1 These functions replicate a character or string a specified number
          of times. The first function returns a string whose length is Left
          and each of whose elements is Right. The second function returns a
          string whose length is Left*Right'Length and whose value is the null
          string if Left = 0 and otherwise is (Left-1)*Right & Right with
          lower bound 1.

      NOTES

107   9  In the Index and Count functions taking Pattern and Mapping
      parameters, the actual String parameter passed to Pattern should
      comprise characters occurring as target characters of the mapping.
      Otherwise the pattern will not match.

108   10  In the Insert subprograms, inserting at the end of a string is
      obtained by passing Source'Last+1 as the Before parameter.

109   11  If a null Character_Mapping_Function is passed to any of the string
      handling subprograms, Constraint_Error is propagated.


A.4.4 Bounded-Length String Handling


1     The language-defined package Strings.Bounded provides a generic package
each of whose instances yields a private type Bounded_String and a set of
operations. An object of a particular Bounded_String type represents a String
whose low bound is 1 and whose length can vary conceptually between 0 and a
maximum size established at the generic instantiation. The subprograms for
fixed-length string handling are either overloaded directly for
Bounded_String, or are modified as needed to reflect the variability in
length. Additionally, since the Bounded_String type is private, appropriate
constructor and selector operations are provided.


                              Static Semantics

2     The library package Strings.Bounded has the following declaration:

3     with Ada.Strings.Maps;
      package Ada.Strings.Bounded is
         pragma Preelaborate(Bounded);

4        generic
            Max   : Positive;    -- Maximum length of a Bounded_String
         package Generic_Bounded_Length is

5           Max_Length : constant Positive := Max;

6           type Bounded_String is private;

7           Null_Bounded_String : constant Bounded_String;

8           subtype Length_Range is Natural range 0 .. Max_Length;

9           function Length (Source : in Bounded_String) return Length_Range;

10       -- Conversion, Concatenation, and Selection functions

11          function To_Bounded_String (Source : in String;
                                        Drop   : in Truncation := Error)
               return Bounded_String;

12          function To_String (Source : in Bounded_String) return String;

13          function Append (Left, Right : in Bounded_String;
                             Drop        : in Truncation  := Error)
               return Bounded_String;

14          function Append (Left  : in Bounded_String;
                             Right : in String;
                             Drop  : in Truncation := Error)
               return Bounded_String;

15          function Append (Left  : in String;
                             Right : in Bounded_String;
                             Drop  : in Truncation := Error)
               return Bounded_String;

16          function Append (Left  : in Bounded_String;
                             Right : in Character;
                             Drop  : in Truncation := Error)
               return Bounded_String;

17          function Append (Left  : in Character;
                             Right : in Bounded_String;
                             Drop  : in Truncation := Error)
               return Bounded_String;

18          procedure Append (Source   : in out Bounded_String;
                              New_Item : in Bounded_String;
                              Drop     : in Truncation  := Error);

19          procedure Append (Source   : in out Bounded_String;
                              New_Item : in String;
                              Drop     : in Truncation  := Error);

20          procedure Append (Source   : in out Bounded_String;
                              New_Item : in Character;
                              Drop     : in Truncation  := Error);

21          function "&" (Left, Right : in Bounded_String)
               return Bounded_String;

22          function "&" (Left : in Bounded_String; Right : in String)
               return Bounded_String;

23          function "&" (Left : in String; Right : in Bounded_String)
               return Bounded_String;

24          function "&" (Left : in Bounded_String; Right : in Character)
               return Bounded_String;

25          function "&" (Left : in Character; Right : in Bounded_String)
               return Bounded_String;

26          function Element (Source : in Bounded_String;
                              Index  : in Positive)
               return Character;

27          procedure Replace_Element (Source : in out Bounded_String;
                                       Index  : in Positive;
                                       By     : in Character);

28          function Slice (Source : in Bounded_String;
                            Low    : in Positive;
                            High   : in Natural)
               return String;

29          function "="  (Left, Right : in Bounded_String) return Boolean;
            function "="  (Left : in Bounded_String; Right : in String)
              return Boolean;

30          function "="  (Left : in String; Right : in Bounded_String)
              return Boolean;

31          function "<"  (Left, Right : in Bounded_String) return Boolean;

32          function "<"  (Left : in Bounded_String; Right : in String)
              return Boolean;

33          function "<"  (Left : in String; Right : in Bounded_String)
              return Boolean;

34          function "<=" (Left, Right : in Bounded_String) return Boolean;

35          function "<="  (Left : in Bounded_String; Right : in String)
              return Boolean;

36          function "<="  (Left : in String; Right : in Bounded_String)
              return Boolean;

37          function ">"  (Left, Right : in Bounded_String) return Boolean;

38          function ">"  (Left : in Bounded_String; Right : in String)
              return Boolean;

39          function ">"  (Left : in String; Right : in Bounded_String)
              return Boolean;

40          function ">=" (Left, Right : in Bounded_String) return Boolean;

41          function ">="  (Left : in Bounded_String; Right : in String)
              return Boolean;

42          function ">="  (Left : in String; Right : in Bounded_String)
              return Boolean;

43       -- Search functions

44          function Index (Source   : in Bounded_String;
                            Pattern  : in String;
                            Going    : in Direction := Forward;
                            Mapping  : in Maps.Character_Mapping
                                       := Maps.Identity)
               return Natural;

45          function Index (Source   : in Bounded_String;
                            Pattern  : in String;
                            Going    : in Direction := Forward;
                            Mapping  : in Maps.Character_Mapping_Function)
               return Natural;

46          function Index (Source : in Bounded_String;
                            Set    : in Maps.Character_Set;
                            Test   : in Membership := Inside;
                            Going  : in Direction  := Forward)
               return Natural;

47          function Index_Non_Blank (Source : in Bounded_String;
                                      Going  : in Direction := Forward)
               return Natural;

48          function Count (Source   : in Bounded_String;
                            Pattern  : in String;
                            Mapping  : in Maps.Character_Mapping
                                         := Maps.Identity)
               return Natural;

49          function Count (Source   : in Bounded_String;
                            Pattern  : in String;
                            Mapping  : in Maps.Character_Mapping_Function)
               return Natural;

50          function Count (Source   : in Bounded_String;
                            Set      : in Maps.Character_Set)
               return Natural;

51          procedure Find_Token (Source : in Bounded_String;
                                  Set    : in Maps.Character_Set;
                                  Test   : in Membership;
                                  First  : out Positive;
                                  Last   : out Natural);

52       -- String translation subprograms

53          function Translate (Source  : in Bounded_String;
                                Mapping : in Maps.Character_Mapping)
               return Bounded_String;

54          procedure Translate (Source  : in out Bounded_String;
                                 Mapping : in Maps.Character_Mapping);

55          function Translate (Source  : in Bounded_String;
                                Mapping : in Maps.Character_Mapping_Function)
               return Bounded_String;

56          procedure Translate (Source  : in out Bounded_String;
                                 Mapping : in Maps.Character_Mapping_Function);

57       -- String transformation subprograms

58          function Replace_Slice (Source   : in Bounded_String;
                                    Low      : in Positive;
                                    High     : in Natural;
                                    By       : in String;
                                    Drop     : in Truncation := Error)
               return Bounded_String;

59          procedure Replace_Slice (Source   : in out Bounded_String;
                                     Low      : in Positive;
                                     High     : in Natural;
                                     By       : in String;
                                     Drop     : in Truncation := Error);

60          function Insert (Source   : in Bounded_String;
                             Before   : in Positive;
                             New_Item : in String;
                             Drop     : in Truncation := Error)
               return Bounded_String;

61          procedure Insert (Source   : in out Bounded_String;
                              Before   : in Positive;
                              New_Item : in String;
                              Drop     : in Truncation := Error);

62          function Overwrite (Source    : in Bounded_String;
                                Position  : in Positive;
                                New_Item  : in String;
                                Drop      : in Truncation := Error)
               return Bounded_String;

63          procedure Overwrite (Source    : in out Bounded_String;
                                 Position  : in Positive;
                                 New_Item  : in String;
                                 Drop      : in Truncation := Error);

64          function Delete (Source  : in Bounded_String;
                             From    : in Positive;
                             Through : in Natural)
               return Bounded_String;

65          procedure Delete (Source  : in out Bounded_String;
                              From    : in Positive;
                              Through : in Natural);

66    --String selector subprograms

67          function Trim (Source : in Bounded_String;
                           Side   : in Trim_End)
               return Bounded_String;
            procedure Trim (Source : in out Bounded_String;
                            Side   : in Trim_End);

68          function Trim (Source : in Bounded_String;
                           Left   : in Maps.Character_Set;
                           Right  : in Maps.Character_Set)
               return Bounded_String;

69          procedure Trim (Source : in out Bounded_String;
                            Left   : in Maps.Character_Set;
                            Right  : in Maps.Character_Set);

70          function Head (Source : in Bounded_String;
                           Count  : in Natural;
                           Pad    : in Character  := Space;
                           Drop   : in Truncation := Error)
               return Bounded_String;

71          procedure Head (Source : in out Bounded_String;
                            Count  : in Natural;
                            Pad    : in Character  := Space;
                            Drop   : in Truncation := Error);

72          function Tail (Source : in Bounded_String;
                           Count  : in Natural;
                           Pad    : in Character  := Space;
                           Drop   : in Truncation := Error)
               return Bounded_String;

73          procedure Tail (Source : in out Bounded_String;
                            Count  : in Natural;
                            Pad    : in Character  := Space;
                            Drop   : in Truncation := Error);

74    --String constructor subprograms

75          function "*" (Left  : in Natural;
                          Right : in Character)
               return Bounded_String;

76          function "*" (Left  : in Natural;
                          Right : in String)
               return Bounded_String;

77          function "*" (Left  : in Natural;
                          Right : in Bounded_String)
               return Bounded_String;

78          function Replicate (Count : in Natural;
                                Item  : in Character;
                                Drop  : in Truncation := Error)
               return Bounded_String;

79          function Replicate (Count : in Natural;
                                Item  : in String;
                                Drop  : in Truncation := Error)
               return Bounded_String;

80          function Replicate (Count : in Natural;
                                Item  : in Bounded_String;
                                Drop  : in Truncation := Error)
               return Bounded_String;

81       private
             ... -- not specified by the language
         end Generic_Bounded_Length;

82    end Ada.Strings.Bounded;

83    Null_Bounded_String represents the null string. If an object of type
Bounded_String is not otherwise initialized, it will be initialized to the
same value as Null_Bounded_String.

84    function Length (Source : in Bounded_String) return Length_Range;

    85    The Length function returns the length of the string represented by
          Source.

86    function To_Bounded_String (Source : in String;
                                  Drop   : in Truncation := Error)
         return Bounded_String;

    87    If Source'Length <= Max_Length then this function returns a
          Bounded_String that represents Source. Otherwise the effect depends
          on the value of Drop:

        88    If Drop=Left, then the result is a Bounded_String that
              represents the string comprising the rightmost Max_Length
              characters of Source.

        89    If Drop=Right, then the result is a Bounded_String that
              represents the string comprising the leftmost Max_Length
              characters of Source.

        90    If Drop=Error, then Strings.Length_Error is propagated.

91    function To_String (Source : in Bounded_String) return String;

    92    To_String returns the String value with lower bound 1 represented by
          Source. If B is a Bounded_String, then B =
          To_Bounded_String(To_String(B)).

93    Each of the Append functions returns a Bounded_String obtained by
concatenating the string or character given or represented by one of the
parameters, with the string or character given or represented by the other
parameter, and applying To_Bounded_String to the concatenation result string,
with Drop as provided to the Append function.

94    Each of the procedures Append(Source, New_Item, Drop) has the same
effect as the corresponding assignment Source := Append(Source, New_Item,
Drop).

95    Each of the "&" functions has the same effect as the corresponding
Append function, with Error as the Drop parameter.

96    function Element (Source : in Bounded_String;
                        Index  : in Positive)
         return Character;

    97    Returns the character at position Index in the string represented by
          Source; propagates Index_Error if Index > Length(Source).

98    procedure Replace_Element (Source : in out Bounded_String;
                                 Index  : in Positive;
                                 By     : in Character);

    99    Updates Source such that the character at position Index in the
          string represented by Source is By; propagates Index_Error if Index
          > Length(Source).

100   function Slice (Source : in Bounded_String;
                      Low    : in Positive;
                      High   : in Natural)
         return String;

    101/1 Returns the slice at positions Low through High in the string
          represented by Source; propagates Index_Error if Low >
          Length(Source)+1 or High > Length(Source).

102   Each of the functions "=", "<", ">","<=", and ">=" returns the same
result as the corresponding String operation applied to the String values
given or represented by the two parameters.

103   Each of the search subprograms (Index, Index_Non_Blank, Count,
Find_Token) has the same effect as the corresponding subprogram in
Strings.Fixed applied to the string represented by the Bounded_String
parameter.

104   Each of the Translate subprograms, when applied to a Bounded_String, has
an analogous effect to the corresponding subprogram in Strings.Fixed. For the
Translate function, the translation is applied to the string represented by
the Bounded_String parameter, and the result is converted (via
To_Bounded_String) to a Bounded_String. For the Translate procedure, the
string represented by the Bounded_String parameter after the translation is
given by the Translate function for fixed-length strings applied to the string
represented by the original value of the parameter.

105/1 Each of the transformation subprograms (Replace_Slice, Insert,
Overwrite, Delete), selector subprograms (Trim, Head, Tail), and constructor
functions ("*") has an effect based on its corresponding subprogram in
Strings.Fixed, and Replicate is based on Fixed."*". In the case of a function,
the corresponding fixed-length string subprogram is applied to the string
represented by the Bounded_String parameter. To_Bounded_String is applied the
result string, with Drop (or Error in the case of Generic_Bounded_Length."*")
determining the effect when the string length exceeds Max_Length. In the case
of a procedure, the corresponding function in Strings.Bounded.Generic_Bounded_-
Length is applied, with the result assigned into the Source parameter.


                            Implementation Advice

106   Bounded string objects should not be implemented by implicit pointers
and dynamic allocation.


A.4.5 Unbounded-Length String Handling


1     The language-defined package Strings.Unbounded provides a private type
Unbounded_String and a set of operations. An object of type Unbounded_String
represents a String whose low bound is 1 and whose length can vary
conceptually between 0 and Natural'Last. The subprograms for fixed-length
string handling are either overloaded directly for Unbounded_String, or are
modified as needed to reflect the flexibility in length. Since the
Unbounded_String type is private, relevant constructor and selector operations
are provided.


                              Static Semantics

2     The library package Strings.Unbounded has the following declaration:

3     with Ada.Strings.Maps;
      package Ada.Strings.Unbounded is
         pragma Preelaborate(Unbounded);

4        type Unbounded_String is private;

5        Null_Unbounded_String : constant Unbounded_String;

6        function Length (Source : in Unbounded_String) return Natural;

7        type String_Access is access all String;
         procedure Free (X : in out String_Access);

8     -- Conversion, Concatenation, and Selection functions

9        function To_Unbounded_String (Source : in String)
            return Unbounded_String;

10       function To_Unbounded_String (Length : in Natural)
            return Unbounded_String;

11       function To_String (Source : in Unbounded_String) return String;

12       procedure Append (Source   : in out Unbounded_String;
                           New_Item : in Unbounded_String);

13       procedure Append (Source   : in out Unbounded_String;
                           New_Item : in String);

14       procedure Append (Source   : in out Unbounded_String;
                           New_Item : in Character);

15       function "&" (Left, Right : in Unbounded_String)
            return Unbounded_String;

16       function "&" (Left : in Unbounded_String; Right : in String)
            return Unbounded_String;

17       function "&" (Left : in String; Right : in Unbounded_String)
            return Unbounded_String;

18       function "&" (Left : in Unbounded_String; Right : in Character)
            return Unbounded_String;

19       function "&" (Left : in Character; Right : in Unbounded_String)
            return Unbounded_String;

20       function Element (Source : in Unbounded_String;
                           Index  : in Positive)
            return Character;

21       procedure Replace_Element (Source : in out Unbounded_String;
                                    Index  : in Positive;
                                    By     : in Character);

22       function Slice (Source : in Unbounded_String;
                         Low    : in Positive;
                         High   : in Natural)
            return String;

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

24       function "="  (Left : in Unbounded_String; Right : in String)
           return Boolean;

25       function "="  (Left : in String; Right : in Unbounded_String)
           return Boolean;

26       function "<"  (Left, Right : in Unbounded_String) return Boolean;

27       function "<"  (Left : in Unbounded_String; Right : in String)
           return Boolean;

28       function "<"  (Left : in String; Right : in Unbounded_String)
           return Boolean;

29       function "<=" (Left, Right : in Unbounded_String) return Boolean;

30       function "<="  (Left : in Unbounded_String; Right : in String)
           return Boolean;

31       function "<="  (Left : in String; Right : in Unbounded_String)
           return Boolean;

32       function ">"  (Left, Right : in Unbounded_String) return Boolean;

33       function ">"  (Left : in Unbounded_String; Right : in String)
           return Boolean;

34       function ">"  (Left : in String; Right : in Unbounded_String)
           return Boolean;

35       function ">=" (Left, Right : in Unbounded_String) return Boolean;

36       function ">="  (Left : in Unbounded_String; Right : in String)
           return Boolean;

37       function ">="  (Left : in String; Right : in Unbounded_String)
           return Boolean;

38    -- Search subprograms

39       function Index (Source   : in Unbounded_String;
                         Pattern  : in String;
                         Going    : in Direction := Forward;
                         Mapping  : in Maps.Character_Mapping
                                      := Maps.Identity)
            return Natural;

40       function Index (Source   : in Unbounded_String;
                         Pattern  : in String;
                         Going    : in Direction := Forward;
                         Mapping  : in Maps.Character_Mapping_Function)
            return Natural;

41       function Index (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership := Inside;
                         Going  : in Direction  := Forward) return Natural;

42       function Index_Non_Blank (Source : in Unbounded_String;
                                   Going  : in Direction := Forward)
            return Natural;

43       function Count (Source   : in Unbounded_String;
                         Pattern  : in String;
                         Mapping  : in Maps.Character_Mapping
                                      := Maps.Identity)
            return Natural;

44       function Count (Source   : in Unbounded_String;
                         Pattern  : in String;
                         Mapping  : in Maps.Character_Mapping_Function)
            return Natural;

45       function Count (Source   : in Unbounded_String;
                         Set      : in Maps.Character_Set)
            return Natural;

46       procedure Find_Token (Source : in Unbounded_String;
                               Set    : in Maps.Character_Set;
                               Test   : in Membership;
                               First  : out Positive;
                               Last   : out Natural);

47    -- String translation subprograms

48       function Translate (Source  : in Unbounded_String;
                             Mapping : in Maps.Character_Mapping)
            return Unbounded_String;

49       procedure Translate (Source  : in out Unbounded_String;
                              Mapping : in Maps.Character_Mapping);

50       function Translate (Source  : in Unbounded_String;
                             Mapping : in Maps.Character_Mapping_Function)
            return Unbounded_String;

51       procedure Translate (Source  : in out Unbounded_String;
                              Mapping : in Maps.Character_Mapping_Function);

52    -- String transformation subprograms

53       function Replace_Slice (Source   : in Unbounded_String;
                                 Low      : in Positive;
                                 High     : in Natural;
                                 By       : in String)
            return Unbounded_String;

54       procedure Replace_Slice (Source   : in out Unbounded_String;
                                  Low      : in Positive;
                                  High     : in Natural;
                                  By       : in String);

55       function Insert (Source   : in Unbounded_String;
                          Before   : in Positive;
                          New_Item : in String)
            return Unbounded_String;

56       procedure Insert (Source   : in out Unbounded_String;
                           Before   : in Positive;
                           New_Item : in String);

57       function Overwrite (Source    : in Unbounded_String;
                             Position  : in Positive;
                             New_Item  : in String)
            return Unbounded_String;

58       procedure Overwrite (Source    : in out Unbounded_String;
                              Position  : in Positive;
                              New_Item  : in String);

59       function Delete (Source  : in Unbounded_String;
                          From    : in Positive;
                          Through : in Natural)
            return Unbounded_String;

60       procedure Delete (Source  : in out Unbounded_String;
                           From    : in Positive;
                           Through : in Natural);

61       function Trim (Source : in Unbounded_String;
                        Side   : in Trim_End)
            return Unbounded_String;

62       procedure Trim (Source : in out Unbounded_String;
                         Side   : in Trim_End);

63       function Trim (Source : in Unbounded_String;
                        Left   : in Maps.Character_Set;
                        Right  : in Maps.Character_Set)
            return Unbounded_String;

64       procedure Trim (Source : in out Unbounded_String;
                         Left   : in Maps.Character_Set;
                         Right  : in Maps.Character_Set);

65       function Head (Source : in Unbounded_String;
                        Count  : in Natural;
                        Pad    : in Character := Space)
            return Unbounded_String;

66       procedure Head (Source : in out Unbounded_String;
                         Count  : in Natural;
                         Pad    : in Character := Space);

67       function Tail (Source : in Unbounded_String;
                        Count  : in Natural;
                        Pad    : in Character := Space)
            return Unbounded_String;

68       procedure Tail (Source : in out Unbounded_String;
                         Count  : in Natural;
                         Pad    : in Character := Space);

69       function "*" (Left  : in Natural;
                       Right : in Character)
            return Unbounded_String;

70       function "*" (Left  : in Natural;
                       Right : in String)
            return Unbounded_String;

71       function "*" (Left  : in Natural;
                       Right : in Unbounded_String)
            return Unbounded_String;

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

73    Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to the
same value as Null_Unbounded_String.

74    The function Length returns the length of the String represented by
Source.

75    The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.

76    The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String that
represents an uninitialized String whose length is Length.

77    The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:

78    If S is a String, then To_String(To_Unbounded_String(S)) = S.

79    If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.

80    For each of the Append procedures, the resulting string represented by
the Source parameter is given by the concatenation of the original value of
Source and the value of New_Item.

81    Each of the "&" functions returns an Unbounded_String obtained by
concatenating the string or character given or represented by one of the
parameters, with the string or character given or represented by the other
parameter, and applying To_Unbounded_String to the concatenation result string.

82    The Element, Replace_Element, and Slice subprograms have the same effect
as the corresponding bounded-length string subprograms.

83    Each of the functions "=", "<", ">","<=", and ">=" returns the same
result as the corresponding String operation applied to the String values
given or represented by Left and Right.

84    Each of the search subprograms (Index, Index_Non_Blank, Count,
Find_Token) has the same effect as the corresponding subprogram in
Strings.Fixed applied to the string represented by the Unbounded_String
parameter.

85    The Translate function has an analogous effect to the corresponding
subprogram in Strings.Fixed. The translation is applied to the string
represented by the Unbounded_String parameter, and the result is converted
(via To_Unbounded_String) to an Unbounded_String.

86    Each of the transformation functions (Replace_Slice, Insert, Overwrite,
Delete), selector functions (Trim, Head, Tail), and constructor functions
("*") is likewise analogous to its corresponding subprogram in Strings.Fixed.
For each of the subprograms, the corresponding fixed-length string subprogram
is applied to the string represented by the Unbounded_String parameter, and
To_Unbounded_String is applied the result string.

87    For each of the procedures Translate, Replace_Slice, Insert, Overwrite,
Delete, Trim, Head, and Tail, the resulting string represented by the Source
parameter is given by the corresponding function for fixed-length strings
applied to the string represented by Source's original value.


                         Implementation Requirements

88    No storage associated with an Unbounded_String object shall be lost upon
assignment or scope exit.


A.4.6 String-Handling Sets and Mappings


1     The language-defined package Strings.Maps.Constants declares
Character_Set and Character_Mapping constants corresponding to classification
and conversion functions in package Characters.Handling.


                              Static Semantics

2     The library package Strings.Maps.Constants has the following declaration:

3     package Ada.Strings.Maps.Constants is
         pragma Preelaborate(Constants);

4        Control_Set           : constant Character_Set;
         Graphic_Set           : constant Character_Set;
         Letter_Set            : constant Character_Set;
         Lower_Set             : constant Character_Set;
         Upper_Set             : constant Character_Set;
         Basic_Set             : constant Character_Set;
         Decimal_Digit_Set     : constant Character_Set;
         Hexadecimal_Digit_Set : constant Character_Set;
         Alphanumeric_Set      : constant Character_Set;
         Special_Set           : constant Character_Set;
         ISO_646_Set           : constant Character_Set;

5        Lower_Case_Map        : constant Character_Mapping;
           --Maps to lower case for letters, else identity
         Upper_Case_Map        : constant Character_Mapping;
           --Maps to upper case for letters, else identity
         Basic_Map             : constant Character_Mapping;
           --Maps to basic letter for letters, else identity

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

7     Each of these constants represents a correspondingly named set of
characters or character mapping in Characters.Handling (see A.3.2).


A.4.7 Wide_String Handling


1     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. They provide the
same string-handling operations as the corresponding packages for strings of
Character elements.


                              Static Semantics

2     The package Strings.Wide_Maps has the following declaration.

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

4        -- Representation for a set of Wide_Character values:
         type Wide_Character_Set is private;

5        Null_Set : constant Wide_Character_Set;

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

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

8        function To_Set    (Ranges : in Wide_Character_Ranges)
            return Wide_Character_Set;

9        function To_Set    (Span   : in Wide_Character_Range)
            return Wide_Character_Set;

10       function To_Ranges (Set    : in Wide_Character_Set)
            return Wide_Character_Ranges;

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

12       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;

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

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

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

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

17       function To_Set (Sequence  : in Wide_Character_Sequence)
            return Wide_Character_Set;

18       function To_Set (Singleton : in Wide_Character)
            return Wide_Character_Set;

19       function To_Sequence (Set  : in Wide_Character_Set)
            return Wide_Character_Sequence;

20       -- Representation for a Wide_Character to Wide_Character mapping:
         type Wide_Character_Mapping is private;

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

22       Identity : constant Wide_Character_Mapping;

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

24       function To_Domain (Map : in Wide_Character_Mapping)
            return Wide_Character_Sequence;

25       function To_Range  (Map : in Wide_Character_Mapping)
            return Wide_Character_Sequence;

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

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

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

29    For each of the packages Strings.Fixed, Strings.Bounded,
Strings.Unbounded, and Strings.Maps.Constants the corresponding wide string
package has the same contents except that

30    Wide_Space replaces Space

31    Wide_Character replaces Character

32    Wide_String replaces String

33    Wide_Character_Set replaces Character_Set

34    Wide_Character_Mapping replaces Character_Mapping

35    Wide_Character_Mapping_Function replaces Character_Mapping_Function

36    Wide_Maps replaces Maps

37    Bounded_Wide_String replaces Bounded_String

38    Null_Bounded_Wide_String replaces Null_Bounded_String

39    To_Bounded_Wide_String replaces To_Bounded_String

40    To_Wide_String replaces To_String

41    Unbounded_Wide_String replaces Unbounded_String

42    Null_Unbounded_Wide_String replaces Null_Unbounded_String

43    Wide_String_Access replaces String_Access

44    To_Unbounded_Wide_String replaces To_Unbounded_String

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

46    Character_Set : constant Wide_Maps.Wide_Character_Set;
      --Contains each Wide_Character value WC such that Characters.Is_Character(WC) is True

      NOTES

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

48    13  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.


A.5 The Numerics Packages


1     The library package Numerics is the parent of several child units that
provide facilities for mathematical computation. One child, the generic
package Generic_Elementary_Functions, is defined in A.5.1, together with
nongeneric equivalents; two others, the package Float_Random and the generic
package Discrete_Random, are defined in A.5.2. Additional (optional) children
are defined in Annex G, ``Numerics''.


                              Static Semantics

2/1   This paragraph was deleted.

3     package Ada.Numerics is
         pragma Pure(Numerics);
         Argument_Error : exception;
         Pi : constant :=
                3.14159_26535_89793_23846_26433_83279_50288_41971_69399_37511;
         e  : constant :=
                2.71828_18284_59045_23536_02874_71352_66249_77572_47093_69996;
      end Ada.Numerics;

4     The Argument_Error exception is raised by a subprogram in a child unit
of Numerics to signal that one or more of the actual subprogram parameters are
outside the domain of the corresponding mathematical function.


                         Implementation Permissions

5     The implementation may specify the values of Pi and e to a larger number
of significant digits.


A.5.1 Elementary Functions


1     Implementation-defined approximations to the mathematical functions
known as the ``elementary functions'' are provided by the subprograms in
Numerics.Generic_Elementary_Functions. Nongeneric equivalents of this generic
package for each of the predefined floating point types are also provided as
children of Numerics.


                              Static Semantics

2     The generic library package Numerics.Generic_Elementary_Functions has
the following declaration:

3     generic
         type Float_Type is digits <>;
      
      package Ada.Numerics.Generic_Elementary_Functions is
         pragma Pure(Generic_Elementary_Functions);

4        function Sqrt
          (X           : Float_Type'Base) return Float_Type'Base;
         function Log
           (X           : Float_Type'Base) return Float_Type'Base;
         function Log
           (X, Base     : Float_Type'Base) return Float_Type'Base;
         function Exp
           (X           : Float_Type'Base) return Float_Type'Base;
         function "**"    (Left, Right : Float_Type'Base) return Float_Type'Base;

5        function Sin
           (X           : Float_Type'Base) return Float_Type'Base;
         function Sin
           (X, Cycle    : Float_Type'Base) return Float_Type'Base;
         function Cos
           (X           : Float_Type'Base) return Float_Type'Base;
         function Cos
           (X, Cycle    : Float_Type'Base) return Float_Type'Base;
         function Tan
           (X           : Float_Type'Base) return Float_Type'Base;
         function Tan
           (X, Cycle    : Float_Type'Base) return Float_Type'Base;
         function Cot
           (X           : Float_Type'Base) return Float_Type'Base;
         function Cot
           (X, Cycle    : Float_Type'Base) return Float_Type'Base;

6        function Arcsin
        (X           : Float_Type'Base) return Float_Type'Base;
         function Arcsin
        (X, Cycle    : Float_Type'Base) return Float_Type'Base;
         function Arccos
        (X           : Float_Type'Base) return Float_Type'Base;
         function Arccos
        (X, Cycle    : Float_Type'Base) return Float_Type'Base;
         function Arctan  (Y           : Float_Type'Base;
                           X           : Float_Type'Base := 1.0)
                                                          return Float_Type'Base;
         function Arctan  (Y           : Float_Type'Base;
                           X           : Float_Type'Base := 1.0;
                           Cycle       : Float_Type'Base) return Float_Type'Base;
         function Arccot  (X           : Float_Type'Base;
                           Y           : Float_Type'Base := 1.0)
                                                          return Float_Type'Base;
         function Arccot  (X           : Float_Type'Base;
                           Y           : Float_Type'Base := 1.0;
                           Cycle       : Float_Type'Base) return Float_Type'Base;

7        function Sinh
          (X           : Float_Type'Base) return Float_Type'Base;
         function Cosh
          (X           : Float_Type'Base) return Float_Type'Base;
         function Tanh
          (X           : Float_Type'Base) return Float_Type'Base;
         function Coth
          (X           : Float_Type'Base) return Float_Type'Base;
         function Arcsinh
       (X           : Float_Type'Base) return Float_Type'Base;
         function Arccosh
       (X           : Float_Type'Base) return Float_Type'Base;
         function Arctanh
       (X           : Float_Type'Base) return Float_Type'Base;
         function Arccoth
       (X           : Float_Type'Base) return Float_Type'Base;

8     end Ada.Numerics.Generic_Elementary_Functions;

9/1   The library package Numerics.Elementary_Functions is declared pure and
defines the same subprograms as Numerics.Generic_Elementary_Functions, except
that the predefined type Float is systematically substituted for
Float_Type'Base throughout. Nongeneric equivalents of Numerics.Generic_-
Elementary_Functions for each of the other predefined floating point types are
defined similarly, with the names Numerics.Short_Elementary_Functions,
Numerics.Long_Elementary_Functions, etc.

10    The functions have their usual mathematical meanings. When the Base
parameter is specified, the Log function computes the logarithm to the given
base; otherwise, it computes the natural logarithm. When the Cycle parameter
is specified, the parameter X of the forward trigonometric functions (Sin,
Cos, Tan, and Cot) and the results of the inverse trigonometric functions
(Arcsin, Arccos, Arctan, and Arccot) are measured in units such that a full
cycle of revolution has the given value; otherwise, they are measured in
radians.

11    The computed results of the mathematically multivalued functions are
rendered single-valued by the following conventions, which are meant to imply
the principal branch:

12    The results of the Sqrt and Arccosh functions and that of the
      exponentiation operator are nonnegative.

13    The result of the Arcsin function is in the quadrant containing the
      point (1.0, x), where x is the value of the parameter X. This quadrant
      is I or IV; thus, the range of the Arcsin function is approximately
      -PI/2.0 to PI/2.0 (-Cycle/4.0 to Cycle/4.0, if the parameter Cycle is
      specified).

14    The result of the Arccos function is in the quadrant containing the
      point (x, 1.0), where x is the value of the parameter X. This quadrant
      is I or II; thus, the Arccos function ranges from 0.0 to approximately
      PI (Cycle/2.0, if the parameter Cycle is specified).

15    The results of the Arctan and Arccot functions are in the quadrant
      containing the point (x, y), where x and y are the values of the
      parameters X and Y, respectively. This may be any quadrant (I through
      IV) when the parameter X (resp., Y) of Arctan (resp., Arccot) is
      specified, but it is restricted to quadrants I and IV (resp., I and II)
      when that parameter is omitted. Thus, the range when that parameter is
      specified is approximately -PI to PI (-Cycle/2.0 to Cycle/2.0, if the
      parameter Cycle is specified); when omitted, the range of Arctan (resp.,
      Arccot) is that of Arcsin (resp., Arccos), as given above. When the
      point (x, y) lies on the negative x-axis, the result approximates

        16    PI (resp., -PI) when the sign of the parameter Y is positive
              (resp., negative), if Float_Type'Signed_Zeros is True;

        17    PI, if Float_Type'Signed_Zeros is False.

18    (In the case of the inverse trigonometric functions, in which a result
lying on or near one of the axes may not be exactly representable, the
approximation inherent in computing the result may place it in an adjacent
quadrant, close to but on the wrong side of the axis.)


                              Dynamic Semantics

19    The exception Numerics.Argument_Error is raised, signaling a parameter
value outside the domain of the corresponding mathematical function, in the
following cases:

20    by any forward or inverse trigonometric function with specified cycle,
      when the value of the parameter Cycle is zero or negative;

21    by the Log function with specified base, when the value of the parameter
      Base is zero, one, or negative;

22    by the Sqrt and Log functions, when the value of the parameter X is
      negative;

23    by the exponentiation operator, when the value of the left operand is
      negative or when both operands have the value zero;

24    by the Arcsin, Arccos, and Arctanh functions, when the absolute value of
      the parameter X exceeds one;

25    by the Arctan and Arccot functions, when the parameters X and Y both
      have the value zero;

26    by the Arccosh function, when the value of the parameter X is less than
      one; and

27    by the Arccoth function, when the absolute value of the parameter X is
      less than one.

28    The exception Constraint_Error is raised, signaling a pole of the
mathematical function (analogous to dividing by zero), in the following cases,
provided that Float_Type'Machine_Overflows is True:

29    by the Log, Cot, and Coth functions, when the value of the parameter X
      is zero;

30    by the exponentiation operator, when the value of the left operand is
      zero and the value of the exponent is negative;

31    by the Tan function with specified cycle, when the value of the
      parameter X is an odd multiple of the quarter cycle;

32    by the Cot function with specified cycle, when the value of the
      parameter X is zero or a multiple of the half cycle; and

33    by the Arctanh and Arccoth functions, when the absolute value of the
      parameter X is one.

34    Constraint_Error can also be raised when a finite result overflows (see
G.2.4); this may occur for parameter values sufficiently near poles, and, in
the case of some of the functions, for parameter values with sufficiently
large magnitudes. When Float_Type'Machine_Overflows is False, the result at
poles is unspecified.

35    When one parameter of a function with multiple parameters represents a
pole and another is outside the function's domain, the latter takes precedence
(i.e., Numerics.Argument_Error is raised).


                         Implementation Requirements

36    In the implementation of Numerics.Generic_Elementary_Functions, the
range of intermediate values allowed during the calculation of a final result
shall not be affected by any range constraint of the subtype Float_Type.

37    In the following cases, evaluation of an elementary function shall yield
the prescribed result, provided that the preceding rules do not call for an
exception to be raised:

38    When the parameter X has the value zero, the Sqrt, Sin, Arcsin, Tan,
      Sinh, Arcsinh, Tanh, and Arctanh functions yield a result of zero, and
      the Exp, Cos, and Cosh functions yield a result of one.

39    When the parameter X has the value one, the Sqrt function yields a
      result of one, and the Log, Arccos, and Arccosh functions yield a result
      of zero.

40    When the parameter Y has the value zero and the parameter X has a
      positive value, the Arctan and Arccot functions yield a result of zero.

41    The results of the Sin, Cos, Tan, and Cot functions with specified cycle
      are exact when the mathematical result is zero; those of the first two
      are also exact when the mathematical result is  1.0.

42    Exponentiation by a zero exponent yields the value one. Exponentiation
      by a unit exponent yields the value of the left operand. Exponentiation
      of the value one yields the value one. Exponentiation of the value zero
      yields the value zero.

43    Other accuracy requirements for the elementary functions, which apply
only in implementations conforming to the Numerics Annex, and then only in the
``strict'' mode defined there (see G.2), are given in G.2.4.

44    When Float_Type'Signed_Zeros is True, the sign of a zero result shall be
as follows:

45    A prescribed zero result delivered at the origin by one of the odd
      functions (Sin, Arcsin, Sinh, Arcsinh, Tan, Arctan or Arccot as a
      function of Y when X is fixed and positive, Tanh, and Arctanh) has the
      sign of the parameter X (Y, in the case of Arctan or Arccot).

46    A prescribed zero result delivered by one of the odd functions away from
      the origin, or by some other elementary function, has an
      implementation-defined sign.

47    A zero result that is not a prescribed result (i.e., one that results
      from rounding or underflow) has the correct mathematical sign.


                         Implementation Permissions

48    The nongeneric equivalent packages may, but need not, be actual
instantiations of the generic package for the appropriate predefined type.


A.5.2 Random Number Generation


1     Facilities for the generation of pseudo-random floating point numbers
are provided in the package Numerics.Float_Random; the generic package
Numerics.Discrete_Random provides similar facilities for the generation of
pseudo-random integers and pseudo-random values of enumeration types. For
brevity, pseudo-random values of any of these types are called random numbers.

2     Some of the facilities provided are basic to all applications of random
numbers. These include a limited private type each of whose objects serves as
the generator of a (possibly distinct) sequence of random numbers; a function
to obtain the ``next'' random number from a given sequence of random numbers
(that is, from its generator); and subprograms to initialize or reinitialize a
given generator to a time-dependent state or a state denoted by a single
integer.

3     Other facilities are provided specifically for advanced applications.
These include subprograms to save and restore the state of a given generator;
a private type whose objects can be used to hold the saved state of a
generator; and subprograms to obtain a string representation of a given
generator state, or, given such a string representation, the corresponding
state.


                              Static Semantics

4     The library package Numerics.Float_Random has the following declaration:

5     package Ada.Numerics.Float_Random is

6        -- Basic facilities

7        type Generator is limited private;

8        subtype Uniformly_Distributed is Float range 0.0 .. 1.0;
         function Random (Gen : Generator) return Uniformly_Distributed;

9        procedure Reset (Gen       : in Generator;
                          Initiator : in Integer);
         procedure Reset (Gen       : in Generator);

10       -- Advanced facilities

11       type State is private;

12       procedure Save  (Gen        : in  Generator;
                          To_State   : out State);
         procedure Reset (Gen        : in  Generator;
                          From_State : in  State);

13       Max_Image_Width : constant := implementation-defined integer value;

14       function Image (Of_State    : State)  return String;
         function Value (Coded_State : String) return State;

15    private
         ... -- not specified by the language
      end Ada.Numerics.Float_Random;

16    The generic library package Numerics.Discrete_Random has the following
declaration:

17    
      generic
         type Result_Subtype is (<>);
      package Ada.Numerics.Discrete_Random is

18       -- Basic facilities

19       type Generator is limited private;

20       function Random (Gen : Generator) return Result_Subtype;

21       procedure Reset (Gen       : in Generator;
                          Initiator : in Integer);
         procedure Reset (Gen       : in Generator);

22       -- Advanced facilities

23       type State is private;

24       procedure Save  (Gen        : in  Generator;
                          To_State   : out State);
         procedure Reset (Gen        : in  Generator;
                          From_State : in  State);

25       Max_Image_Width : constant := implementation-defined integer value;

26       function Image (Of_State    : State)  return String;
         function Value (Coded_State : String) return State;

27    private
         ... -- not specified by the language
      end Ada.Numerics.Discrete_Random;

28    An object of the limited private type Generator is associated with a
sequence of random numbers. Each generator has a hidden (internal) state,
which the operations on generators use to determine the position in the
associated sequence. All generators are implicitly initialized to an
unspecified state that does not vary from one program execution to another;
they may also be explicitly initialized, or reinitialized, to a time-dependent
state, to a previously saved state, or to a state uniquely denoted by an
integer value.

29    An object of the private type State can be used to hold the internal
state of a generator. Such objects are only needed if the application is
designed to save and restore generator states or to examine or manufacture
them.

30    The operations on generators affect the state and therefore the future
values of the associated sequence. The semantics of the operations on
generators and states are defined below.

31    function Random (Gen : Generator) return Uniformly_Distributed;
      function Random (Gen : Generator) return Result_Subtype;

    32    Obtains the ``next'' random number from the given generator,
          relative to its current state, according to an
          implementation-defined algorithm. The result of the function in
          Numerics.Float_Random is delivered as a value of the subtype
          Uniformly_Distributed, which is a subtype of the predefined type
          Float having a range of 0.0 .. 1.0. The result of the function in an
          instantiation of Numerics.Discrete_Random is delivered as a value of
          the generic formal subtype Result_Subtype.

33    procedure Reset (Gen       : in Generator;
                       Initiator : in Integer);
      procedure Reset (Gen       : in Generator);

    34    Sets the state of the specified generator to one that is an
          unspecified function of the value of the parameter Initiator (or to
          a time-dependent state, if only a generator parameter is specified).
          The latter form of the procedure is known as the time-dependent
          Reset procedure.

35    procedure Save  (Gen        : in  Generator;
                       To_State   : out State);
      procedure Reset (Gen        : in  Generator;
                       From_State : in  State);

    36    Save obtains the current state of a generator. Reset gives a
          generator the specified state. A generator that is reset to a state
          previously obtained by invoking Save is restored to the state it had
          when Save was invoked.

37    function Image (Of_State    : State)  return String;
      function Value (Coded_State : String) return State;

    38    Image provides a representation of a state coded (in an
          implementation-defined way) as a string whose length is bounded by
          the value of Max_Image_Width. Value is the inverse of Image:
          Value(Image(S)) = S for each state S that can be obtained from a
          generator by invoking Save.


                              Dynamic Semantics

39    Instantiation of Numerics.Discrete_Random with a subtype having a null
range raises Constraint_Error.

40/1  This paragraph was deleted.


                          Bounded (Run-Time) Errors

40.1/1 It is a bounded error to invoke Value with a string that is not the
image of any generator state. If the error is detected, Constraint_Error or
Program_Error is raised. Otherwise, a call to Reset with the resulting state
will produce a generator such that calls to Random with this generator will
produce a sequence of values of the appropriate subtype, but which might not
be random in character. That is, the sequence of values might not fulfill the
implementation requirements of this subclause.


                         Implementation Requirements

41    A sufficiently long sequence of random numbers obtained by successive
calls to Random is approximately uniformly distributed over the range of the
result subtype.

42    The Random function in an instantiation of Numerics.Discrete_Random is
guaranteed to yield each value in its result subtype in a finite number of
calls, provided that the number of such values does not exceed 2 (15).

43    Other performance requirements for the random number generator, which
apply only in implementations conforming to the Numerics Annex, and then only
in the ``strict'' mode defined there (see G.2), are given in G.2.5.


                         Documentation Requirements

44    No one algorithm for random number generation is best for all
applications. To enable the user to determine the suitability of the random
number generators for the intended application, the implementation shall
describe the algorithm used and shall give its period, if known exactly, or a
lower bound on the period, if the exact period is unknown. Periods that are so
long that the periodicity is unobservable in practice can be described in such
terms, without giving a numerical bound.

45    The implementation also shall document the minimum time interval between
calls to the time-dependent Reset procedure that are guaranteed to initiate
different sequences, and it shall document the nature of the strings that
Value will accept without raising Constraint_Error.


                            Implementation Advice

46    Any storage associated with an object of type Generator should be
reclaimed on exit from the scope of the object.

47    If the generator period is sufficiently long in relation to the number
of distinct initiator values, then each possible value of Initiator passed to
Reset should initiate a sequence of random numbers that does not, in a
practical sense, overlap the sequence initiated by any other value. If this is
not possible, then the mapping between initiator values and generator states
should be a rapidly varying function of the initiator value.

      NOTES

48    14  If two or more tasks are to share the same generator, then the tasks
      have to synchronize their access to the generator as for any shared
      variable (see 9.10).

49    15  Within a given implementation, a repeatable random number sequence
      can be obtained by relying on the implicit initialization of generators
      or by explicitly initializing a generator with a repeatable initiator
      value. Different sequences of random numbers can be obtained from a
      given generator in different program executions by explicitly
      initializing the generator to a time-dependent state.

50    16  A given implementation of the Random function in
      Numerics.Float_Random may or may not be capable of delivering the values
      0.0 or 1.0. Portable applications should assume that these values, or
      values sufficiently close to them to behave indistinguishably from them,
      can occur. If a sequence of random integers from some fixed range is
      needed, the application should use the Random function in an appropriate
      instantiation of Numerics.Discrete_Random, rather than transforming the
      result of the Random function in Numerics.Float_Random. However, some
      applications with unusual requirements, such as for a sequence of random
      integers each drawn from a different range, will find it more convenient
      to transform the result of the floating point Random function. For M
      >= 1, the expression

51       Integer(Float(M) * Random(G)) mod M

52    transforms the result of Random(G) to an integer uniformly distributed
      over the range 0 .. M-1; it is valid even if Random delivers 0.0 or 1.0.
      Each value of the result range is possible, provided that M is not too
      large. Exponentially distributed (floating point) random numbers with
      mean and standard deviation 1.0 can be obtained by the transformation

53       -Log(Random(G) + Float'Model_Small))

54    where Log comes from Numerics.Elementary_Functions (see A.5.1); in this
      expression, the addition of Float'Model_Small avoids the exception that
      would be raised were Log to be given the value zero, without affecting
      the result (in most implementations) when Random returns a nonzero
      value.


                                  Examples

55    Example of a program that plays a simulated dice game:

56    with Ada.Numerics.Discrete_Random;
      procedure Dice_Game is
         subtype Die is Integer range 1 .. 6;
         subtype Dice is Integer range 2*Die'First .. 2*Die'Last;
         package Random_Die is new Ada.Numerics.Discrete_Random (Die);
         use Random_Die;
         G : Generator;
         D : Dice;
      begin
         Reset (G);  -- Start the generator in a unique state in each run
         loop
            -- Roll a pair of dice; sum and process the results
            D := Random(G) + Random(G);
            ...
         end loop;
      end Dice_Game;

57    Example of a program that simulates coin tosses:

58    with Ada.Numerics.Discrete_Random;
      procedure Flip_A_Coin is
         type Coin is (Heads, Tails);
         package Random_Coin is new Ada.Numerics.Discrete_Random (Coin);
         use Random_Coin;
         G : Generator;
      begin
         Reset (G);  -- Start the generator in a unique state in each run
         loop
            -- Toss a coin and process the result
            case Random(G) is
                when Heads =>
                   ...
                when Tails =>
                   ...
            end case;
         ...
         end loop;
      end Flip_A_Coin;

59    Example of a parallel simulation of a physical system, with a separate
generator of event probabilities in each task:

60    with Ada.Numerics.Float_Random;
      procedure Parallel_Simulation is
         use Ada.Numerics.Float_Random;
         task type Worker is
            entry Initialize_Generator (Initiator : in Integer);
            ...
         end Worker;
         W : array (1 .. 10) of Worker;
         task body Worker is
            G : Generator;
            Probability_Of_Event : Uniformly_Distributed;
         begin
            accept Initialize_Generator (Initiator : in Integer) do
               Reset (G, Initiator);
            end Initialize_Generator;
            loop
               ...
               Probability_Of_Event := Random(G);
               ...
            end loop;
         end Worker;
      begin
         -- Initialize the generators in the Worker tasks to different states
         for I in W'Range loop
            W(I).Initialize_Generator (I);
         end loop;
         ... -- Wait for the Worker tasks to terminate
      end Parallel_Simulation;

      NOTES

61    17  Notes on the last example: Although each Worker task initializes its
      generator to a different state, those states will be the same in every
      execution of the program. The generator states can be initialized
      uniquely in each program execution by instantiating
      Ada.Numerics.Discrete_Random for the type Integer in the main procedure,
      resetting the generator obtained from that instance to a time-dependent
      state, and then using random integers obtained from that generator to
      initialize the generators in each Worker task.


A.5.3 Attributes of Floating Point Types



                              Static Semantics

1     The following representation-oriented attributes are defined for every
subtype S of a floating point type T.

2     S'Machine_Radix
              Yields the radix of the hardware representation of the type T.
              The value of this attribute is of the type universal_integer.

3     The values of other representation-oriented attributes of a floating
point subtype, and of the ``primitive function'' attributes of a floating
point subtype described later, are defined in terms of a particular
representation of nonzero values called the canonical form. The canonical form
(for the type T) is the form
     mantissa  T'Machine_Radix(exponent)
where

4     mantissa is a fraction in the number base T'Machine_Radix, the first
      digit of which is nonzero, and

5     exponent is an integer.

6     S'Machine_Mantissa
              Yields the largest value of p such that every value expressible
              in the canonical form (for the type T), having a p-digit
              mantissa and an exponent between T'Machine_Emin and
              T'Machine_Emax, is a machine number (see 3.5.7) of the type T.
              This attribute yields a value of the type universal_integer.

7     S'Machine_Emin
              Yields the smallest (most negative) value of exponent such that
              every value expressible in the canonical form (for the type T),
              having a mantissa of T'Machine_Mantissa digits, is a machine
              number (see 3.5.7) of the type T. This attribute yields a value
              of the type universal_integer.

8     S'Machine_Emax
              Yields the largest (most positive) value of exponent such that
              every value expressible in the canonical form (for the type T),
              having a mantissa of T'Machine_Mantissa digits, is a machine
              number (see 3.5.7) of the type T. This attribute yields a value
              of the type universal_integer.

9     S'Denorm
              Yields the value True if every value expressible in the form
                   mantissa  T'Machine_Radix(T'Machine_Emin)
              where mantissa is a nonzero T'Machine_Mantissa-digit fraction in
              the number base T'Machine_Radix, the first digit of which is
              zero, is a machine number (see 3.5.7) of the type T; yields the
              value False otherwise. The value of this attribute is of the
              predefined type Boolean.

10    The values described by the formula in the definition of S'Denorm are
called denormalized numbers. A nonzero machine number that is not a
denormalized number is a normalized number. A normalized number x of a given
type T is said to be represented in canonical form when it is expressed in the
canonical form (for the type T) with a mantissa having T'Machine_Mantissa
digits; the resulting form is the canonical-form representation of x.

11    S'Machine_Rounds
              Yields the value True if rounding is performed on inexact
              results of every predefined operation that yields a result of
              the type T; yields the value False otherwise. The value of this
              attribute is of the predefined type Boolean.

12    S'Machine_Overflows
              Yields the value True if overflow and divide-by-zero are
              detected and reported by raising Constraint_Error for every
              predefined operation that yields a result of the type T; yields
              the value False otherwise. The value of this attribute is of the
              predefined type Boolean.

13    S'Signed_Zeros
              Yields the value True if the hardware representation for the
              type T has the capability of representing both positively and
              negatively signed zeros, these being generated and used by the
              predefined operations of the type T as specified in IEC
              559:1989; yields the value False otherwise. The value of this
              attribute is of the predefined type Boolean.

14    For every value x of a floating point type T, the normalized exponent of
x is defined as follows:

15    the normalized exponent of zero is (by convention) zero;

16    for nonzero x, the normalized exponent of x is the unique integer k such
      that T'Machine_Radix(k-1) <= |x| < T'Machine_Radix(k).

17    The following primitive function attributes are defined for any subtype
S of a floating point type T.

18    S'Exponent
              S'Exponent denotes a function with the following specification:

            19    function S'Exponent (X : T)
                    return universal_integer

        20    The function yields the normalized exponent of X.

21    S'Fraction
              S'Fraction denotes a function with the following specification:

            22    function S'Fraction (X : T)
                    return T

        23    The function yields the value X  T'Machine_Radix(-k), where k
              is the normalized exponent of X. A zero result, which can only
              occur when X is zero, has the sign of X.

24    S'Compose
              S'Compose denotes a function with the following specification:

            25    function S'Compose (Fraction : T;
                                      Exponent : universal_integer)
                    return T

        26    Let v be the value Fraction  T'Machine_Radix(Exponent-k), where
              k is the normalized exponent of Fraction. If v is a machine
              number of the type T, or if |v| >= T'Model_Small, the function
              yields v; otherwise, it yields either one of the machine numbers
              of the type T adjacent to v. Constraint_Error is optionally
              raised if v is outside the base range of S. A zero result has
              the sign of Fraction when S'Signed_Zeros is True.

27    S'Scaling
              S'Scaling denotes a function with the following specification:

            28    function S'Scaling (X : T;
                                      Adjustment : universal_integer)
                    return T

        29    Let v be the value X  T'Machine_Radix(Adjustment). If v is a
              machine number of the type T, or if |v| >= T'Model_Small, the
              function yields v; otherwise, it yields either one of the
              machine numbers of the type T adjacent to v. Constraint_Error is
              optionally raised if v is outside the base range of S. A zero
              result has the sign of X when S'Signed_Zeros is True.

30    S'Floor S'Floor denotes a function with the following specification:

            31    function S'Floor (X : T)
                    return T

        32    The function yields the value Floor(X), i.e., the largest (most
              positive) integral value less than or equal to X. When X is
              zero, the result has the sign of X; a zero result otherwise has
              a positive sign.

33    S'Ceiling
              S'Ceiling denotes a function with the following specification:

            34    function S'Ceiling (X : T)
                    return T

        35    The function yields the value Ceiling(X), i.e., the smallest
              (most negative) integral value greater than or equal to X. When
              X is zero, the result has the sign of X; a zero result otherwise
              has a negative sign when S'Signed_Zeros is True.

36    S'Rounding
              S'Rounding denotes a function with the following specification:

            37    function S'Rounding (X : T)
                    return T

        38    The function yields the integral value nearest to X, rounding
              away from zero if X lies exactly halfway between two integers. A
              zero result has the sign of X when S'Signed_Zeros is True.

39    S'Unbiased_Rounding
              S'Unbiased_Rounding denotes a function with the following
              specification:

            40    function S'Unbiased_Rounding (X : T)
                    return T

        41    The function yields the integral value nearest to X, rounding
              toward the even integer if X lies exactly halfway between two
              integers. A zero result has the sign of X when S'Signed_Zeros is
              True.

42    S'Truncation
              S'Truncation denotes a function with the following
              specification:

            43    function S'Truncation (X : T)
                    return T

        44    The function yields the value Ceiling(X) when X is negative, and
              Floor(X) otherwise. A zero result has the sign of X when
              S'Signed_Zeros is True.

45    S'Remainder
              S'Remainder denotes a function with the following specification:

            46    function S'Remainder (X, Y : T)
                    return T

        47    For nonzero Y, let v be the value X - n  Y, where n is the
              integer nearest to the exact value of X/Y; if |n - X/Y|   =  
              1/2, then n is chosen to be even. If v is a machine number of
              the type T, the function yields v; otherwise, it yields zero.
              Constraint_Error is raised if Y is zero. A zero result has the
              sign of X when S'Signed_Zeros is True.

48    S'Adjacent
              S'Adjacent denotes a function with the following specification:

            49    function S'Adjacent (X, Towards : T)
                    return T

        50    If Towards   =   X, the function yields X; otherwise, it yields
              the machine number of the type T adjacent to X in the direction
              of Towards, if that machine number exists. If the result would
              be outside the base range of S, Constraint_Error is raised. When
              T'Signed_Zeros is True, a zero result has the sign of X. When
              Towards is zero, its sign has no bearing on the result.

51    S'Copy_Sign
              S'Copy_Sign denotes a function with the following specification:

            52    function S'Copy_Sign (Value, Sign : T)
                    return T

        53    If the value of Value is nonzero, the function yields a result
              whose magnitude is that of Value and whose sign is that of Sign;
              otherwise, it yields the value zero. Constraint_Error is
              optionally raised if the result is outside the base range of S.
              A zero result has the sign of Sign when S'Signed_Zeros is True.

54    S'Leading_Part
              S'Leading_Part denotes a function with the following
              specification:

            55    function S'Leading_Part (X : T;
                                           Radix_Digits : universal_integer)
                    return T

        56    Let v be the value T'Machine_Radix(k-Radix_Digits), where k is
              the normalized exponent of X. The function yields the value

            57    Floor(X/v)  v, when X is nonnegative and Radix_Digits is
                  positive;

            58    Ceiling(X/v)  v, when X is negative and Radix_Digits is
                  positive.

        59    Constraint_Error is raised when Radix_Digits is zero or
              negative. A zero result, which can only occur when X is zero,
              has the sign of X.

60    S'Machine
              S'Machine denotes a function with the following specification:

            61    function S'Machine (X : T)
                    return T

        62    If X is a machine number of the type T, the function yields X;
              otherwise, it yields the value obtained by rounding or
              truncating X to either one of the adjacent machine numbers of
              the type T. Constraint_Error is raised if rounding or truncating
              X to the precision of the machine numbers results in a value
              outside the base range of S. A zero result has the sign of X
              when S'Signed_Zeros is True.

63    The following model-oriented attributes are defined for any subtype S of
a floating point type T.

64    S'Model_Mantissa
              If the Numerics Annex is not supported, this attribute yields an
              implementation defined value that is greater than or equal to
              Ceiling(d  log(10) / log(T'Machine_Radix)) + 1, where d is the
              requested decimal precision of T, and less than or equal to the
              value of T'Machine_Mantissa. See G.2.2 for further requirements
              that apply to implementations supporting the Numerics Annex. The
              value of this attribute is of the type universal_integer.

65    S'Model_Emin
              If the Numerics Annex is not supported, this attribute yields an
              implementation defined value that is greater than or equal to
              the value of T'Machine_Emin. See G.2.2 for further requirements
              that apply to implementations supporting the Numerics Annex. The
              value of this attribute is of the type universal_integer.

66    S'Model_Epsilon
              Yields the value T'Machine_Radix(1 - T'Model_Mantissa). The
              value of this attribute is of the type universal_real.

67    S'Model_Small
              Yields the value T'Machine_Radix(T'Model_Emin - 1). The value of
              this attribute is of the type universal_real.

68    S'Model S'Model denotes a function with the following specification:

            69    function S'Model (X : T)
                    return T

        70    If the Numerics Annex is not supported, the meaning of this
              attribute is implementation defined; see G.2.2 for the
              definition that applies to implementations supporting the
              Numerics Annex.

71    S'Safe_First
              Yields the lower bound of the safe range (see 3.5.7) of the type
              T. If the Numerics Annex is not supported, the value of this
              attribute is implementation defined; see G.2.2 for the
              definition that applies to implementations supporting the
              Numerics Annex. The value of this attribute is of the type
              universal_real.

72    S'Safe_Last
              Yields the upper bound of the safe range (see 3.5.7) of the type
              T. If the Numerics Annex is not supported, the value of this
              attribute is implementation defined; see G.2.2 for the
              definition that applies to implementations supporting the
              Numerics Annex. The value of this attribute is of the type
              universal_real.


A.5.4 Attributes of Fixed Point Types



                              Static Semantics

1     The following representation-oriented attributes are defined for every
subtype S of a fixed point type T.

2     S'Machine_Radix
              Yields the radix of the hardware representation of the type T.
              The value of this attribute is of the type universal_integer.

3     S'Machine_Rounds
              Yields the value True if rounding is performed on inexact
              results of every predefined operation that yields a result of
              the type T; yields the value False otherwise. The value of this
              attribute is of the predefined type Boolean.

4     S'Machine_Overflows
              Yields the value True if overflow and divide-by-zero are
              detected and reported by raising Constraint_Error for every
              predefined operation that yields a result of the type T; yields
              the value False otherwise. The value of this attribute is of the
              predefined type Boolean.


A.6 Input-Output


1     Input-output is provided through language-defined packages, each of
which is a child of the root package Ada. The generic packages Sequential_IO
and Direct_IO define input-output operations applicable to files containing
elements of a given type. The generic package Storage_IO supports reading from
and writing to an in-memory buffer. Additional operations for text
input-output are supplied in the packages Text_IO and Wide_Text_IO.
Heterogeneous input-output is provided through the child packages Streams.-
Stream_IO and Text_IO.Text_Streams (see also 13.13). The package IO_Exceptions
defines the exceptions needed by the predefined input-output packages.


A.7 External Files and File Objects



                              Static Semantics

1     Values input from the external environment of the program, or output to
the external environment, are considered to occupy external files. An external
file can be anything external to the program that can produce a value to be
read or receive a value to be written. An external file is identified by a
string (the name). A second string (the form) gives further system-dependent
characteristics that may be associated with the file, such as the physical
organization or access rights. The conventions governing the interpretation of
such strings shall be documented.

2     Input and output operations are expressed as operations on objects of
some file type, rather than directly in terms of the external files. In the
remainder of this section, the term file is always used to refer to a file
object; the term external file is used otherwise.

3     Input-output for sequential files of values of a single element type is
defined by means of the generic package Sequential_IO. In order to define
sequential input-output for a given element type, an instantiation of this
generic unit, with the given type as actual parameter, has to be declared. The
resulting package contains the declaration of a file type (called File_Type)
for files of such elements, as well as the operations applicable to these
files, such as the Open, Read, and Write procedures.

4     Input-output for direct access files is likewise defined by a generic
package called Direct_IO. Input-output in human-readable form is defined by
the (nongeneric) packages Text_IO for Character and String data, and
Wide_Text_IO for Wide_Character and Wide_String data. Input-output for files
containing streams of elements representing values of possibly different types
is defined by means of the (nongeneric) package Streams.Stream_IO.

5     Before input or output operations can be performed on a file, the file
first has to be associated with an external file. While such an association is
in effect, the file is said to be open, and otherwise the file is said to be
closed.

6     The language does not define what happens to external files after the
completion of the main program and all the library tasks (in particular, if
corresponding files have not been closed). The effect of input-output for
access types is unspecified.

7     An open file has a current mode, which is a value of one of the
following enumeration types:

8     type File_Mode is (In_File, Inout_File, Out_File);  --  for Direct_IO

    9     These values correspond respectively to the cases where only
          reading, both reading and writing, or only writing are to be
          performed.

10    type File_Mode is (In_File, Out_File, Append_File);
      --  for Sequential_IO, Text_IO, Wide_Text_IO, and Stream_IO

    11    These values correspond respectively to the cases where only
          reading, only writing, or only appending are to be performed.

    12    The mode of a file can be changed.

13    Several file management operations are common to Sequential_IO,
Direct_IO, Text_IO, and Wide_Text_IO. These operations are described in
subclause A.8.2 for sequential and direct files. Any additional effects
concerning text input-output are described in subclause A.10.2.

14    The exceptions that can be propagated by the execution of an
input-output subprogram are defined in the package IO_Exceptions; the
situations in which they can be propagated are described following the
description of the subprogram (and in clause A.13). The exceptions
Storage_Error and Program_Error may be propagated. (Program_Error can only be
propagated due to errors made by the caller of the subprogram.) Finally,
exceptions can be propagated in certain implementation-defined situations.

      NOTES

15    18  Each instantiation of the generic packages Sequential_IO and
      Direct_IO declares a different type File_Type. In the case of Text_IO,
      Wide_Text_IO, and Streams.Stream_IO, the corresponding type File_Type is
      unique.

16    19  A bidirectional device can often be modeled as two sequential files
      associated with the device, one of mode In_File, and one of mode
      Out_File. An implementation may restrict the number of files that may be
      associated with a given external file.




A.8 Sequential and Direct Files



                              Static Semantics

1     Two kinds of access to external files are defined in this subclause:
sequential access and direct access. The corresponding file types and the
associated operations are provided by the generic packages Sequential_IO and
Direct_IO. A file object to be used for sequential access is called a
sequential file, and one to be used for direct access is called a direct file.
Access to stream files is described in A.12.1.

2     For sequential access, the file is viewed as a sequence of values that
are transferred in the order of their appearance (as produced by the program
or by the external environment). When the file is opened with mode In_File or
Out_File, transfer starts respectively from or to the beginning of the file.
When the file is opened with mode Append_File, transfer to the file starts
after the last element of the file.

3     For direct access, the file is viewed as a set of elements occupying
consecutive positions in linear order; a value can be transferred to or from
an element of the file at any selected position. The position of an element is
specified by its index, which is a number, greater than zero, of the
implementation-defined integer type Count. The first element, if any, has
index one; the index of the last element, if any, is called the current size;
the current size is zero if there are no elements. The current size is a
property of the external file.

4     An open direct file has a current index, which is the index that will be
used by the next read or write operation. When a direct file is opened, the
current index is set to one. The current index of a direct file is a property
of a file object, not of an external file.


A.8.1 The Generic Package Sequential_IO



                              Static Semantics

1     The generic library package Sequential_IO has the following declaration:

2     with Ada.IO_Exceptions;
      generic
         type Element_Type(<>) is private;
      package Ada.Sequential_IO is

3        type File_Type is limited private;

4        type File_Mode is (In_File, Out_File, Append_File);

5        -- File management

6        procedure Create(File : in out File_Type;
                          Mode : in File_Mode := Out_File;
                          Name : in String := "";
                          Form : in String := "");

7        procedure Open  (File : in out File_Type;
                          Mode : in File_Mode;
                          Name : in String;
                          Form : in String := "");

8        procedure Close (File : in out File_Type);
         procedure Delete(File : in out File_Type);
         procedure Reset (File : in out File_Type; Mode : in File_Mode);
         procedure Reset (File : in out File_Type);

9        function Mode   (File : in File_Type) return File_Mode;
         function Name   (File : in File_Type) return String;
         function Form   (File : in File_Type) return String;

10       function Is_Open(File : in File_Type) return Boolean;

11       -- Input and output operations

12       procedure Read  (File : in File_Type; Item : out Element_Type);
         procedure Write (File : in File_Type; Item : in Element_Type);

13       function End_Of_File(File : in File_Type) return Boolean;

14       -- Exceptions

15       Status_Error : exception renames IO_Exceptions.Status_Error;
         Mode_Error   : exception renames IO_Exceptions.Mode_Error;
         Name_Error   : exception renames IO_Exceptions.Name_Error;
         Use_Error    : exception renames IO_Exceptions.Use_Error;
         Device_Error : exception renames IO_Exceptions.Device_Error;
         End_Error    : exception renames IO_Exceptions.End_Error;
         Data_Error   : exception renames IO_Exceptions.Data_Error;

16    private
         ... -- not specified by the language
      end Ada.Sequential_IO;


A.8.2 File Management



                              Static Semantics

1     The procedures and functions described in this subclause provide for the
control of external files; their declarations are repeated in each of the
packages for sequential, direct, text, and stream input-output. For text
input-output, the procedures Create, Open, and Reset have additional effects
described in subclause A.10.2.

2     procedure Create(File : in out File_Type;
                       Mode : in File_Mode := default_mode;
                       Name : in String := "";
                       Form : in String := "");

    3     Establishes a new external file, with the given name and form, and
          associates this external file with the given file. The given file is
          left open. The current mode of the given file is set to the given
          access mode. The default access mode is the mode Out_File for
          sequential and text input-output; it is the mode Inout_File for
          direct input-output. For direct access, the size of the created file
          is implementation defined.

    4     A null string for Name specifies an external file that is not
          accessible after the completion of the main program (a temporary
          file). A null string for Form specifies the use of the default
          options of the implementation for the external file.

    5     The exception Status_Error is propagated if the given file is
          already open. The exception Name_Error is propagated if the string
          given as Name does not allow the identification of an external file.
          The exception Use_Error is propagated if, for the specified mode,
          the external environment does not support creation of an external
          file with the given name (in the absence of Name_Error) and form.

6     procedure Open(File : in out File_Type;
                     Mode : in File_Mode;
                     Name : in String;
                     Form : in String := "");

    7     Associates the given file with an existing external file having the
          given name and form, and sets the current mode of the given file to
          the given mode. The given file is left open.

    8     The exception Status_Error is propagated if the given file is
          already open. The exception Name_Error is propagated if the string
          given as Name does not allow the identification of an external file;
          in particular, this exception is propagated if no external file with
          the given name exists. The exception Use_Error is propagated if, for
          the specified mode, the external environment does not support
          opening for an external file with the given name (in the absence of
          Name_Error) and form.

9     procedure Close(File : in out File_Type);

    10    Severs the association between the given file and its associated
          external file. The given file is left closed. In addition, for
          sequential files, if the file being closed has mode Out_File or
          Append_File, then the last element written since the most recent
          open or reset is the last element that can be read from the file. If
          no elements have been written and the file mode is Out_File, then
          the closed file is empty. If no elements have been written and the
          file mode is Append_File, then the closed file is unchanged.

    11    The exception Status_Error is propagated if the given file is not
          open.

12    procedure Delete(File : in out File_Type);

    13    Deletes the external file associated with the given file. The given
          file is closed, and the external file ceases to exist.

    14    The exception Status_Error is propagated if the given file is not
          open. The exception Use_Error is propagated if deletion of the
          external file is not supported by the external environment.

15    procedure Reset(File : in out File_Type; Mode : in File_Mode);
      procedure Reset(File : in out File_Type);

    16    Resets the given file so that reading from its elements can be
          restarted from the beginning of the file (for modes In_File and
          Inout_File), and so that writing to its elements can be restarted at
          the beginning of the file (for modes Out_File and Inout_File) or
          after the last element of the file (for mode Append_File). In
          particular, for direct access this means that the current index is
          set to one. If a Mode parameter is supplied, the current mode of the
          given file is set to the given mode. In addition, for sequential
          files, if the given file has mode Out_File or Append_File when Reset
          is called, the last element written since the most recent open or
          reset is the last element that can be read from the file. If no
          elements have been written and the file mode is Out_File, the reset
          file is empty. If no elements have been written and the file mode is
          Append_File, then the reset file is unchanged.

    17    The exception Status_Error is propagated if the file is not open.
          The exception Use_Error is propagated if the external environment
          does not support resetting for the external file and, also, if the
          external environment does not support resetting to the specified
          mode for the external file.

18    function Mode(File : in File_Type) return File_Mode;

    19    Returns the current mode of the given file.

    20    The exception Status_Error is propagated if the file is not open.

21    function Name(File : in File_Type) return String;

    22    Returns a string which uniquely identifies the external file
          currently associated with the given file (and may thus be used in an
          Open operation). If an external environment allows alternative
          specifications of the name (for example, abbreviations), the string
          returned by the function should correspond to a full specification
          of the name.

    23    The exception Status_Error is propagated if the given file is not
          open. The exception Use_Error is propagated if the associated
          external file is a temporary file that cannot be opened by any name.

24    function Form(File : in File_Type) return String;

    25    Returns the form string for the external file currently associated
          with the given file. If an external environment allows alternative
          specifications of the form (for example, abbreviations using default
          options), the string returned by the function should correspond to a
          full specification (that is, it should indicate explicitly all
          options selected, including default options).

    26    The exception Status_Error is propagated if the given file is not
          open.

27    function Is_Open(File : in File_Type) return Boolean;

    28    Returns True if the file is open (that is, if it is associated with
          an external file), otherwise returns False.


                         Implementation Permissions

29    An implementation may propagate Name_Error or Use_Error if an attempt is
made to use an I/O feature that cannot be supported by the implementation due
to limitations in the external environment. Any such restriction should be
documented.


A.8.3 Sequential Input-Output Operations



                              Static Semantics

1     The operations available for sequential input and output are described
in this subclause. The exception Status_Error is propagated if any of these
operations is attempted for a file that is not open.

2     procedure Read(File : in File_Type; Item : out Element_Type);

    3     Operates on a file of mode In_File. Reads an element from the given
          file, and returns the value of this element in the Item parameter.

    4     The exception Mode_Error is propagated if the mode is not In_File.
          The exception End_Error is propagated if no more elements can be
          read from the given file. The exception Data_Error can be propagated
          if the element read cannot be interpreted as a value of the subtype
          Element_Type (see A.13, ``Exceptions in Input-Output'').

5     procedure Write(File : in File_Type; Item : in Element_Type);

    6     Operates on a file of mode Out_File or Append_File. Writes the value
          of Item to the given file.

    7     The exception Mode_Error is propagated if the mode is not Out_File
          or Append_File. The exception Use_Error is propagated if the
          capacity of the external file is exceeded.

8     function End_Of_File(File : in File_Type) return Boolean;

    9     Operates on a file of mode In_File. Returns True if no more elements
          can be read from the given file; otherwise returns False.

    10    The exception Mode_Error is propagated if the mode is not In_File.


A.8.4 The Generic Package Direct_IO



                              Static Semantics

1     The generic library package Direct_IO has the following declaration:

2     with Ada.IO_Exceptions;
      generic
         type Element_Type is private;
      package Ada.Direct_IO is

3        type File_Type is limited private;

4        type File_Mode is (In_File, Inout_File, Out_File);
         type Count     is range 0 .. implementation-defined;
         subtype Positive_Count is Count range 1 .. Count'Last;

5        -- File management

6        procedure Create(File : in out File_Type;
                          Mode : in File_Mode := Inout_File;
                          Name : in String := "";
                          Form : in String := "");

7        procedure Open  (File : in out File_Type;
                          Mode : in File_Mode;
                          Name : in String;
                          Form : in String := "");

8        procedure Close (File : in out File_Type);
         procedure Delete(File : in out File_Type);
         procedure Reset (File : in out File_Type; Mode : in File_Mode);
         procedure Reset (File : in out File_Type);

9        function Mode   (File : in File_Type) return File_Mode;
         function Name   (File : in File_Type) return String;
         function Form   (File : in File_Type) return String;

10       function Is_Open(File : in File_Type) return Boolean;

11       -- Input and output operations

12       procedure Read (File : in File_Type; Item : out Element_Type;
                                              From : in Positive_Count);
         procedure Read (File : in File_Type; Item : out Element_Type);

13       procedure Write(File : in File_Type; Item : in  Element_Type;
                                              To   : in Positive_Count);
         procedure Write(File : in File_Type; Item : in Element_Type);

14       procedure Set_Index(File : in File_Type; To : in Positive_Count);

15       function Index(File : in File_Type) return Positive_Count;
         function Size (File : in File_Type) return Count;

16       function End_Of_File(File : in File_Type) return Boolean;

17       -- Exceptions

18       Status_Error : exception renames IO_Exceptions.Status_Error;
         Mode_Error   : exception renames IO_Exceptions.Mode_Error;
         Name_Error   : exception renames IO_Exceptions.Name_Error;
         Use_Error    : exception renames IO_Exceptions.Use_Error;
         Device_Error : exception renames IO_Exceptions.Device_Error;
         End_Error    : exception renames IO_Exceptions.End_Error;
         Data_Error   : exception renames IO_Exceptions.Data_Error;

19    private
         ... -- not specified by the language
      end Ada.Direct_IO;


A.8.5 Direct Input-Output Operations



                              Static Semantics

1     The operations available for direct input and output are described in
this subclause. The exception Status_Error is propagated if any of these
operations is attempted for a file that is not open.

2     procedure Read(File : in File_Type; Item : out Element_Type;
                                          From : in  Positive_Count);
      procedure Read(File : in File_Type; Item : out Element_Type);

    3     Operates on a file of mode In_File or Inout_File. In the case of the
          first form, sets the current index of the given file to the index
          value given by the parameter From. Then (for both forms) returns, in
          the parameter Item, the value of the element whose position in the
          given file is specified by the current index of the file; finally,
          increases the current index by one.

    4     The exception Mode_Error is propagated if the mode of the given file
          is Out_File. The exception End_Error is propagated if the index to
          be used exceeds the size of the external file. The exception
          Data_Error can be propagated if the element read cannot be
          interpreted as a value of the subtype Element_Type (see A.13).

5     procedure Write(File : in File_Type; Item : in Element_Type;
                                           To   : in Positive_Count);
      procedure Write(File : in File_Type; Item : in Element_Type);

    6     Operates on a file of mode Inout_File or Out_File. In the case of
          the first form, sets the index of the given file to the index value
          given by the parameter To. Then (for both forms) gives the value of
          the parameter Item to the element whose position in the given file
          is specified by the current index of the file; finally, increases
          the current index by one.

    7     The exception Mode_Error is propagated if the mode of the given file
          is In_File. The exception Use_Error is propagated if the capacity of
          the external file is exceeded.

8     procedure Set_Index(File : in File_Type; To : in Positive_Count);

    9     Operates on a file of any mode. Sets the current index of the given
          file to the given index value (which may exceed the current size of
          the file).

10    function Index(File : in File_Type) return Positive_Count;

    11    Operates on a file of any mode. Returns the current index of the
          given file.

12    function Size(File : in File_Type) return Count;

    13    Operates on a file of any mode. Returns the current size of the
          external file that is associated with the given file.

14    function End_Of_File(File : in File_Type) return Boolean;

    15    Operates on a file of mode In_File or Inout_File. Returns True if
          the current index exceeds the size of the external file; otherwise
          returns False.

    16    The exception Mode_Error is propagated if the mode of the given file
          is Out_File.

      NOTES

17    20  Append_File mode is not supported for the generic package Direct_IO.


A.9 The Generic Package Storage_IO


1     The generic package Storage_IO provides for reading from and writing to
an in-memory buffer. This generic package supports the construction of
user-defined input-output packages.


                              Static Semantics

2     The generic library package Storage_IO has the following declaration:

3     with Ada.IO_Exceptions;
      with System.Storage_Elements;
      generic
         type Element_Type is private;
      package Ada.Storage_IO is
         pragma Preelaborate(Storage_IO);

4        Buffer_Size : constant System.Storage_Elements.Storage_Count :=
            implementation-defined;
         subtype Buffer_Type is
            System.Storage_Elements.Storage_Array(1..Buffer_Size);

5        -- Input and output operations

6        procedure Read (Buffer : in  Buffer_Type; Item : out Element_Type);

7        procedure Write(Buffer : out Buffer_Type; Item : in  Element_Type);

8        -- Exceptions

9        Data_Error   : exception renames IO_Exceptions.Data_Error;
      end Ada.Storage_IO;

10    In each instance, the constant Buffer_Size has a value that is the size
(in storage elements) of the buffer required to represent the content of an
object of subtype Element_Type, including any implicit levels of indirection
used by the implementation. The Read and Write procedures of Storage_IO
correspond to the Read and Write procedures of Direct_IO (see A.8.4), but with
the content of the Item parameter being read from or written into the
specified Buffer, rather than an external file.

      NOTES

11    21  A buffer used for Storage_IO holds only one element at a time; an
      external file used for Direct_IO holds a sequence of elements.


A.10 Text Input-Output



                              Static Semantics

1     This clause describes the package Text_IO, which provides facilities for
input and output in human-readable form. Each file is read or written
sequentially, as a sequence of characters grouped into lines, and as a
sequence of lines grouped into pages. The specification of the package is
given below in subclause A.10.1.

2     The facilities for file management given above, in subclauses A.8.2 and
A.8.3, are available for text input-output. In place of Read and Write,
however, there are procedures Get and Put that input values of suitable types
from text files, and output values to them. These values are provided to the
Put procedures, and returned by the Get procedures, in a parameter Item.
Several overloaded procedures of these names exist, for different types of
Item. These Get procedures analyze the input sequences of characters based on
lexical elements (see Section 2) and return the corresponding values; the Put
procedures output the given values as appropriate lexical elements. Procedures
Get and Put are also available that input and output individual characters
treated as character values rather than as lexical elements. Related to
character input are procedures to look ahead at the next character without
reading it, and to read a character ``immediately'' without waiting for an
end-of-line to signal availability.

3     In addition to the procedures Get and Put for numeric and enumeration
types of Item that operate on text files, analogous procedures are provided
that read from and write to a parameter of type String. These procedures
perform the same analysis and composition of character sequences as their
counterparts which have a file parameter.

4     For all Get and Put procedures that operate on text files, and for many
other subprograms, there are forms with and without a file parameter. Each
such Get procedure operates on an input file, and each such Put procedure
operates on an output file. If no file is specified, a default input file or a
default output file is used.

5     At the beginning of program execution the default input and output files
are the so-called standard input file and standard output file. These files
are open, have respectively the current modes In_File and Out_File, and are
associated with two implementation-defined external files. Procedures are
provided to change the current default input file and the current default
output file.

6     At the beginning of program execution a default file for
program-dependent error-related text output is the so-called standard error
file. This file is open, has the current mode Out_File, and is associated with
an implementation-defined external file. A procedure is provided to change the
current default error file.

7     From a logical point of view, a text file is a sequence of pages, a page
is a sequence of lines, and a line is a sequence of characters; the end of a
line is marked by a line terminator; the end of a page is marked by the
combination of a line terminator immediately followed by a page terminator;
and the end of a file is marked by the combination of a line terminator
immediately followed by a page terminator and then a file terminator.
Terminators are generated during output; either by calls of procedures
provided expressly for that purpose; or implicitly as part of other
operations, for example, when a bounded line length, a bounded page length, or
both, have been specified for a file.

8     The actual nature of terminators is not defined by the language and
hence depends on the implementation. Although terminators are recognized or
generated by certain of the procedures that follow, they are not necessarily
implemented as characters or as sequences of characters. Whether they are
characters (and if so which ones) in any particular implementation need not
concern a user who neither explicitly outputs nor explicitly inputs control
characters. The effect of input (Get) or output (Put) of control characters
(other than horizontal tabulation) is not specified by the language.

9     The characters of a line are numbered, starting from one; the number of
a character is called its column number. For a line terminator, a column
number is also defined: it is one more than the number of characters in the
line. The lines of a page, and the pages of a file, are similarly numbered.
The current column number is the column number of the next character or line
terminator to be transferred. The current line number is the number of the
current line. The current page number is the number of the current page. These
numbers are values of the subtype Positive_Count of the type Count (by
convention, the value zero of the type Count is used to indicate special
conditions).

10    type Count is range 0 .. implementation-defined;
      subtype Positive_Count is Count range 1 .. Count'Last;

11    For an output file or an append file, a maximum line length can be
specified and a maximum page length can be specified. If a value to be output
cannot fit on the current line, for a specified maximum line length, then a
new line is automatically started before the value is output; if, further,
this new line cannot fit on the current page, for a specified maximum page
length, then a new page is automatically started before the value is output.
Functions are provided to determine the maximum line length and the maximum
page length. When a file is opened with mode Out_File or Append_File, both
values are zero: by convention, this means that the line lengths and page
lengths are unbounded. (Consequently, output consists of a single line if the
subprograms for explicit control of line and page structure are not used.) The
constant Unbounded is provided for this purpose.


A.10.1 The Package Text_IO



                              Static Semantics

1     The library package Text_IO has the following declaration:

2     with Ada.IO_Exceptions;
      package Ada.Text_IO is

3        type File_Type is limited private;

4        type File_Mode is (In_File, Out_File, Append_File);

5        type Count is range 0 .. implementation-defined;
         subtype Positive_Count is Count range 1 .. Count'Last;
         Unbounded : constant Count := 0; -- line and page length

6        subtype Field       is Integer range 0 .. implementation-defined;
         subtype Number_Base is Integer range 2 .. 16;

7        type Type_Set is (Lower_Case, Upper_Case);

8        -- File Management

9        procedure Create (File : in out File_Type;
                           Mode : in File_Mode := Out_File;
                           Name : in String    := "";
                           Form : in String    := "");

10       procedure Open   (File : in out File_Type;
                           Mode : in File_Mode;
                           Name : in String;
                           Form : in String := "");

11       procedure Close  (File : in out File_Type);
         procedure Delete (File : in out File_Type);
         procedure Reset  (File : in out File_Type; Mode : in File_Mode);
         procedure Reset  (File : in out File_Type);

12       function  Mode   (File : in File_Type) return File_Mode;
         function  Name   (File : in File_Type) return String;
         function  Form   (File : in File_Type) return String;

13       function  Is_Open(File : in File_Type) return Boolean;

14       -- Control of default input and output files

15       procedure Set_Input (File : in File_Type);
         procedure Set_Output(File : in File_Type);
         procedure Set_Error (File : in File_Type);

16       function Standard_Input  return File_Type;
         function Standard_Output return File_Type;
         function Standard_Error  return File_Type;

17       function Current_Input   return File_Type;
         function Current_Output  return File_Type;
         function Current_Error   return File_Type;

18       type File_Access is access constant File_Type;

19       function Standard_Input  return File_Access;
         function Standard_Output return File_Access;
         function Standard_Error  return File_Access;

20       function Current_Input   return File_Access;
         function Current_Output  return File_Access;
         function Current_Error   return File_Access;

21/1  --Buffer control
         procedure Flush (File : in File_Type);
         procedure Flush;

22       -- Specification of line and page lengths

23       procedure Set_Line_Length(File : in File_Type; To : in Count);
         procedure Set_Line_Length(To   : in Count);

24       procedure Set_Page_Length(File : in File_Type; To : in Count);
         procedure Set_Page_Length(To   : in Count);

25       function  Line_Length(File : in File_Type) return Count;
         function  Line_Length return Count;

26       function  Page_Length(File : in File_Type) return Count;
         function  Page_Length return Count;

27       -- Column, Line, and Page Control

28       procedure New_Line   (File    : in File_Type;
                               Spacing : in Positive_Count := 1);
         procedure New_Line   (Spacing : in Positive_Count := 1);

29       procedure Skip_Line  (File    : in File_Type;
                               Spacing : in Positive_Count := 1);
         procedure Skip_Line  (Spacing : in Positive_Count := 1);

30       function  End_Of_Line(File : in File_Type) return Boolean;
         function  End_Of_Line return Boolean;

31       procedure New_Page   (File : in File_Type);
         procedure New_Page;

32       procedure Skip_Page  (File : in File_Type);
         procedure Skip_Page;

33       function  End_Of_Page(File : in File_Type) return Boolean;
         function  End_Of_Page return Boolean;

34       function  End_Of_File(File : in File_Type) return Boolean;
         function  End_Of_File return Boolean;

35       procedure Set_Col (File : in File_Type; To : in Positive_Count);
         procedure Set_Col (To   : in Positive_Count);

36       procedure Set_Line(File : in File_Type; To : in Positive_Count);
         procedure Set_Line(To   : in Positive_Count);

37       function Col (File : in File_Type) return Positive_Count;
         function Col  return Positive_Count;

38       function Line(File : in File_Type) return Positive_Count;
         function Line return Positive_Count;

39       function Page(File : in File_Type) return Positive_Count;
         function Page return Positive_Count;

40       -- Character Input-Output

41       procedure Get(File : in  File_Type; Item : out Character);
         procedure Get(Item : out Character);

42       procedure Put(File : in  File_Type; Item : in Character);
         procedure Put(Item : in  Character);

43       procedure Look_Ahead (File        : in  File_Type;
                               Item        : out Character;
                               End_Of_Line : out Boolean);
         procedure Look_Ahead (Item        : out Character;
                               End_Of_Line : out Boolean);

44       procedure Get_Immediate(File      : in  File_Type;
                                 Item      : out Character);
         procedure Get_Immediate(Item      : out Character);

45       procedure Get_Immediate(File      : in  File_Type;
                                 Item      : out Character;
                                 Available : out Boolean);
         procedure Get_Immediate(Item      : out Character;
                                 Available : out Boolean);

46       -- String Input-Output

47       procedure Get(File : in  File_Type; Item : out String);
         procedure Get(Item : out String);

48       procedure Put(File : in  File_Type; Item : in String);
         procedure Put(Item : in  String);

49       procedure Get_Line(File : in  File_Type;
                            Item : out String;
                            Last : out Natural);
         procedure Get_Line(Item : out String; Last : out Natural);

50       procedure Put_Line(File : in  File_Type; Item : in String);
         procedure Put_Line(Item : in  String);

51    -- Generic packages for Input-Output of Integer Types

52       generic
            type Num is range <>;
         package Integer_IO is

53          Default_Width : Field := Num'Width;
            Default_Base  : Number_Base := 10;

54          procedure Get(File  : in  File_Type;
                          Item  : out Num;
                          Width : in Field := 0);
            procedure Get(Item  : out Num;
                          Width : in  Field := 0);

55          procedure Put(File  : in File_Type;
                          Item  : in Num;
                          Width : in Field := Default_Width;
                          Base  : in Number_Base := Default_Base);
            procedure Put(Item  : in Num;
                          Width : in Field := Default_Width;
                          Base  : in Number_Base := Default_Base);
            procedure Get(From : in  String;
                          Item : out Num;
                          Last : out Positive);
            procedure Put(To   : out String;
                          Item : in Num;
                          Base : in Number_Base := Default_Base);

56       end Integer_IO;

57       generic
            type Num is mod <>;
         package Modular_IO is

58          Default_Width : Field := Num'Width;
            Default_Base  : Number_Base := 10;

59          procedure Get(File  : in  File_Type;
                          Item  : out Num;
                          Width : in Field := 0);
            procedure Get(Item  : out Num;
                          Width : in  Field := 0);

60          procedure Put(File  : in File_Type;
                          Item  : in Num;
                          Width : in Field := Default_Width;
                          Base  : in Number_Base := Default_Base);
            procedure Put(Item  : in Num;
                          Width : in Field := Default_Width;
                          Base  : in Number_Base := Default_Base);
            procedure Get(From : in  String;
                          Item : out Num;
                          Last : out Positive);
            procedure Put(To   : out String;
                          Item : in Num;
                          Base : in Number_Base := Default_Base);

61       end Modular_IO;

62       -- Generic packages for Input-Output of Real Types

63       generic
            type Num is digits <>;
         package Float_IO is

64          Default_Fore : Field := 2;
            Default_Aft  : Field := Num'Digits-1;
            Default_Exp  : Field := 3;

65          procedure Get(File  : in  File_Type;
                          Item  : out Num;
                          Width : in  Field := 0);
            procedure Get(Item  : out Num;
                          Width : in  Field := 0);

66          procedure Put(File : in File_Type;
                          Item : in Num;
                          Fore : in Field := Default_Fore;
                          Aft  : in Field := Default_Aft;
                          Exp  : in Field := Default_Exp);
            procedure Put(Item : in Num;
                          Fore : in Field := Default_Fore;
                          Aft  : in Field := Default_Aft;
                          Exp  : in Field := Default_Exp);

67          procedure Get(From : in String;
                          Item : out Num;
                          Last : out Positive);
            procedure Put(To   : out String;
                          Item : in Num;
                          Aft  : in Field := Default_Aft;
                          Exp  : in Field := Default_Exp);
         end Float_IO;

68       generic
            type Num is delta <>;
         package Fixed_IO is

69          Default_Fore : Field := Num'Fore;
            Default_Aft  : Field := Num'Aft;
            Default_Exp  : Field := 0;

70          procedure Get(File  : in  File_Type;
                          Item  : out Num;
                          Width : in  Field := 0);
            procedure Get(Item  : out Num;
                          Width : in  Field := 0);

71          procedure Put(File : in File_Type;
                          Item : in Num;
                          Fore : in Field := Default_Fore;
                          Aft  : in Field := Default_Aft;
                          Exp  : in Field := Default_Exp);
            procedure Put(Item : in Num;
                          Fore : in Field := Default_Fore;
                          Aft  : in Field := Default_Aft;
                          Exp  : in Field := Default_Exp);

72          procedure Get(From : in  String;
                          Item : out Num;
                          Last : out Positive);
            procedure Put(To   : out String;
                          Item : in Num;
                          Aft  : in Field := Default_Aft;
                          Exp  : in Field := Default_Exp);
         end Fixed_IO;

73       generic
            type Num is delta <> digits <>;
         package Decimal_IO is

74          Default_Fore : Field := Num'Fore;
            Default_Aft  : Field := Num'Aft;
            Default_Exp  : Field := 0;

75          procedure Get(File  : in  File_Type;
                          Item  : out Num;
                          Width : in  Field := 0);
            procedure Get(Item  : out Num;
                          Width : in  Field := 0);

76          procedure Put(File : in File_Type;
                          Item : in Num;
                          Fore : in Field := Default_Fore;
                          Aft  : in Field := Default_Aft;
                          Exp  : in Field := Default_Exp);
            procedure Put(Item : in Num;
                          Fore : in Field := Default_Fore;
                          Aft  : in Field := Default_Aft;
                          Exp  : in Field := Default_Exp);

77          procedure Get(From : in  String;
                          Item : out Num;
                          Last : out Positive);
            procedure Put(To   : out String;
                          Item : in Num;
                          Aft  : in Field := Default_Aft;
                          Exp  : in Field := Default_Exp);
         end Decimal_IO;

78       -- Generic package for Input-Output of Enumeration Types

79       generic
            type Enum is (<>);
         package Enumeration_IO is

80          Default_Width   : Field := 0;
            Default_Setting : Type_Set := Upper_Case;

81          procedure Get(File : in  File_Type;
                          Item : out Enum);
            procedure Get(Item : out Enum);

82          procedure Put(File  : in File_Type;
                          Item  : in Enum;
                          Width : in Field    := Default_Width;
                          Set   : in Type_Set := Default_Setting);
            procedure Put(Item  : in Enum;
                          Width : in Field    := Default_Width;
                          Set   : in Type_Set := Default_Setting);

83          procedure Get(From : in  String;
                          Item : out Enum;
                          Last : out Positive);
            procedure Put(To   : out String;
                          Item : in  Enum;
                          Set  : in  Type_Set := Default_Setting);
         end Enumeration_IO;

84    -- Exceptions

85       Status_Error : exception renames IO_Exceptions.Status_Error;
         Mode_Error   : exception renames IO_Exceptions.Mode_Error;
         Name_Error   : exception renames IO_Exceptions.Name_Error;
         Use_Error    : exception renames IO_Exceptions.Use_Error;
         Device_Error : exception renames IO_Exceptions.Device_Error;
         End_Error    : exception renames IO_Exceptions.End_Error;
         Data_Error   : exception renames IO_Exceptions.Data_Error;
         Layout_Error : exception renames IO_Exceptions.Layout_Error;
      private
         ... -- not specified by the language
      end Ada.Text_IO;


A.10.2 Text File Management



                              Static Semantics

1     The only allowed file modes for text files are the modes In_File,
Out_File, and Append_File. The subprograms given in subclause A.8.2 for the
control of external files, and the function End_Of_File given in subclause
A.8.3 for sequential input-output, are also available for text files. There is
also a version of End_Of_File that refers to the current default input file.
For text files, the procedures have the following additional effects:

2     For the procedures Create and Open: After a file with mode Out_File or
      Append_File is opened, the page length and line length are unbounded
      (both have the conventional value zero). After a file (of any mode) is
      opened, the current column, current line, and current page numbers are
      set to one. If the mode is Append_File, it is implementation defined
      whether a page terminator will separate preexisting text in the file
      from the new text to be written.

3     For the procedure Close: If the file has the current mode Out_File or
      Append_File, has the effect of calling New_Page, unless the current page
      is already terminated; then outputs a file terminator.

4     For the procedure Reset: If the file has the current mode Out_File or
      Append_File, has the effect of calling New_Page, unless the current page
      is already terminated; then outputs a file terminator. The current
      column, line, and page numbers are set to one, and the line and page
      lengths to Unbounded. If the new mode is Append_File, it is
      implementation defined whether a page terminator will separate
      preexisting text in the file from the new text to be written.

5     The exception Mode_Error is propagated by the procedure Reset upon an
attempt to change the mode of a file that is the current default input file,
the current default output file, or the current default error file.

      NOTES

6     22  An implementation can define the Form parameter of Create and Open
      to control effects including the following:

    7     the interpretation of line and column numbers for an interactive
          file, and

    8     the interpretation of text formats in a file created by a foreign
          program.


A.10.3 Default Input, Output, and Error Files



                              Static Semantics

1     The following subprograms provide for the control of the particular
default files that are used when a file parameter is omitted from a Get, Put,
or other operation of text input-output described below, or when
application-dependent error-related text is to be output.

2     procedure Set_Input(File : in File_Type);

    3     Operates on a file of mode In_File. Sets the current default input
          file to File.

    4     The exception Status_Error is propagated if the given file is not
          open. The exception Mode_Error is propagated if the mode of the
          given file is not In_File.

5     procedure Set_Output(File : in File_Type);
      procedure Set_Error (File : in File_Type);

    6     Each operates on a file of mode Out_File or Append_File. Set_Output
          sets the current default output file to File. Set_Error sets the
          current default error file to File. The exception Status_Error is
          propagated if the given file is not open. The exception Mode_Error
          is propagated if the mode of the given file is not Out_File or
          Append_File.

7     function Standard_Input return File_Type;
      function Standard_Input return File_Access;

    8     Returns the standard input file (see A.10), or an access value
          designating the standard input file, respectively.

9     function Standard_Output return File_Type;
      function Standard_Output return File_Access;

    10    Returns the standard output file (see A.10) or an access value
          designating the standard output file, respectively.

11    function Standard_Error return File_Type;
      function Standard_Error return File_Access;

    12/1  Returns the standard error file (see A.10), or an access value
          designating the standard error file, respectively.

13    The Form strings implicitly associated with the opening of
Standard_Input, Standard_Output, and Standard_Error at the start of program
execution are implementation defined.

14    function Current_Input return File_Type;
      function Current_Input return File_Access;

    15    Returns the current default input file, or an access value
          designating the current default input file, respectively.

16    function Current_Output return File_Type;
      function Current_Output return File_Access;

    17    Returns the current default output file, or an access value
          designating the current default output file, respectively.

18    function Current_Error return File_Type;
      function Current_Error return File_Access;

    19    Returns the current default error file, or an access value
          designating the current default error file, respectively.

20/1  procedure Flush (File : in File_Type);
      procedure Flush;

    21    The effect of Flush is the same as the corresponding subprogram in
          Streams.Stream_IO (see A.12.1). If File is not explicitly specified,
          Current_Output is used.


                             Erroneous Execution

22/1  The execution of a program is erroneous if it invokes an operation on a
current default input, default output, or default error file, and if the
corresponding file object is closed or no longer exists.

23/1  This paragraph was deleted.

      NOTES

24    23  The standard input, standard output, and standard error files cannot
      be opened, closed, reset, or deleted, because the parameter File of the
      corresponding procedures has the mode in out.

25    24  The standard input, standard output, and standard error files are
      different file objects, but not necessarily different external files.


A.10.4 Specification of Line and Page Lengths



                              Static Semantics

1     The subprograms described in this subclause are concerned with the line
and page structure of a file of mode Out_File or Append_File. They operate
either on the file given as the first parameter, or, in the absence of such a
file parameter, on the current default output file. They provide for output of
text with a specified maximum line length or page length. In these cases, line
and page terminators are output implicitly and automatically when needed. When
line and page lengths are unbounded (that is, when they have the conventional
value zero), as in the case of a newly opened file, new lines and new pages
are only started when explicitly called for.

2     In all cases, the exception Status_Error is propagated if the file to be
used is not open; the exception Mode_Error is propagated if the mode of the
file is not Out_File or Append_File.

3     procedure Set_Line_Length(File : in File_Type; To : in Count);
      procedure Set_Line_Length(To   : in Count);

    4     Sets the maximum line length of the specified output or append file
          to the number of characters specified by To. The value zero for To
          specifies an unbounded line length.

    5     The exception Use_Error is propagated if the specified line length
          is inappropriate for the associated external file.

6     procedure Set_Page_Length(File : in File_Type; To : in Count);
      procedure Set_Page_Length(To   : in Count);

    7     Sets the maximum page length of the specified output or append file
          to the number of lines specified by To. The value zero for To
          specifies an unbounded page length.

    8     The exception Use_Error is propagated if the specified page length
          is inappropriate for the associated external file.

9     function Line_Length(File : in File_Type) return Count;
      function Line_Length return Count;

    10    Returns the maximum line length currently set for the specified
          output or append file, or zero if the line length is unbounded.

11    function Page_Length(File : in File_Type) return Count;
      function Page_Length return Count;

    12    Returns the maximum page length currently set for the specified
          output or append file, or zero if the page length is unbounded.


A.10.5 Operations on Columns, Lines, and Pages



                              Static Semantics

1     The subprograms described in this subclause provide for explicit control
of line and page structure; they operate either on the file given as the first
parameter, or, in the absence of such a file parameter, on the appropriate
(input or output) current default file. The exception Status_Error is
propagated by any of these subprograms if the file to be used is not open.

2     procedure New_Line(File : in File_Type; Spacing : in Positive_Count := 1);
      procedure New_Line(Spacing : in Positive_Count := 1);

    3     Operates on a file of mode Out_File or Append_File.

    4     For a Spacing of one: Outputs a line terminator and sets the current
          column number to one. Then increments the current line number by
          one, except in the case that the current line number is already
          greater than or equal to the maximum page length, for a bounded page
          length; in that case a page terminator is output, the current page
          number is incremented by one, and the current line number is set to
          one.

    5     For a Spacing greater than one, the above actions are performed
          Spacing times.

    6     The exception Mode_Error is propagated if the mode is not Out_File
          or Append_File.

7     procedure Skip_Line(File  : in File_Type; Spacing : in Positive_Count := 1);
      procedure Skip_Line(Spacing : in Positive_Count := 1);

    8     Operates on a file of mode In_File.

    9     For a Spacing of one: Reads and discards all characters until a line
          terminator has been read, and then sets the current column number to
          one. If the line terminator is not immediately followed by a page
          terminator, the current line number is incremented by one.
          Otherwise, if the line terminator is immediately followed by a page
          terminator, then the page terminator is skipped, the current page
          number is incremented by one, and the current line number is set to
          one.

    10    For a Spacing greater than one, the above actions are performed
          Spacing times.

    11    The exception Mode_Error is propagated if the mode is not In_File.
          The exception End_Error is propagated if an attempt is made to read
          a file terminator.

12    function End_Of_Line(File : in File_Type) return Boolean;
      function End_Of_Line return Boolean;

    13    Operates on a file of mode In_File. Returns True if a line
          terminator or a file terminator is next; otherwise returns False.

    14    The exception Mode_Error is propagated if the mode is not In_File.

15    procedure New_Page(File : in File_Type);
      procedure New_Page;

    16    Operates on a file of mode Out_File or Append_File. Outputs a line
          terminator if the current line is not terminated, or if the current
          page is empty (that is, if the current column and line numbers are
          both equal to one). Then outputs a page terminator, which terminates
          the current page. Adds one to the current page number and sets the
          current column and line numbers to one.

    17    The exception Mode_Error is propagated if the mode is not Out_File
          or Append_File.

18    procedure Skip_Page(File : in File_Type);
      procedure Skip_Page;

    19    Operates on a file of mode In_File. Reads and discards all
          characters and line terminators until a page terminator has been
          read. Then adds one to the current page number, and sets the current
          column and line numbers to one.

    20    The exception Mode_Error is propagated if the mode is not In_File.
          The exception End_Error is propagated if an attempt is made to read
          a file terminator.

21    function End_Of_Page(File : in File_Type) return Boolean;
      function End_Of_Page return Boolean;

    22    Operates on a file of mode In_File. Returns True if the combination
          of a line terminator and a page terminator is next, or if a file
          terminator is next; otherwise returns False.

    23    The exception Mode_Error is propagated if the mode is not In_File.

24    function End_Of_File(File : in File_Type) return Boolean;
      function End_Of_File return Boolean;

    25    Operates on a file of mode In_File. Returns True if a file
          terminator is next, or if the combination of a line, a page, and a
          file terminator is next; otherwise returns False.

    26    The exception Mode_Error is propagated if the mode is not In_File.

27    The following subprograms provide for the control of the current
position of reading or writing in a file. In all cases, the default file is
the current output file.

28    procedure Set_Col(File : in File_Type; To : in Positive_Count);
      procedure Set_Col(To   : in Positive_Count);

    29    If the file mode is Out_File or Append_File:

        30    If the value specified by To is greater than the current column
              number, outputs spaces, adding one to the current column number
              after each space, until the current column number equals the
              specified value. If the value specified by To is equal to the
              current column number, there is no effect. If the value
              specified by To is less than the current column number, has the
              effect of calling New_Line (with a spacing of one), then outputs
              (To - 1) spaces, and sets the current column number to the
              specified value.

        31    The exception Layout_Error is propagated if the value specified
              by To exceeds Line_Length when the line length is bounded (that
              is, when it does not have the conventional value zero).

    32    If the file mode is In_File:

        33    Reads (and discards) individual characters, line terminators,
              and page terminators, until the next character to be read has a
              column number that equals the value specified by To; there is no
              effect if the current column number already equals this value.
              Each transfer of a character or terminator maintains the current
              column, line, and page numbers in the same way as a Get
              procedure (see A.10.6). (Short lines will be skipped until a
              line is reached that has a character at the specified column
              position.)

        34    The exception End_Error is propagated if an attempt is made to
              read a file terminator.

35    procedure Set_Line(File : in File_Type; To : in Positive_Count);
      procedure Set_Line(To   : in Positive_Count);

    36    If the file mode is Out_File or Append_File:

        37    If the value specified by To is greater than the current line
              number, has the effect of repeatedly calling New_Line (with a
              spacing of one), until the current line number equals the
              specified value. If the value specified by To is equal to the
              current line number, there is no effect. If the value specified
              by To is less than the current line number, has the effect of
              calling New_Page followed by a call of New_Line with a spacing
              equal to (To - 1).

        38    The exception Layout_Error is propagated if the value specified
              by To exceeds Page_Length when the page length is bounded (that
              is, when it does not have the conventional value zero).

    39    If the mode is In_File:

        40    Has the effect of repeatedly calling Skip_Line (with a spacing
              of one), until the current line number equals the value
              specified by To; there is no effect if the current line number
              already equals this value. (Short pages will be skipped until a
              page is reached that has a line at the specified line position.)

        41    The exception End_Error is propagated if an attempt is made to
              read a file terminator.

42    function Col(File : in File_Type) return Positive_Count;
      function Col return Positive_Count;

    43    Returns the current column number.

    44    The exception Layout_Error is propagated if this number exceeds
          Count'Last.

45    function Line(File : in File_Type) return Positive_Count;
      function Line return Positive_Count;

    46    Returns the current line number.

    47    The exception Layout_Error is propagated if this number exceeds
          Count'Last.

48    function Page(File : in File_Type) return Positive_Count;
      function Page return Positive_Count;

    49    Returns the current page number.

    50    The exception Layout_Error is propagated if this number exceeds
          Count'Last.

51    The column number, line number, or page number are allowed to exceed
Count'Last (as a consequence of the input or output of sufficiently many
characters, lines, or pages). These events do not cause any exception to be
propagated. However, a call of Col, Line, or Page propagates the exception
Layout_Error if the corresponding number exceeds Count'Last.

      NOTES

52    25  A page terminator is always skipped whenever the preceding line
      terminator is skipped. An implementation may represent the combination
      of these terminators by a single character, provided that it is properly
      recognized on input.


A.10.6 Get and Put Procedures



                              Static Semantics

1     The procedures Get and Put for items of the type Character, String,
numeric types, and enumeration types are described in subsequent subclauses.
Features of these procedures that are common to most of these types are
described in this subclause. The Get and Put procedures for items of type
Character and String deal with individual character values; the Get and Put
procedures for numeric and enumeration types treat the items as lexical
elements.

2     All procedures Get and Put have forms with a file parameter, written
first. Where this parameter is omitted, the appropriate (input or output)
current default file is understood to be specified. Each procedure Get
operates on a file of mode In_File. Each procedure Put operates on a file of
mode Out_File or Append_File.

3     All procedures Get and Put maintain the current column, line, and page
numbers of the specified file: the effect of each of these procedures upon
these numbers is the result of the effects of individual transfers of
characters and of individual output or skipping of terminators. Each transfer
of a character adds one to the current column number. Each output of a line
terminator sets the current column number to one and adds one to the current
line number. Each output of a page terminator sets the current column and line
numbers to one and adds one to the current page number. For input, each
skipping of a line terminator sets the current column number to one and adds
one to the current line number; each skipping of a page terminator sets the
current column and line numbers to one and adds one to the current page
number. Similar considerations apply to the procedures Get_Line, Put_Line, and
Set_Col.

4     Several Get and Put procedures, for numeric and enumeration types, have
format parameters which specify field lengths; these parameters are of the
nonnegative subtype Field of the type Integer.

5     Input-output of enumeration values uses the syntax of the corresponding
lexical elements. Any Get procedure for an enumeration type begins by skipping
any leading blanks, or line or page terminators. Get procedures for numeric or
enumeration types start by skipping leading blanks, where a blank is defined
as a space or a horizontal tabulation character. Next, characters are input
only so long as the sequence input is an initial sequence of an identifier or
of a character literal (in particular, input ceases when a line terminator is
encountered). The character or line terminator that causes input to cease
remains available for subsequent input.

6     For a numeric type, the Get procedures have a format parameter called
Width. If the value given for this parameter is zero, the Get procedure
proceeds in the same manner as for enumeration types, but using the syntax of
numeric literals instead of that of enumeration literals. If a nonzero value
is given, then exactly Width characters are input, or the characters up to a
line terminator, whichever comes first; any skipped leading blanks are
included in the count. The syntax used for numeric literals is an extended
syntax that allows a leading sign (but no intervening blanks, or line or page
terminators) and that also allows (for real types) an integer literal as well
as forms that have digits only before the point or only after the point.

7     Any Put procedure, for an item of a numeric or an enumeration type,
outputs the value of the item as a numeric literal, identifier, or character
literal, as appropriate. This is preceded by leading spaces if required by the
format parameters Width or Fore (as described in later subclauses), and then a
minus sign for a negative value; for an enumeration type, the spaces follow
instead of leading. The format given for a Put procedure is overridden if it
is insufficiently wide, by using the minimum needed width.

8     Two further cases arise for Put procedures for numeric and enumeration
types, if the line length of the specified output file is bounded (that is, if
it does not have the conventional value zero). If the number of characters to
be output does not exceed the maximum line length, but is such that they
cannot fit on the current line, starting from the current column, then (in
effect) New_Line is called (with a spacing of one) before output of the item.
Otherwise, if the number of characters exceeds the maximum line length, then
the exception Layout_Error is propagated and nothing is output.

9     The exception Status_Error is propagated by any of the procedures Get,
Get_Line, Put, and Put_Line if the file to be used is not open. The exception
Mode_Error is propagated by the procedures Get and Get_Line if the mode of the
file to be used is not In_File; and by the procedures Put and Put_Line, if the
mode is not Out_File or Append_File.

10    The exception End_Error is propagated by a Get procedure if an attempt
is made to skip a file terminator. The exception Data_Error is propagated by a
Get procedure if the sequence finally input is not a lexical element
corresponding to the type, in particular if no characters were input; for this
test, leading blanks are ignored; for an item of a numeric type, when a sign
is input, this rule applies to the succeeding numeric literal. The exception
Layout_Error is propagated by a Put procedure that outputs to a parameter of
type String, if the length of the actual string is insufficient for the output
of the item.


                                  Examples

11    In the examples, here and in subclauses A.10.8 and A.10.9, the string
quotes and the lower case letter b are not transferred: they are shown only to
reveal the layout and spaces.

12    N : Integer;
         ...
      Get(N);

13    --                        Characters at input  Sequence input  
      Value of N
      
      --                        bb-12535b           -12535  -12535
      --                        bb12_535e1b         12_535e1  125350
      --                        bb12_535e;          12_535e  
      (none) Data_Error raised

14    Example of overridden width parameter:

15    Put(Item => -23, Width => 2);  --  "-23"


A.10.7 Input-Output of Characters and Strings



                              Static Semantics

1     For an item of type Character the following procedures are provided:

2     procedure Get(File : in File_Type; Item : out Character);
      procedure Get(Item : out Character);

    3     After skipping any line terminators and any page terminators, reads
          the next character from the specified input file and returns the
          value of this character in the out parameter Item.

    4     The exception End_Error is propagated if an attempt is made to skip
          a file terminator.

5     procedure Put(File : in File_Type; Item : in Character);
      procedure Put(Item : in Character);

    6     If the line length of the specified output file is bounded (that is,
          does not have the conventional value zero), and the current column
          number exceeds it, has the effect of calling New_Line with a spacing
          of one. Then, or otherwise, outputs the given character to the file.

7     procedure Look_Ahead (File        : in  File_Type;
                            Item        : out Character;
                            End_Of_Line : out Boolean);
      procedure Look_Ahead (Item        : out Character;
                            End_Of_Line : out Boolean);

    8/1   Mode_Error is propagated if the mode of the file is not In_File.
          Sets End_Of_Line to True if at end of line, including if at end of
          page or at end of file; in each of these cases the value of Item is
          not specified. Otherwise End_Of_Line is set to False and Item is set
          to the next character (without consuming it) from the file.

9     procedure Get_Immediate(File : in  File_Type;
                              Item : out Character);
      procedure Get_Immediate(Item : out Character);

    10    Reads the next character, either control or graphic, from the
          specified File or the default input file. Mode_Error is propagated
          if the mode of the file is not In_File. End_Error is propagated if
          at the end of the file. The current column, line and page numbers
          for the file are not affected.

11    procedure Get_Immediate(File      : in  File_Type;
                              Item      : out Character;
                              Available : out Boolean);
      procedure Get_Immediate(Item      : out Character;
                              Available : out Boolean);

    12    If a character, either control or graphic, is available from the
          specified File or the default input file, then the character is
          read; Available is True and Item contains the value of this
          character. If a character is not available, then Available is False
          and the value of Item is not specified. Mode_Error is propagated if
          the mode of the file is not In_File. End_Error is propagated if at
          the end of the file. The current column, line and page numbers for
          the file are not affected.

13    For an item of type String the following procedures are provided:

14    procedure Get(File : in File_Type; Item : out String);
      procedure Get(Item : out String);

    15    Determines the length of the given string and attempts that number
          of Get operations for successive characters of the string (in
          particular, no operation is performed if the string is null).

16    procedure Put(File : in File_Type; Item : in String);
      procedure Put(Item : in String);

    17    Determines the length of the given string and attempts that number
          of Put operations for successive characters of the string (in
          particular, no operation is performed if the string is null).

18    procedure Get_Line(File : in File_Type;
                                    Item : out String;
                                    Last : out Natural);
      procedure Get_Line(Item : out String;   Last : out Natural);

    19    Reads successive characters from the specified input file and
          assigns them to successive characters of the specified string.
          Reading stops if the end of the string is met. Reading also stops if
          the end of the line is met before meeting the end of the string; in
          this case Skip_Line is (in effect) called with a spacing of 1. The
          values of characters not assigned are not specified.

    20    If characters are read, returns in Last the index value such that
          Item(Last) is the last character assigned (the index of the first
          character assigned is Item'First). If no characters are read,
          returns in Last an index value that is one less than Item'First. The
          exception End_Error is propagated if an attempt is made to skip a
          file terminator.

21    procedure Put_Line(File : in File_Type; Item : in String);
      procedure Put_Line(Item : in String);

    22    Calls the procedure Put for the given string, and then the procedure
          New_Line with a spacing of one.


                            Implementation Advice

23    The Get_Immediate procedures should be implemented with unbuffered
input. For a device such as a keyboard, input should be ``available'' if a key
has already been typed, whereas for a disk file, input should always be
available except at end of file. For a file associated with a keyboard-like
device, any line-editing features of the underlying operating system should be
disabled during the execution of Get_Immediate.

      NOTES

24    26  Get_Immediate can be used to read a single key from the keyboard `
      `immediately''; that is, without waiting for an end of line. In a call
      of Get_Immediate without the parameter Available, the caller will wait
      until a character is available.

25    27  In a literal string parameter of Put, the enclosing string bracket
      characters are not output. Each doubled string bracket character in the
      enclosed string is output as a single string bracket character, as a
      consequence of the rule for string literals (see 2.6).

26    28  A string read by Get or written by Put can extend over several
      lines. An implementation is allowed to assume that certain external
      files do not contain page terminators, in which case Get_Line and
      Skip_Line can return as soon as a line terminator is read.


A.10.8 Input-Output for Integer Types



                              Static Semantics

1     The following procedures are defined in the generic packages Integer_IO
and Modular_IO, which have to be instantiated for the appropriate signed
integer or modular type respectively (indicated by Num in the specifications).

2     Values are output as decimal or based literals, without low line
characters or exponent, and, for Integer_IO, preceded by a minus sign if
negative. The format (which includes any leading spaces and minus sign) can be
specified by an optional field width parameter. Values of widths of fields in
output formats are of the nonnegative integer subtype Field. Values of bases
are of the integer subtype Number_Base.

3     subtype Number_Base is Integer range 2 .. 16;

4     The default field width and base to be used by output procedures are
defined by the following variables that are declared in the generic packages
Integer_IO and Modular_IO:

5     Default_Width : Field := Num'Width;
      Default_Base  : Number_Base := 10;

6     The following procedures are provided:

7     procedure Get(File : in File_Type; Item : out Num; Width : in Field := 0);
      procedure Get(Item : out Num; Width : in Field := 0);

    8     If the value of the parameter Width is zero, skips any leading
          blanks, line terminators, or page terminators, then reads a plus
          sign if present or (for a signed type only) a minus sign if present,
          then reads the longest possible sequence of characters matching the
          syntax of a numeric literal without a point. If a nonzero value of
          Width is supplied, then exactly Width characters are input, or the
          characters (possibly none) up to a line terminator, whichever comes
          first; any skipped leading blanks are included in the count.

    9     Returns, in the parameter Item, the value of type Num that
          corresponds to the sequence input.

    10    The exception Data_Error is propagated if the sequence of characters
          read does not form a legal integer literal or if the value obtained
          is not of the subtype Num (for Integer_IO) or is not in the base
          range of Num (for Modular_IO).

11    procedure Put(File  : in File_Type;
                    Item  : in Num;
                    Width : in Field := Default_Width;
                    Base  : in Number_Base := Default_Base);
      
      procedure Put(Item  : in Num;
                    Width : in Field := Default_Width;
                    Base  : in Number_Base := Default_Base);

    12    Outputs the value of the parameter Item as an integer literal, with
          no low lines, no exponent, and no leading zeros (but a single zero
          for the value zero), and a preceding minus sign for a negative value.

    13    If the resulting sequence of characters to be output has fewer than
          Width characters, then leading spaces are first output to make up
          the difference.

    14    Uses the syntax for decimal literal if the parameter Base has the
          value ten (either explicitly or through Default_Base); otherwise,
          uses the syntax for based literal, with any letters in upper case.

15    procedure Get(From : in String; Item : out Num; Last : out Positive);

    16    Reads an integer value from the beginning of the given string,
          following the same rules as the Get procedure that reads an integer
          value from a file, but treating the end of the string as a file
          terminator. Returns, in the parameter Item, the value of type Num
          that corresponds to the sequence input. Returns in Last the index
          value such that From(Last) is the last character read.

    17    The exception Data_Error is propagated if the sequence input does
          not have the required syntax or if the value obtained is not of the
          subtype Num.

18    procedure Put(To   : out String;
                    Item : in Num;
                    Base : in Number_Base := Default_Base);

    19    Outputs the value of the parameter Item to the given string,
          following the same rule as for output to a file, using the length of
          the given string as the value for Width.

20    Integer_Text_IO is a library package that is a nongeneric equivalent to
Text_IO.Integer_IO for the predefined type Integer:

21    with Ada.Text_IO;
      package Ada.Integer_Text_IO is new Ada.Text_IO.Integer_IO(Integer);

22    For each predefined signed integer type, a nongeneric equivalent to
Text_IO.Integer_IO is provided, with names such as Ada.Long_Integer_Text_IO.


                         Implementation Permissions

23    The nongeneric equivalent packages may, but need not, be actual
instantiations of the generic package for the appropriate predefined type.

      NOTES

24    29  For Modular_IO, execution of Get propagates Data_Error if the
      sequence of characters read forms an integer literal outside the range
      0..Num'Last.


                                  Examples

25/1  This paragraph was deleted.

26    package Int_IO is new Integer_IO(Small_Int); use Int_IO;
      -- default format used at instantiation,
      -- Default_Width = 4, Default_Base = 10

27    Put(126);                            -- "b126"
      Put(-126, 7);                        -- "bbb-126"
      Put(126, Width => 13, Base => 2);    -- "bbb2#1111110#"


A.10.9 Input-Output for Real Types



                              Static Semantics

1     The following procedures are defined in the generic packages Float_IO,
Fixed_IO, and Decimal_IO, which have to be instantiated for the appropriate
floating point, ordinary fixed point, or decimal fixed point type respectively
(indicated by Num in the specifications).

2     Values are output as decimal literals without low line characters. The
format of each value output consists of a Fore field, a decimal point, an Aft
field, and (if a nonzero Exp parameter is supplied) the letter E and an Exp
field. The two possible formats thus correspond to:

3     Fore  .  Aft

4     and to:

5     Fore  .  Aft  E  Exp

6     without any spaces between these fields. The Fore field may include
leading spaces, and a minus sign for negative values. The Aft field includes
only decimal digits (possibly with trailing zeros). The Exp field includes the
sign (plus or minus) and the exponent (possibly with leading zeros).

7     For floating point types, the default lengths of these fields are
defined by the following variables that are declared in the generic package
Float_IO:

8     Default_Fore : Field := 2;
      Default_Aft  : Field := Num'Digits-1;
      Default_Exp  : Field := 3;

9     For ordinary or decimal fixed point types, the default lengths of these
fields are defined by the following variables that are declared in the generic
packages Fixed_IO and Decimal_IO, respectively:

10    Default_Fore : Field := Num'Fore;
      Default_Aft  : Field := Num'Aft;
      Default_Exp  : Field := 0;

11    The following procedures are provided:

12    procedure Get(File : in File_Type; Item : out Num; Width : in Field := 0);
      procedure Get(Item : out Num; Width : in Field := 0);

    13    If the value of the parameter Width is zero, skips any leading
          blanks, line terminators, or page terminators, then reads the
          longest possible sequence of characters matching the syntax of any
          of the following (see 2.4):

        14    [+|-]numeric_literal

        15    [+|-]numeral.[exponent]

        16    [+|-].numeral[exponent]

        17    [+|-]base#based_numeral.#[exponent]

        18    [+|-]base#.based_numeral#[exponent]

    19    If a nonzero value of Width is supplied, then exactly Width
          characters are input, or the characters (possibly none) up to a line
          terminator, whichever comes first; any skipped leading blanks are
          included in the count.

    20    Returns in the parameter Item the value of type Num that corresponds
          to the sequence input, preserving the sign (positive if none has
          been specified) of a zero value if Num is a floating point type and
          Num'Signed_Zeros is True.

    21    The exception Data_Error is propagated if the sequence input does
          not have the required syntax or if the value obtained is not of the
          subtype Num.

22    procedure Put(File : in File_Type;
                    Item : in Num;
                    Fore : in Field := Default_Fore;
                    Aft  : in Field := Default_Aft;
                    Exp  : in Field := Default_Exp);
      
      procedure Put(Item : in Num;
                    Fore : in Field := Default_Fore;
                    Aft  : in Field := Default_Aft;
                    Exp  : in Field := Default_Exp);

    23    Outputs the value of the parameter Item as a decimal literal with
          the format defined by Fore, Aft and Exp. If the value is negative,
          or if Num is a floating point type where Num'Signed_Zeros is True
          and the value is a negatively signed zero, then a minus sign is
          included in the integer part. If Exp has the value zero, then the
          integer part to be output has as many digits as are needed to
          represent the integer part of the value of Item, overriding Fore if
          necessary, or consists of the digit zero if the value of Item has no
          integer part.

    24    If Exp has a value greater than zero, then the integer part to be
          output has a single digit, which is nonzero except for the value 0.0
          of Item.

    25    In both cases, however, if the integer part to be output has fewer
          than Fore characters, including any minus sign, then leading spaces
          are first output to make up the difference. The number of digits of
          the fractional part is given by Aft, or is one if Aft equals zero.
          The value is rounded; a value of exactly one half in the last place
          is rounded away from zero.

    26    If Exp has the value zero, there is no exponent part. If Exp has a
          value greater than zero, then the exponent part to be output has as
          many digits as are needed to represent the exponent part of the
          value of Item (for which a single digit integer part is used), and
          includes an initial sign (plus or minus). If the exponent part to be
          output has fewer than Exp characters, including the sign, then
          leading zeros precede the digits, to make up the difference. For the
          value 0.0 of Item, the exponent has the value zero.

27    procedure Get(From : in String; Item : out Num; Last : out Positive);

    28    Reads a real value from the beginning of the given string, following
          the same rule as the Get procedure that reads a real value from a
          file, but treating the end of the string as a file terminator.
          Returns, in the parameter Item, the value of type Num that
          corresponds to the sequence input. Returns in Last the index value
          such that From(Last) is the last character read.

    29    The exception Data_Error is propagated if the sequence input does
          not have the required syntax, or if the value obtained is not of the
          subtype Num.

30    procedure Put(To   : out String;
                    Item : in Num;
                    Aft  : in Field := Default_Aft;
                    Exp  : in Field := Default_Exp);

    31    Outputs the value of the parameter Item to the given string,
          following the same rule as for output to a file, using a value for
          Fore such that the sequence of characters output exactly fills the
          string, including any leading spaces.

32    Float_Text_IO is a library package that is a nongeneric equivalent to
Text_IO.Float_IO for the predefined type Float:

33    with Ada.Text_IO;
      package Ada.Float_Text_IO is new Ada.Text_IO.Float_IO(Float);

34    For each predefined floating point type, a nongeneric equivalent to
Text_IO.Float_IO is provided, with names such as Ada.Long_Float_Text_IO.


                         Implementation Permissions

35    An implementation may extend Get and Put for floating point types to
support special values such as infinities and NaNs.

36    The implementation of Put need not produce an output value with greater
accuracy than is supported for the base subtype. The additional accuracy, if
any, of the value produced by Put when the number of requested digits in the
integer and fractional parts exceeds the required accuracy is implementation
defined.

37    The nongeneric equivalent packages may, but need not, be actual
instantiations of the generic package for the appropriate predefined type.

      NOTES

38    30  For an item with a positive value, if output to a string exactly
      fills the string without leading spaces, then output of the
      corresponding negative value will propagate Layout_Error.

39    31  The rules for the Value attribute (see 3.5) and the rules for Get
      are based on the same set of formats.


                                  Examples

40/1  This paragraph was deleted.

41    package Real_IO is new Float_IO(Real); use Real_IO;
      -- default format used at instantiation, Default_Exp = 3

42    X : Real := -123.4567;  --  digits 8      (see 3.5.7)

43    Put(X);  -- default format                                   "-
      1.2345670E+02"
      Put(X, Fore => 5, Aft => 3, Exp => 2);                       -- "bbb-
      1.235E+2"
      Put(X, 5, 3, 0);                                             -- "b-
      123.457"


A.10.10 Input-Output for Enumeration Types



                              Static Semantics

1     The following procedures are defined in the generic package
Enumeration_IO, which has to be instantiated for the appropriate enumeration
type (indicated by Enum in the specification).

2     Values are output using either upper or lower case letters for
identifiers. This is specified by the parameter Set, which is of the
enumeration type Type_Set.

3     type Type_Set is (Lower_Case, Upper_Case);

4     The format (which includes any trailing spaces) can be specified by an
optional field width parameter. The default field width and letter case are
defined by the following variables that are declared in the generic package
Enumeration_IO:

5     Default_Width   : Field := 0;
      Default_Setting : Type_Set := Upper_Case;

6     The following procedures are provided:

7     procedure Get(File : in File_Type; Item : out Enum);
      procedure Get(Item : out Enum);

    8     After skipping any leading blanks, line terminators, or page
          terminators, reads an identifier according to the syntax of this
          lexical element (lower and upper case being considered equivalent),
          or a character literal according to the syntax of this lexical
          element (including the apostrophes). Returns, in the parameter Item,
          the value of type Enum that corresponds to the sequence input.

    9     The exception Data_Error is propagated if the sequence input does
          not have the required syntax, or if the identifier or character
          literal does not correspond to a value of the subtype Enum.

10    procedure Put(File  : in File_Type;
                    Item  : in Enum;
                    Width : in Field := Default_Width;
                    Set   : in Type_Set := Default_Setting);
      
      procedure Put(Item  : in Enum;
                    Width : in Field := Default_Width;
                    Set   : in Type_Set := Default_Setting);

    11    Outputs the value of the parameter Item as an enumeration literal
          (either an identifier or a character literal). The optional
          parameter Set indicates whether lower case or upper case is used for
          identifiers; it has no effect for character literals. If the
          sequence of characters produced has fewer than Width characters,
          then trailing spaces are finally output to make up the difference.
          If Enum is a character type, the sequence of characters produced is
          as for Enum'Image(Item), as modified by the Width and Set
          parameters.

12    procedure Get(From : in String; Item : out Enum; Last : out Positive);

    13    Reads an enumeration value from the beginning of the given string,
          following the same rule as the Get procedure that reads an
          enumeration value from a file, but treating the end of the string as
          a file terminator. Returns, in the parameter Item, the value of type
          Enum that corresponds to the sequence input. Returns in Last the
          index value such that From(Last) is the last character read.

    14    The exception Data_Error is propagated if the sequence input does
          not have the required syntax, or if the identifier or character
          literal does not correspond to a value of the subtype Enum.

15    procedure Put(To   : out String;
                    Item : in Enum;
                    Set  : in Type_Set := Default_Setting);

    16    Outputs the value of the parameter Item to the given string,
          following the same rule as for output to a file, using the length of
          the given string as the value for Width.

17/1  Although the specification of the generic package Enumeration_IO would
allow instantiation for an integer type, this is not the intended purpose of
this generic package, and the effect of such instantiations is not defined by
the language.

      NOTES

18    32  There is a difference between Put defined for characters, and for
      enumeration values. Thus

19       Ada.Text_IO.Put('A');  --  outputs the character A

20       package Char_IO is new Ada.Text_IO.Enumeration_IO(Character);
         Char_IO.Put('A');  --  outputs the character 'A', between apostrophes

21    33  The type Boolean is an enumeration type, hence Enumeration_IO can be
      instantiated for this type.


A.11 Wide Text Input-Output


1     The package Wide_Text_IO provides facilities for input and output in
human-readable form. Each file is read or written sequentially, as a sequence
of wide characters grouped into lines, and as a sequence of lines grouped into
pages.


                              Static Semantics

2     The specification of package Wide_Text_IO is the same as that for
Text_IO, except that in each Get, Look_Ahead, Get_Immediate, Get_Line, Put,
and Put_Line procedure, any occurrence of Character is replaced by
Wide_Character, and any occurrence of String is replaced by Wide_String.

3     Nongeneric equivalents of Wide_Text_IO.Integer_IO and Wide_Text_IO.-
Float_IO are provided (as for Text_IO) for each predefined numeric type, with
names such as Ada.Integer_Wide_Text_IO, Ada.Long_Integer_Wide_Text_IO,
Ada.Float_Wide_Text_IO, Ada.Long_Float_Wide_Text_IO.


A.12 Stream Input-Output


1     The packages Streams.Stream_IO, Text_IO.Text_Streams, and
Wide_Text_IO.Text_Streams provide stream-oriented operations on files.


A.12.1 The Package Streams.Stream_IO


1     The subprograms in the child package Streams.Stream_IO provide control
over stream files. Access to a stream file is either sequential, via a call on
Read or Write to transfer an array of stream elements, or positional (if
supported by the implementation for the given file), by specifying a relative
index for an element. Since a stream file can be converted to a Stream_Access
value, calling stream-oriented attribute subprograms of different element
types with the same Stream_Access value provides heterogeneous input-output.
See 13.13 for a general discussion of streams.


                              Static Semantics

1.1/1 The elements of a stream file are stream elements. If positioning is
supported for the specified external file, a current index and current size
are maintained for the file as described in A.8. If positioning is not
supported, a current index is not maintained, and the current size is
implementation defined.

2     The library package Streams.Stream_IO has the following declaration:

3     with Ada.IO_Exceptions;
      package Ada.Streams.Stream_IO is

4         type Stream_Access is access all Root_Stream_Type'Class;

5         type File_Type is limited private;

6         type File_Mode is (In_File, Out_File, Append_File);

7         type    Count          is range 0 .. implementation-defined;
          subtype Positive_Count is Count range 1 .. Count'Last;
            -- Index into file, in stream elements.

8         procedure Create (File : in out File_Type;
                            Mode : in File_Mode := Out_File;
                            Name : in String    := "";
                            Form : in String    := "");

9         procedure Open (File : in out File_Type;
                          Mode : in File_Mode;
                          Name : in String;
                          Form : in String := "");

10        procedure Close  (File : in out File_Type);
          procedure Delete (File : in out File_Type);
          procedure Reset  (File : in out File_Type; Mode : in File_Mode);
          procedure Reset  (File : in out File_Type);

11        function Mode (File : in File_Type) return File_Mode;
          function Name (File : in File_Type) return String;
          function Form (File : in File_Type) return String;

12        function Is_Open     (File : in File_Type) return Boolean;
          function End_Of_File (File : in File_Type) return Boolean;

13        function Stream (File : in File_Type) return Stream_Access;
              -- Return stream access for use with T'Input and T'Output

14/1  This paragraph was deleted.

15        -- Read array of stream elements from file
          procedure Read (File : in  File_Type;
                          Item : out Stream_Element_Array;
                          Last : out Stream_Element_Offset;
                          From : in  Positive_Count);

16        procedure Read (File : in  File_Type;
                          Item : out Stream_Element_Array;
                          Last : out Stream_Element_Offset);

17/1  This paragraph was deleted.

18        -- Write array of stream elements into file
          procedure Write (File : in File_Type;
                           Item : in Stream_Element_Array;
                           To   : in Positive_Count);

19        procedure Write (File : in File_Type;
                                 Item : in Stream_Element_Array);

20/1  This paragraph was deleted.

21        -- Operations on position within file

22        procedure Set_Index(File : in File_Type; To : in Positive_Count);

23        function Index(File : in File_Type) return Positive_Count;
          function Size (File : in File_Type) return Count;

24        procedure Set_Mode(File : in out File_Type; Mode : in File_Mode);

25/1      procedure Flush(File : in File_Type);

26        -- exceptions
          Status_Error : exception renames IO_Exceptions.Status_Error;
          Mode_Error   : exception renames IO_Exceptions.Mode_Error;
          Name_Error   : exception renames IO_Exceptions.Name_Error;
          Use_Error    : exception renames IO_Exceptions.Use_Error;
          Device_Error : exception renames IO_Exceptions.Device_Error;
          End_Error    : exception renames IO_Exceptions.End_Error;
          Data_Error   : exception renames IO_Exceptions.Data_Error;

27    private
         ... -- not specified by the language
      end Ada.Streams.Stream_IO;

28    The subprograms Create, Open, Close, Delete, Reset, Mode, Name, Form,
Is_Open, and End_of_File have the same effect as the corresponding subprograms
in Sequential_IO (see A.8.2).

28.1/1 The Set_Mode procedure changes the mode of the file. If the new mode is
Append_File, the file is positioned to its end; otherwise, the position in the
file is unchanged.

28.2/1 The Flush procedure synchronizes the external file with the internal
file (by flushing any internal buffers) without closing the file or changing
the position. Mode_Error is propagated if the mode of the file is In_File.

29/1  The Stream function returns a Stream_Access result from a File_Type
object, thus allowing the stream-oriented attributes Read, Write, Input, and
Output to be used on the same file for multiple types. Stream propagates
Status_Error if File is not open.

30    The procedures Read and Write are equivalent to the corresponding
operations in the package Streams. Read propagates Mode_Error if the mode of
File is not In_File. Write propagates Mode_Error if the mode of File is not
Out_File or Append_File. The Read procedure with a Positive_Count parameter
starts reading at the specified index. The Write procedure with a
Positive_Count parameter starts writing at the specified index.

30.1/1 The Size function returns the current size of the file.

31/1  The Index function returns the current index.

32    The Set_Index procedure sets the current index to the specified value.

32.1/1 If positioning is supported for the external file, the current index is
maintained as follows:

32.2/1 For Open and Create, if the Mode parameter is Append_File, the current
      index is set to the current size of the file plus one; otherwise, the
      current index is set to one.

32.3/1 For Reset, if the Mode parameter is Append_File, or no Mode parameter
      is given and the current mode is Append_File, the current index is set
      to the current size of the file plus one; otherwise, the current index
      is set to one.

32.4/1 For Set_Mode, if the new mode is Append_File, the current index is set
      to current size plus one; otherwise, the current index is unchanged.

32.5/1 For Read and Write without a Positive_Count parameter, the current
      index is incremented by the number of stream elements read or written.

32.6/1 For Read and Write with a Positive_Count parameter, the value of the
      current index is set to the value of the Positive_Count parameter plus
      the number of stream elements read or written.

33    If positioning is not supported for the given file, then a call of Index
or Set_Index propagates Use_Error. Similarly, a call of Read or Write with a
Positive_Count parameter propagates Use_Error.

34/1  This paragraph was deleted.

35/1  This paragraph was deleted.

36/1  This paragraph was deleted.


                             Erroneous Execution

36.1/1 If the File_Type object passed to the Stream function is later closed
or finalized, and the stream-oriented attributes are subsequently called
(explicitly or implicitly) on the Stream_Access value returned by Stream,
execution is erroneous. This rule applies even if the File_Type object was
opened again after it had been closed.


A.12.2 The Package Text_IO.Text_Streams


1     The package Text_IO.Text_Streams provides a function for treating a text
file as a stream.


                              Static Semantics

2     The library package Text_IO.Text_Streams has the following declaration:

3     with Ada.Streams;
      package Ada.Text_IO.Text_Streams is
         type Stream_Access is access all Streams.Root_Stream_Type'Class;

4        function Stream (File : in File_Type) return Stream_Access;
      end Ada.Text_IO.Text_Streams;

5     The Stream function has the same effect as the corresponding function in
Streams.Stream_IO.

      NOTES

6     34  The ability to obtain a stream for a text file allows Current_Input,
      Current_Output, and Current_Error to be processed with the functionality
      of streams, including the mixing of text and binary input-output, and
      the mixing of binary input-output for different types.

7     35  Performing operations on the stream associated with a text file does
      not affect the column, line, or page counts.


A.12.3 The Package Wide_Text_IO.Text_Streams


1     The package Wide_Text_IO.Text_Streams provides a function for treating a
wide text file as a stream.


                              Static Semantics

2     The library package Wide_Text_IO.Text_Streams has the following
declaration:

3     with Ada.Streams;
      package Ada.Wide_Text_IO.Text_Streams is
         type Stream_Access is access all Streams.Root_Stream_Type'Class;

4        function Stream (File : in File_Type) return Stream_Access;
      end Ada.Wide_Text_IO.Text_Streams;

5     The Stream function has the same effect as the corresponding function in
Streams.Stream_IO.


A.13 Exceptions in Input-Output


1     The package IO_Exceptions defines the exceptions needed by the
predefined input-output packages.


                              Static Semantics

2     The library package IO_Exceptions has the following declaration:

3     package Ada.IO_Exceptions is
         pragma Pure(IO_Exceptions);

4        Status_Error : exception;
         Mode_Error   : exception;
         Name_Error   : exception;
         Use_Error    : exception;
         Device_Error : exception;
         End_Error    : exception;
         Data_Error   : exception;
         Layout_Error : exception;

5     end Ada.IO_Exceptions;

6     If more than one error condition exists, the corresponding exception
that appears earliest in the following list is the one that is propagated.

7     The exception Status_Error is propagated by an attempt to operate upon a
file that is not open, and by an attempt to open a file that is already open.

8     The exception Mode_Error is propagated by an attempt to read from, or
test for the end of, a file whose current mode is Out_File or Append_File, and
also by an attempt to write to a file whose current mode is In_File. In the
case of Text_IO, the exception Mode_Error is also propagated by specifying a
file whose current mode is Out_File or Append_File in a call of Set_Input,
Skip_Line, End_Of_Line, Skip_Page, or End_Of_Page; and by specifying a file
whose current mode is In_File in a call of Set_Output, Set_Line_Length,
Set_Page_Length, Line_Length, Page_Length, New_Line, or New_Page.

9     The exception Name_Error is propagated by a call of Create or Open if
the string given for the parameter Name does not allow the identification of
an external file. For example, this exception is propagated if the string is
improper, or, alternatively, if either none or more than one external file
corresponds to the string.

10    The exception Use_Error is propagated if an operation is attempted that
is not possible for reasons that depend on characteristics of the external
file. For example, this exception is propagated by the procedure Create, among
other circumstances, if the given mode is Out_File but the form specifies an
input only device, if the parameter Form specifies invalid access rights, or
if an external file with the given name already exists and overwriting is not
allowed.

11    The exception Device_Error is propagated if an input-output operation
cannot be completed because of a malfunction of the underlying system.

12    The exception End_Error is propagated by an attempt to skip (read past)
the end of a file.

13    The exception Data_Error can be propagated by the procedure Read (or by
the Read attribute) if the element read cannot be interpreted as a value of
the required subtype. This exception is also propagated by a procedure Get
(defined in the package Text_IO) if the input character sequence fails to
satisfy the required syntax, or if the value input does not belong to the
range of the required subtype.

14    The exception Layout_Error is propagated (in text input-output) by Col,
Line, or Page if the value returned exceeds Count'Last. The exception
Layout_Error is also propagated on output by an attempt to set column or line
numbers in excess of specified maximum line or page lengths, respectively
(excluding the unbounded cases). It is also propagated by an attempt to Put
too many characters to a string.


                         Documentation Requirements

15    The implementation shall document the conditions under which Name_Error,
Use_Error and Device_Error are propagated.


                         Implementation Permissions

16    If the associated check is too complex, an implementation need not
propagate Data_Error as part of a procedure Read (or the Read attribute) if
the value read cannot be interpreted as a value of the required subtype.


                             Erroneous Execution

17    If the element read by the procedure Read (or by the Read attribute)
cannot be interpreted as a value of the required subtype, but this is not
detected and Data_Error is not propagated, then the resulting value can be
abnormal, and subsequent references to the value can lead to erroneous
execution, as explained in 13.9.1.


A.14 File Sharing



                              Dynamic Semantics

1     It is not specified by the language whether the same external file can
be associated with more than one file object. If such sharing is supported by
the implementation, the following effects are defined:

2     Operations on one text file object do not affect the column, line, and
      page numbers of any other file object.

3/1   This paragraph was deleted.

4     For direct and stream files, the current index is a property of each
      file object; an operation on one file object does not affect the current
      index of any other file object.

5     For direct and stream files, the current size of the file is a property
      of the external file.

6     All other effects are identical.


A.15 The Package Command_Line


1     The package Command_Line allows a program to obtain the values of its
arguments and to set the exit status code to be returned on normal
termination.


                              Static Semantics

2     The library package Ada.Command_Line has the following declaration:

3     package Ada.Command_Line is
        pragma Preelaborate(Command_Line);

4       function Argument_Count return Natural;

5       function Argument (Number : in Positive) return String;

6       function Command_Name return String;

7       type Exit_Status is implementation-defined integer type;

8       Success : constant Exit_Status;
        Failure : constant Exit_Status;

9       procedure Set_Exit_Status (Code : in Exit_Status);

10    private
        ... -- not specified by the language
      end Ada.Command_Line;
      

11    function Argument_Count return Natural;

    12    If the external execution environment supports passing arguments to
          a program, then Argument_Count returns the number of arguments
          passed to the program invoking the function. Otherwise it returns 0.
          The meaning of ``number of arguments'' is implementation defined.

13    function Argument (Number : in Positive) return String;

    14    If the external execution environment supports passing arguments to
          a program, then Argument returns an implementation-defined value
          corresponding to the argument at relative position Number. If Number
          is outside the range 1..Argument_Count, then Constraint_Error is
          propagated.

15    function Command_Name return String;

    16    If the external execution environment supports passing arguments to
          a program, then Command_Name returns an implementation-defined value
          corresponding to the name of the command invoking the program;
          otherwise Command_Name returns the null string.

16.1/1 type Exit_Status is implementation-defined integer type;

    17    The type Exit_Status represents the range of exit status values
          supported by the external execution environment. The constants
          Success and Failure correspond to success and failure, respectively.

18    procedure Set_Exit_Status (Code : in Exit_Status);

    19    If the external execution environment supports returning an exit
          status from a program, then Set_Exit_Status sets Code as the status.
          Normal termination of a program returns as the exit status the value
          most recently set by Set_Exit_Status, or, if no such value has been
          set, then the value Success. If a program terminates abnormally, the
          status set by Set_Exit_Status is ignored, and an
          implementation-defined exit status value is set.

    20    If the external execution environment does not support returning an
          exit value from a program, then Set_Exit_Status does nothing.


                         Implementation Permissions

21    An alternative declaration is allowed for package Command_Line if
different functionality is appropriate for the external execution environment.

      NOTES

22    36  Argument_Count, Argument, and Command_Name correspond to the C
      language's argc, argv[n] (for n>0) and argv[0], respectively.