Contents Index Search Previous Next
G.1.3 Complex Input-Output
1
The generic package Text_IO.Complex_IO defines
procedures for the formatted input and output of complex values. The
generic actual parameter in an instantiation of Text_IO.Complex_IO is
an instance of Numerics.Generic_Complex_Types for some floating point
subtype. Exceptional conditions are reported by raising the appropriate
exception defined in Text_IO.
1.a
Implementation Note: An
implementation of Text_IO.Complex_IO can be built around an instance
of Text_IO.Float_IO for the base subtype of Complex_Types.Real, where
Complex_Types is the generic formal package parameter of Text_IO.Complex_IO.
There is no need for an implementation of Text_IO.Complex_IO to parse
real values.
Static Semantics
2
The generic library
package Text_IO.Complex_IO has the following declaration:
2.a
Ramification: Because
this is a child of Text_IO, the declarations of the visible part of Text_IO
are directly visible within it.
3
with Ada.Numerics.Generic_Complex_Types;
generic
with package Complex_Types is
new Ada.Numerics.Generic_Complex_Types (<>);
package Ada.Text_IO.Complex_IO is
4
use Complex_Types;
5
Default_Fore : Field := 2;
Default_Aft : Field := Real'Digits - 1;
Default_Exp : Field := 3;
6
procedure Get (File : in File_Type;
Item : out Complex;
Width : in Field := 0);
procedure Get (Item : out Complex;
Width : in Field := 0);
7
procedure Put (File : in File_Type;
Item : in Complex;
Fore : in Field := Default_Fore;
Aft : in Field := Default_Aft;
Exp : in Field := Default_Exp);
procedure Put (Item : in Complex;
Fore : in Field := Default_Fore;
Aft : in Field := Default_Aft;
Exp : in Field := Default_Exp);
8
procedure Get (From : in String;
Item : out Complex;
Last : out Positive);
procedure Put (To : out String;
Item : in Complex;
Aft : in Field := Default_Aft;
Exp : in Field := Default_Exp);
9
end Ada.Text_IO.Complex_IO;
10
The semantics of the Get and Put procedures are
as follows:
11
procedure Get (File : in File_Type;
Item : out Complex;
Width : in Field := 0);
procedure Get (Item : out Complex;
Width : in Field := 0);
12/1
{
8652/0092}
The input sequence is a pair of optionally signed real literals representing
the real and imaginary components of a complex value
These components
have the format defined for the corresponding Get procedure of an instance
of Text_IO.Float_IO (see A.10.9) for the
base subtype of Complex_Types.Real. T ; optionally, the pair
of components may be separated by a comma
and/or surrounded by
a pair of parentheses
or both . Blanks are freely allowed before
each of the components and before the parentheses and comma, if either
is used. If the value of the parameter Width is zero, then
13
- line
and page terminators are also allowed in these places;
14
- the components shall be
separated by at least one blank or line terminator if the comma is omitted;
and
15
- reading stops when the
right parenthesis has been read, if the input sequence includes a left
parenthesis, or when the imaginary component has been read, otherwise.
15.1
16
- the components shall be
separated by at least one blank if the comma is omitted; and
17
- exactly Width characters
are read, or the characters (possibly none) up to a line terminator,
whichever comes first (blanks are included in the count).
17.a
Reason: The parenthesized
and comma-separated form is the form produced by Put on output (see below),
and also by list-directed output in Fortran. The other allowed forms
match several common styles of edit-directed output in Fortran, allowing
most preexisting Fortran data files containing complex data to be read
easily. When such files contain complex values with no separation between
the real and imaginary components, the user will have to read those components
separately, using an instance of Text_IO.Float_IO.
18
Returns, in the parameter Item, the value of
type Complex that corresponds to the input sequence.
19
The exception
Text_IO.Data_Error is raised if the input sequence does not have the
required syntax or if the components of the complex value obtained are
not of the base subtype of Complex_Types.Real.
20
procedure Put (File : in File_Type;
Item : in Complex;
Fore : in Field := Default_Fore;
Aft : in Field := Default_Aft;
Exp : in Field := Default_Exp);
procedure Put (Item : in Complex;
Fore : in Field := Default_Fore;
Aft : in Field := Default_Aft;
Exp : in Field := Default_Exp);
21
Outputs the value of the parameter Item as
a pair of decimal literals representing the real and imaginary components
of the complex value, using the syntax of an aggregate. More specifically,
22
- outputs a left parenthesis;
23
- outputs the value of the
real component of the parameter Item with the format defined by the corresponding
Put procedure of an instance of Text_IO.Float_IO for the base subtype
of Complex_Types.Real, using the given values of Fore, Aft, and Exp;
24
25
- outputs the value of the
imaginary component of the parameter Item with the format defined by
the corresponding Put procedure of an instance of Text_IO.Float_IO for
the base subtype of Complex_Types.Real, using the given values of Fore,
Aft, and Exp;
26
- outputs
a right parenthesis.
26.a
Discussion: If the file
has a bounded line length, a line terminator may be output implicitly
before any element of the sequence itemized above.
26.b
Discussion: The option
of outputting the complex value as a pair of reals without additional
punctuation is not provided, since it can be accomplished by outputting
the real and imaginary components of the complex value separately.
27
procedure Get (From : in String;
Item : out Complex;
Last : out Positive);
28
Reads a complex value from the beginning of
the given string, following the same rule as the Get procedure that reads
a complex value from a file, but treating the end of the string as a
line terminator. Returns, in the parameter Item, the value of type Complex
that corresponds to the input sequence. Returns in Last the index value
such that From(Last) is the last character read.
29
The exception
Text_IO.Data_Error is raised if the input sequence does not have the
required syntax or if the components of the complex value obtained are
not of the base subtype of Complex_Types.Real.
30
procedure Put (To : out String;
Item : in Complex;
Aft : in Field := Default_Aft;
Exp : in Field := Default_Exp);
31
Outputs the value of the parameter Item to
the given string as a pair of decimal literals representing the real
and imaginary components of the complex value, using the syntax of an
aggregate. More specifically,
32
- a left parenthesis, the
real component, and a comma are left justified in the given string, with
the real component having the format defined by the Put procedure (for
output to a file) of an instance of Text_IO.Float_IO for the base subtype
of Complex_Types.Real, using a value of zero for Fore and the given values
of Aft and Exp;
33
- the imaginary component
and a right parenthesis are right justified in the given string, with
the imaginary component having the format defined by the Put procedure
(for output to a file) of an instance of Text_IO.Float_IO for the base
subtype of Complex_Types.Real, using a value for Fore that completely
fills the remainder of the string, together with the given values of
Aft and Exp.
33.a
Reason: This rule is
the one proposed in LSN-1051. Other rules were considered, including
one that would have read ``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, or comes closest to filling, the string; in the latter case, the
string is filled by inserting one extra blank immediately after the comma.''
While this latter rule might be considered the closest analogue to the
rule for output to a string in Text_IO.Float_IO, it requires a more difficult
and inefficient implementation involving special cases when the integer
part of one component is substantially longer than that of the other
and the string is too short to allow both to be preceded by blanks. Unless
such a special case applies, the latter rule might produce better columnar
output if several such strings are ultimately output to a file, but very
nearly the same output can be produced by outputting to the file directly,
with the appropriate value of Fore; in any case, it might validly be
assumed that output to a string is intended for further computation rather
than for display, so that the precise formatting of the string to achieve
a particular appearance is not the major concern.
34
The exception Text_IO.Layout_Error is raised
if the given string is too short to hold the formatted output.
Implementation Permissions
35
Other exceptions declared (by renaming) in Text_IO
may be raised by the preceding procedures in the appropriate circumstances,
as for the corresponding procedures of Text_IO.Float_IO.
Contents Index Search Previous Next Legal