Next: , Previous: G.1.2, Up: G.1


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;

9.1/2
{00328AI95−00328−01} 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. Non−generic 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.

9.a/2

Reason: The nongeneric equivalents are provided to allow the programmer to construct simple mathematical applications without being required to understand and use generics.

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/00928652/0092} {00029AI95−00029−01} 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

13

14

15

15.1

If a nonzero value of Width is supplied, then

16

17

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

23

24

25

26

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/2

{00434AI95−00434−01} 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.

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

33

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.

Extensions to Ada 95

35.a/2

{00328AI95−00328−01} {extensions to Ada 95} Nongeneric equivalents for Text_IO.Complex_IO are added, to be consistent with all other language−defined Numerics generic packages.
Wording Changes from Ada 95

35.b/2

{8652/00928652/0092} {00029AI95−00029−01} Corrigendum: Clarified that the syntax of values read by Complex_IO is the same as that read by Text_IO.Float_IO.