Ada Reference Manual (Ada 2022) — Legal Information

# A.10.9 Input-Output for Real Types

#### Static Semantics

1
The following procedures are defined in the generic packages Float_IO, Fixed_IO, and Decimal_IO, which have to be instantiated for the appropriate floating point, ordinary fixed point, or decimal fixed point type respectively (indicated by Num in the specifications).
2
Values are output as decimal literals without low line characters. The format of each value output consists of a Fore field, a decimal point, an Aft field, and (if a nonzero Exp parameter is supplied) the letter E and an Exp field. The two possible formats thus correspond to:
3
Fore . Aft
4
and to:
5
Fore . Aft E Exp
6
without any spaces between these fields. The Fore field may include leading spaces, and a minus sign for negative values. The Aft field includes only decimal digits (possibly with trailing zeros). The Exp field includes the sign (plus or minus) and the exponent (possibly with leading zeros).
7
For floating point types, the default lengths of these fields are defined by the following variables that are declared in the generic package Float_IO:
8
Default_Fore : Field := 2;
Default_Aft : Field := Num'Digits-1;
Default_Exp : Field := 3;
9
For ordinary or decimal fixed point types, the default lengths of these fields are defined by the following variables that are declared in the generic packages Fixed_IO and Decimal_IO, respectively:
10
Default_Fore : Field := Num'Fore;
Default_Aft : Field := Num'Aft;
Default_Exp : Field := 0;
11
The following procedures are provided:
12
procedure Get(File : in File_Type; Item : out Num; Width : in Field := 0);
procedure Get(Item : out Num; Width : in Field := 0);
13
If the value of the parameter Width is zero, skips any leading blanks, line terminators, or page terminators, then reads the longest possible sequence of characters matching the syntax of any of the following (see 2.4):
14
[+|–]numeric_literal
15
[+|–]numeral.[exponent]
16
[+|–].numeral[exponent]
17
[+|–]base#based_numeral.#[exponent]
18
[+|–]base#.based_numeral#[exponent]
19
If a nonzero value of Width is supplied, then exactly Width characters are input, or the characters (possibly none) up to a line terminator, whichever comes first; any skipped leading blanks are included in the count.
20
Returns in the parameter Item the value of type Num that corresponds to the sequence input, preserving the sign (positive if none has been specified) of a zero value if Num is a floating point type and Num'Signed_Zeros is True.
21
The exception Data_Error is propagated if the sequence input does not have the required syntax or if the value obtained is not of the subtype Num.
22
procedure Put(File : in File_Type;
Item : in Num;
Fore : in Field := Default_Fore;
Aft : in Field := Default_Aft;
Exp : in Field := Default_Exp);
procedure Put(Item : in Num;
Fore : in Field := Default_Fore;
Aft : in Field := Default_Aft;
Exp : in Field := Default_Exp);
23
Outputs the value of the parameter Item as a decimal literal with the format defined by Fore, Aft and Exp. If the value is negative, or if Num is a floating point type where Num'Signed_Zeros is True and the value is a negatively signed zero, then a minus sign is included in the integer part. If Exp has the value zero, then the integer part to be output has as many digits as are needed to represent the integer part of the value of Item, overriding Fore if necessary, or consists of the digit zero if the value of Item has no integer part.
24
If Exp has a value greater than zero, then the integer part to be output has a single digit, which is nonzero except for the value 0.0 of Item.
25
In both cases, however, if the integer part to be output has fewer than Fore characters, including any minus sign, then leading spaces are first output to make up the difference. The number of digits of the fractional part is given by Aft, or is one if Aft equals zero. The value is rounded; a value of exactly one half in the last place is rounded away from zero.
26
If Exp has the value zero, there is no exponent part. If Exp has a value greater than zero, then the exponent part to be output has as many digits as are needed to represent the exponent part of the value of Item (for which a single digit integer part is used), and includes an initial sign (plus or minus). If the exponent part to be output has fewer than Exp characters, including the sign, then leading zeros precede the digits, to make up the difference. For the value 0.0 of Item, the exponent has the value zero.
27
procedure Get(From : in String; Item : out Num; Last : out Positive);
28
Reads a real value from the beginning of the given string, following the same rule as the Get procedure that reads a real value from a file, but treating the end of the string as a file terminator. Returns, in the parameter Item, the value of type Num that corresponds to the sequence input. Returns in Last the index value such that From(Last) is the last character read.
29
The exception Data_Error is propagated if the sequence input does not have the required syntax, or if the value obtained is not of the subtype Num.
30
procedure Put(To : out String;
Item : in Num;
Aft : in Field := Default_Aft;
Exp : in Field := Default_Exp);
31
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 the string, including any leading spaces.
32
Float_Text_IO is a library package that is a nongeneric equivalent to Text_IO.Float_IO for the predefined type Float:
33
with Ada.Text_IO;
package Ada.Float_Text_IO is new Ada.Text_IO.Float_IO(Float);
34
For each predefined floating point type, a nongeneric equivalent to Text_IO.Float_IO is provided, with names such as Ada.Long_Float_Text_IO.

#### Implementation Permissions

35
An implementation may extend Get and Put for floating point types to support special values such as infinities and NaNs.
36/5
The implementation of Put may produce an output value with no greater accuracy than that which is supported for the base subtype. The additional accuracy, if any, of the value produced by Put when the number of requested digits in the integer and fractional parts exceeds the required accuracy is implementation defined.
37/5
The nongeneric equivalent packages can be actual instantiations of the generic package for the appropriate predefined type, though that is not required.
38
NOTE 1 For an item with a positive value, if output to a string exactly fills the string without leading spaces, then output of the corresponding negative value will propagate Layout_Error.
39
NOTE 2 The rules for the Value attribute (see 3.5) and the rules for Get are based on the same set of formats.

#### Examples

40/5
Examples of use of an instantiation of Text_IO.Float_IO:
41
package Real_IO is new Float_IO(Real); use Real_IO;
-- default format used at instantiation, Default_Exp = 3
42
X : Real := -123.4567; -- digits 8 (see 3.5.7)
43
Put(X); -- default format "–​1.2345670E+02"
Put(X, Fore => 5, Aft => 3, Exp => 2); -- "bbb–​1.235E+2"
Put(X, 5, 3, 0); -- "b–​123.457"

Ada 2005 and 2012 Editions sponsored in part by Ada-Europe