A.10.6 Get and Put Procedures
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.
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.
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.
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.
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. 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.
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.
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.
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.
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.
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.
In the examples, here and in subclauses A.10.8
, the string quotes and the lower
case letter b are not transferred: they are shown only to reveal the
layout and spaces.
N : Integer;
-- 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
Example of overridden
Put(Item => -23, Width => 2); -- "–23"