DocAda Light by KSCE - G.1.3 Complex Input-Output

DocAda^(tm) is a productivity tool of KSCE

| | | |
About DocAda Light: Preface / Preliminary / Help / TOC / Copyright
DocAda Online at the Ada Home: Complete RM95 / Updates / News

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 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; optionally, the pair of components may be separated by a comma and/or surrounded by a pair of parentheses. 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.

    
       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.

About DocAda Light: Preface / Preliminary / Help / TOC / Copyright
DocAda Online at the Ada Home: Complete RM95 / Updates / News
| | | |