G.1.3 Complex Input-Output
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.
Static Semantics
The generic library
package Text_IO.Complex_IO has the following declaration:
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
use Complex_Types;
Default_Fore : Field := 2;
Default_Aft : Field := Real'Digits - 1;
Default_Exp : Field := 3;
procedure Get (File :
in File_Type;
Item :
out Complex;
Width :
in Field := 0);
procedure Get (Item :
out Complex;
Width :
in Field := 0);
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);
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);
end Ada.Text_IO.Complex_IO;
The library package Complex_Text_IO
defines the same subprograms as Text_IO.Complex_IO, except that the predefined
type Float is systematically substituted for Real, and the type Numerics.Complex_Types.Complex
is systematically substituted for Complex throughout. Nongeneric equivalents
of Text_IO.Complex_IO corresponding to each of the other predefined floating
point types are defined similarly, with the names Short_Complex_Text_IO,
Long_Complex_Text_IO, etc.
The semantics of the Get and Put procedures are as
follows:
procedure Get (File : in File_Type;
Item : out Complex;
Width : in Field := 0);
procedure Get (Item : out Complex;
Width : in Field := 0);
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.
The pair of components may be separated by a comma 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
line and page terminators are also allowed
in these places;
the components shall be separated by at
least one blank or line terminator if the comma is omitted; and
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.
If a nonzero value
of Width is supplied, then
the components shall be separated by at
least one blank if the comma is omitted; and
exactly Width characters are read, or
the characters (possibly none) up to a line terminator, whichever comes
first (blanks are included in the count).
Returns, in the parameter Item, the value of type
Complex that corresponds to the input sequence.
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.
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);
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,
outputs a left parenthesis;
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;
outputs a comma;
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;
outputs
a right parenthesis.
procedure Get (From : in String;
Item : out Complex;
Last : out Positive);
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
file 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.
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.
procedure Put (To : out String;
Item : in Complex;
Aft : in Field := Default_Aft;
Exp : in Field := Default_Exp);
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,
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;
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.
The exception Text_IO.Layout_Error is raised if
the given string is too short to hold the formatted output.
Implementation Permissions
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.
Ada 2005 and 2012 Editions sponsored in part by Ada-Europe
