G.1.3 Complex Input-Output

Contents | Index | Previous | Next

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

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.

Contents | Index | Previous | Next Legal