VMS Help
ADA, Language Topics, TEXT_IO
*Conan The Librarian
|
TEXT_IO is an Ada package that provides input-output operations
for text files, including interactive input-output to and from a
terminal.
All of the file management input-output operations are also
provided by this package (see HELP Ada Language_Topics File_
Management).
procedure SET_INPUT(FILE : in FILE_TYPE);
Operates on a file of mode IN_FILE. Sets the current default
input file to FILE.
The exception STATUS_ERROR is raised if the given file is not
open. The exception MODE_ERROR is raised if the mode of the given
file is not IN_FILE.
procedure SET_OUTPUT(FILE : in FILE_TYPE);
Operates on a file of mode OUT_FILE. Sets the current default
output file to FILE.
The exception STATUS_ERROR is raised if the given file is not
open. The exception MODE_ERROR is raised if the mode of the given
file is not OUT_FILE.
function STANDARD_INPUT return FILE_TYPE;
Returns the standard input file.
Note:
The standard input file cannot be opened, closed, reset, or
deleted, because the parameter FILE of the corresponding
procedures has the mode 'in out'.
function STANDARD_OUTPUT return FILE_TYPE;
Returns the standard output file.
Note:
The standard output file cannot be opened, closed, reset,
or deleted, because the parameter FILE of the corresponding
procedures has the mode 'in out'.
function CURRENT_INPUT return FILE_TYPE;
Returns the current default input file.
function CURRENT_OUTPUT return FILE_TYPE;
Returns the current default output file.
procedure SET_LINE_LENGTH(FILE : in FILE_TYPE; TO : in COUNT);
procedure SET_LINE_LENGTH(TO : in COUNT);
Sets the maximum line length of the specified output file to
the number of characters specified by TO. The value zero for TO
specifies an unbounded line length.
The exception USE_ERROR is raised if the specified line length is
inappropriate for the associated external file.
procedure SET_PAGE_LENGTH(FILE : in FILE_TYPE; TO : in COUNT);
procedure SET_PAGE_LENGTH(TO : in COUNT);
Sets the maximum page length of the specified output file to the
number of lines specified by TO. The value zero for TO specifies
an unbounded page length.
The exception USE_ERROR is raised if the specified page length is
inappropriate for the associated external file.
function LINE_LENGTH(FILE : in FILE_TYPE) return COUNT;
function LINE_LENGTH return COUNT;
Returns the maximum line length currently set for the specified
output file, or zero if the line length is unbounded.
function PAGE_LENGTH(FILE : in FILE_TYPE) return COUNT;
function PAGE_LENGTH return COUNT;
Returns the maximum page length currently set for the specified
output file, or zero if the page length is unbounded.
procedure NEW_LINE(FILE : in FILE_TYPE;
SPACING : in POSITIVE_COUNT := 1);
procedure NEW_LINE(SPACING : in POSITIVE_COUNT := 1);
Operates on a file of mode OUT_FILE.
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.
For a SPACING greater than one, the above actions are performed
SPACING times.
The exception MODE_ERROR is raised if the mode is not OUT_FILE.
procedure SKIP_LINE(FILE : in FILE_TYPE;
SPACING : in POSITIVE_COUNT := 1);
procedure SKIP_LINE(SPACING : in POSITIVE_COUNT := 1);
Operates on a file of mode IN_FILE.
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.
For a SPACING greater than one, the above actions are performed
SPACING times.
The exception MODE_ERROR is raised if the mode is not IN_FILE.
The exception END_ERROR is raised if an attempt is made to read a
file terminator.
function END_OF_LINE(FILE : in FILE_TYPE) return BOOLEAN;
function END_OF_LINE return BOOLEAN;
Operates on a file of mode IN_FILE. Returns TRUE if a line
terminator or a file terminator is next; otherwise returns FALSE.
The exception MODE_ERROR is raised if the mode is not IN_FILE.
procedure NEW_PAGE(FILE : in FILE_TYPE);
procedure NEW_PAGE;
Operates on a file of mode OUT_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.
The exception MODE_ERROR is raised if the mode is not OUT_FILE.
procedure SKIP_PAGE(FILE : in FILE_TYPE);
procedure SKIP_PAGE;
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.
The exception MODE_ERROR is raised if the mode is not IN_FILE.
The exception END_ERROR is raised if an attempt is made to read a
file terminator.
function END_OF_PAGE(FILE : in FILE_TYPE) return BOOLEAN;
function END_OF_PAGE return BOOLEAN;
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.
The exception MODE_ERROR is raised if the mode is not IN_FILE.
function END_OF_FILE(FILE : in FILE_TYPE) return BOOLEAN;
function END_OF_FILE;
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.
The exception MODE_ERROR is raised if the mode is not IN_FILE.
procedure SET_COL(FILE : in FILE_TYPE; TO : in POSITIVE_COUNT);
procedure SET_COL(TO : in POSITIVE_COUNT);
If the file mode is OUT_FILE:
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.
The exception LAYOUT_ERROR is raised 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).
If the file mode is IN_FILE:
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. (Short lines will be skipped until a line is reached
that has a character at the specified column position.)
The exception END_ERROR is raised if an attempt is made to read a
file terminator.
procedure SET_LINE(FILE : in FILE_TYPE;
TO : in POSITIVE_COUNT);
procedure SET_LINE(TO : in POSITIVE_COUNT);
If the file mode is OUT_FILE:
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).
The exception LAYOUT_ERROR is raised 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).
If the mode is IN_FILE:
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.)
The exception END_ERROR is raised if an attempt is made to read a
file terminator.
function COL(FILE : in FILE_TYPE) return POSITIVE_COUNT;
function COL return POSITIVE_COUNT;
Returns the current column number.
The exception LAYOUT_ERROR is raised if this number exceeds
COUNT'LAST.
function LINE(FILE : in FILE_TYPE) return POSITIVE_COUNT;
function LINE return POSITIVE_COUNT;
Returns the current line number.
The exception LAYOUT_ERROR is raised if this number exceeds
COUNT'LAST.
function PAGE(FILE : in FILE_TYPE) return POSITIVE_COUNT;
function PAGE return POSITIVE_COUNT;
Returns the current page number.
The exception LAYOUT_ERROR is raised if this number exceeds
COUNT'LAST.
|
23 - Character and String IO
|
23.1 - GET
procedure GET(FILE : in FILE_TYPE;
ITEM : out CHARACTER);
procedure GET(ITEM : out CHARACTER);
procedure GET(FILE : in FILE_TYPE; ITEM: out STRING);
procedure GET(ITEM: out STRING);
If ITEM is of the type CHARACTER:
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.
The exception END_ERROR is raised if an attempt is made to skip a
file terminator.
If ITEM is of the type STRING:
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).
23.2 - PUT
procedure PUT(FILE : in FILE_TYPE; ITEM : in CHARACTER);
procedure PUT(ITEM : in CHARACTER);
procedure PUT(FILE : in FILE_TYPE; ITEM : in STRING);
procedure PUT(ITEM : in STRING);
If ITEM is of the type CHARACTER:
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.
If ITEM is of the type STRING:
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).
23.3 - GET_LINE
procedure GET_LINE(FILE : in FILE_TYPE;
ITEM : out STRING;
LAST : out NATURAL);
procedure GET_LINE(ITEM : out STRING;
LAST : out NATURAL);
Replaces successive characters of the specified string by
successive characters read from the specified input file. Reading
stops if the end of the line is met, in which case the procedure
SKIP_LINE is then called (in effect) with a spacing of one;
reading also stops if the end of the string is met. Characters
not replaced are left undefined.
If characters are read, returns in LAST the index value such that
ITEM(LAST) is the last character replaced (the index of the first
character replaced 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 raised if an attempt is made to skip a
file terminator.
23.4 - PUT_LINE
procedure PUT_LINE(FILE : in FILE_TYPE; ITEM : in STRING);
procedure PUT_LINE(ITEM : in STRING);
Calls the procedure PUT for the given string, and then the
procedure NEW_LINE with a spacing of one.
INTEGER_IO is a generic package defined within the package TEXT_
IO. You use it to input and output integers to and from a text
file, or interactively with a terminal. You instantiate it with
one generic parameter, NUM, which defines the integer type upon
which the procedures and functions will operate. For example, if
you defined the following type
type MY_INT is new INTEGER range 0 .. INTEGER'LAST;
you would need two instantiations of INTEGER_IO if numbers of
both types MY_INT and INTEGER were to be used for input-output.
For example:
package MY_INT_IO is new TEXT_IO.INTEGER_IO(NUM => MY_INT);
package INT_IO is new TEXT_IO.INTEGER_IO(NUM => INTEGER);
24.1 - GET
procedure GET(FILE : in FILE_TYPE;
ITEM : out NUM;
WIDTH : in FIELD := 0);
procedure GET(ITEM : out NUM; WIDTH : in FIELD := 0);
If the value of the parameter WIDTH is zero, skips any leading
blanks, line terminators, or page terminators, then reads a plus
or a minus sign if present, then reads according to the syntax of
an integer literal (which may be a based literal). 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.
Returns, in the parameter ITEM, the value of type NUM that
corresponds to the sequence input.
The exception DATA_ERROR is raised if the sequence input does not
have the required syntax or if the value obtained is not of the
subtype NUM.
procedure GET(FROM : in STRING;
ITEM : out NUM;
LAST : out POSITIVE);
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.
24.2 - PUT
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);
Outputs the value of the parameter ITEM as an integer literal,
with no underlines, no exponent, and no leading zeros (but a
single zero for the value zero), and a preceding minus sign for a
negative value.
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.
Uses the syntax for a decimal literal if the parameter BASE
has the value ten (either explicitly or through DEFAULT_BASE);
otherwise, uses the syntax for a based literal, with any letters
in uppercase.
procedure PUT(TO : out STRING;
ITEM : in NUM;
BASE : in NUMBER_BASE := DEFAULT_BASE);
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.
FLOAT_IO and FIXED_IO are generic packages defined within the
package TEXT_IO. You use them to input and output real numbers
to and from a text file, or interactively with a terminal. You
instantiate them with one generic parameter, NUM, which defines
the real type, floating or fixed respectively, upon which the
procedures and functions will operate. For example, if you
defined the following types
type VOLT is delta 0.125 range 0.0 .. 255.0;
type MASS is digits 7 range 0.0 .. 1.0E35;
you would need to instantiate both FLOAT_IO and FIXED_IO if
numbers of both types were to be used for input-output. For
example:
package VOLT_IO is new TEXT_IO.FIXED_IO(NUM => VOLT);
package MASS_IO is new TEXT_IO.FLOAT_IO(NUM => MASS);
25.1 - GET
procedure GET(FILE : in FILE_TYPE;
ITEM : out NUM;
WIDTH : in FIELD := 0);
procedure GET(ITEM : out NUM;
WIDTH : in FIELD := 0);
If the value of the parameter WIDTH is zero, skips any leading
blanks, line terminators, or page terminators, then reads a plus
or a minus sign if present, then reads according to the syntax
of a real literal (which may be a based literal). 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.
Returns, in the parameter ITEM, the value of type NUM that
corresponds to the sequence input.
The exception DATA_ERROR is raised if the sequence input does not
have the required syntax or if the value obtained is not of the
subtype NUM.
procedure GET(FROM : in STRING;
ITEM : out NUM;
LAST : out POSITIVE);
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 the type
NUM that corresponds to the sequence input. Returns in LAST the
index value such that FROM(LAST) is the last character read.
The exception DATA_ERROR is raised if the sequence input does not
have the required syntax, or if the value obtained is not of the
subtype NUM.
25.2 - PUT
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);
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, 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.
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.
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 may be rounded either up or down.
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.
procedure PUT(TO : out STRING;
ITEM : in NUM;
AFT : in FIELD := DEFAULT_AFT;
EXP : in FIELD := DEFAULT_EXP);
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.
ENUMERATION_IO is a generic package defined within the package
TEXT_IO. You use it to input and output enumerated types to
and from a text file, or interactively with a terminal. You
instantiate it with one generic parameter, ENUM, which defines
the enumerated type upon which the procedures and functions will
operate. For example, if you defined the following type
type COLOR is (RED, YELLOW, GREEN, BLUE, VIOLET);
you would need to instantiate ENUMERATION_IO if values of the
type COLOR were to be used for input-output. For example:
package COLOR_IO is new TEXT_IO.ENUMERATION_IO(ENUM => COLOR);
26.1 - GET
procedure GET(FILE : in FILE_TYPE; ITEM : out ENUM);
procedure GET(ITEM : out ENUM);
After skipping any leading blanks, line terminators, or page
terminators, reads an identifier according to the syntax of
this lexical element (lower- and uppercase 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.
The exception DATA_ERROR is raised 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.
procedure GET(FROM : in STRING;
ITEM : out ENUM;
LAST : out POSITIVE):
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 the type ENUM that corresponds to the sequence input.
Returns in LAST the index value such that FROM(LAST) is the last
character read.
The exception DATA_ERROR is raised 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.
26.2 - PUT
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);
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- or uppercase 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.
procedure PUT(TO : out STRING;
ITEM : in ENUM;
SET : in TYPE_SET := DEFAULT_SETTING);
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.