A.10 Text Input-Output
This Reference Manual output has not been verified, and may contain omissions or errors. Report any problems on the tracking issue
Static Semantics
1/5This subclause describes the package Text_IO, which provides facilities for input and output in human-readable form. Each file is read or written sequentially, as a sequence of characters grouped into lines, and as a sequence of lines grouped into pages. The specification of the package is given below in A.10.1.
The facilities for file management given above, in A.8.2 and A.8.3, are available for text input-output. In place of Read and Write, however, there are procedures Get and Put that input values of suitable types from text files, and output values to them. These values are provided to the Put procedures, and returned by the Get procedures, in a parameter Item. Several overloaded procedures of these names exist, for different types of Item. These Get procedures analyze the input sequences of characters based on lexical elements (see Clause 2) and return the corresponding values; the Put procedures output the given values as appropriate lexical elements. Procedures Get and Put are also available that input and output individual characters treated as character values rather than as lexical elements. Related to character input are procedures to look ahead at the next character without reading it, and to read a character “immediately” without waiting for an end-of-line to signal availability.
In addition to the procedures Get and Put for numeric and enumeration types of Item that operate on text files, analogous procedures are provided that read from and write to a parameter of type String. These procedures perform the same analysis and composition of character sequences as their counterparts which have a file parameter.
For all Get and Put procedures that operate on text files, and for many other subprograms, there are forms with and without a file parameter. Each such Get procedure operates on an input file, and each such Put procedure operates on an output file. If no file is specified, a default input file or a default output file is used.
At the beginning of program execution the default input and output files are the so-called standard input file and standard output file. These files are open, have respectively the current modes In_File and Out_File, and are associated with two implementation-defined external files. Procedures are provided to change the current default input file and the current default output file.
The external files associated with the standard input, standard output, and standard error files.
{8652/0113} The default input file and default output file are not the names of distinct file objects, but rather the role played by one or more (other) file object(s). Thus, they generally will be implemented as accesses to another file object. An implementation that implements them by copying them is incorrect.
At the beginning of program execution a default file for program-dependent error-related text output is the so-called standard error file. This file is open, has the current mode Out_File, and is associated with an implementation-defined external file. A procedure is provided to change the current default error file.
From a logical point of view, a text file is a sequence of pages, a page is a sequence of lines, and a line is a sequence of characters; the end of a line is marked by a line terminator; the end of a page is marked by the combination of a line terminator immediately followed by a page terminator; and the end of a file is marked by the combination of a line terminator immediately followed by a page terminator and then a file terminator. Terminators are generated during output; either by calls of procedures provided expressly for that purpose; or implicitly as part of other operations, for example, when a bounded line length, a bounded page length, or both, have been specified for a file.
The actual nature of terminators is not defined by the language and hence depends on the implementation. Although terminators are recognized or generated by certain of the procedures that follow, they are not necessarily implemented as characters or as sequences of characters. Whether they are characters (and if so which ones) in any particular implementation is not of concern to a user who neither explicitly outputs nor explicitly inputs control characters. The effect of input (Get) or output (Put) of control characters (other than horizontal tabulation) is not specified by the language.
The characters of a line are numbered, starting from one; the number of a character is called its column number. For a line terminator, a column number is also defined: it is one more than the number of characters in the line. The lines of a page, and the pages of a file, are similarly numbered. The current column number is the column number of the next character or line terminator to be transferred. The current line number is the number of the current line. The current page number is the number of the current page. These numbers are values of the subtype Positive_Count of the type Count (by convention, the value zero of the type Count is used to indicate special conditions).
type Count is range 0 .. implementation-defined;
subtype Positive_Count is Count range 1 .. Count'Last;
For an output file or an append file, a maximum line length can be specified and a maximum page length can be specified. If a value to be output cannot fit on the current line, for a specified maximum line length, then a new line is automatically started before the value is output; if, further, this new line cannot fit on the current page, for a specified maximum page length, then a new page is automatically started before the value is output. Functions are provided to determine the maximum line length and the maximum page length. When a file is opened with mode Out_File or Append_File, both values are zero: by convention, this means that the line lengths and page lengths are unbounded. (Consequently, output consists of a single line if the subprograms for explicit control of line and page structure are not used.) The constant Unbounded is provided for this purpose.
Extensions to Ada 83
Append_File is new in Ada 95.
A.10.1 The Package Text_IO
Static Semantics
1The library package Text_IO has the following declaration:
with Ada.IO_Exceptions;
package Ada.Text_IO
with Global => in out synchronized is
3
type File_Type is limited private;
4
type File_Mode is (In_File, Out_File, Append_File);
5
type Count is range 0 .. implementation-defined;
subtype Positive_Count is Count range 1 .. Count'Last;
Unbounded : constant Count := 0; -- line and page length
6
subtype Field is Integer range 0 .. implementation-defined;
subtype Number_Base is Integer range 2 .. 16;
7
type Type_Set is (Lower_Case, Upper_Case);
8
-- File Management
9
procedure Create (File : in out File_Type;
Mode : in File_Mode := Out_File;
Name : in String := "";
Form : in String := "");
10
procedure Open (File : in out File_Type;
Mode : in File_Mode;
Name : in String;
Form : in String := "");
11
procedure Close (File : in out File_Type);
procedure Delete (File : in out File_Type);
procedure Reset (File : in out File_Type; Mode : in File_Mode);
procedure Reset (File : in out File_Type);
12
function Mode (File : in File_Type) return File_Mode;
function Name (File : in File_Type) return String;
function Form (File : in File_Type) return String;
13
function Is_Open(File : in File_Type) return Boolean;
14
-- Control of default input and output files
15
procedure Set_Input (File : in File_Type);
procedure Set_Output(File : in File_Type);
procedure Set_Error (File : in File_Type);
16
function Standard_Input return File_Type;
function Standard_Output return File_Type;
function Standard_Error return File_Type;
17
function Current_Input return File_Type;
function Current_Output return File_Type;
function Current_Error return File_Type;
18
type File_Access is access constant File_Type;
19
function Standard_Input return File_Access;
function Standard_Output return File_Access;
function Standard_Error return File_Access;
20
function Current_Input return File_Access;
function Current_Output return File_Access;
function Current_Error return File_Access;
21/5
{8652/0051} --Buffer control
procedure Flush (File : in File_Type)
with Global => overriding in out File;
procedure Flush
with Global => in out all;
22
-- Specification of line and page lengths
23/5
procedure Set_Line_Length(File : in File_Type; To : in Count)
with Global => overriding in out File;
procedure Set_Line_Length(To : in Count)
with Global => in out all;
24/5
procedure Set_Page_Length(File : in File_Type; To : in Count)
with Global => overriding in out File;
procedure Set_Page_Length(To : in Count)
with Global => in out all;
25/5
function Line_Length(File : in File_Type) return Count;
function Line_Length return Count
with Global => in all;
26/5
function Page_Length(File : in File_Type) return Count;
function Page_Length return Count
with Global => in all;
27
-- Column, Line, and Page Control
28/5
procedure New_Line (File : in File_Type;
Spacing : in Positive_Count := 1)
with Global => overriding in out File;
procedure New_Line (Spacing : in Positive_Count := 1)
with Global => in out all;
29/5
procedure Skip_Line (File : in File_Type;
Spacing : in Positive_Count := 1)
with Global => overriding in out File;
procedure Skip_Line (Spacing : in Positive_Count := 1)
with Global => in out all;
30/5
function End_Of_Line(File : in File_Type) return Boolean;
function End_Of_Line return Boolean;
31/5
procedure New_Page (File : in File_Type)
with Global => overriding in out File;
procedure New_Page
with Global => in out all;
32/5
procedure Skip_Page (File : in File_Type)
with Global => overriding in out File;
procedure Skip_Page
with Global => in out all;
33/5
function End_Of_Page(File : in File_Type) return Boolean;
function End_Of_Page return Boolean
with Global => in all;
34/5
function End_Of_File(File : in File_Type) return Boolean;
function End_Of_File return Boolean
with Global => in all;
35/5
procedure Set_Col (File : in File_Type; To : in Positive_Count)
with Global => overriding in out File;
procedure Set_Col (To : in Positive_Count)
with Global => in out all;
36/5
procedure Set_Line(File : in File_Type; To : in Positive_Count)
with Global => overriding in out File;
procedure Set_Line(To : in Positive_Count)
with Global => in out all;
37/5
function Col (File : in File_Type) return Positive_Count;
function Col return Positive_Count
with Global => in all;
38/5
function Line(File : in File_Type) return Positive_Count;
function Line return Positive_Count
with Global => in all;
39/5
function Page(File : in File_Type) return Positive_Count;
function Page return Positive_Count
with Global => in all;
40
-- Character Input-Output
41/5
procedure Get(File : in File_Type; Item : out Character)
with Global => overriding in out File;
procedure Get(Item : out Character)
with Global => in out all;
42/5
procedure Put(File : in File_Type; Item : in Character)
with Global => overriding in out File;
procedure Put(Item : in Character)
with Global => in out all;
43/5
procedure Look_Ahead (File : in File_Type;
Item : out Character;
End_Of_Line : out Boolean)
with Global => overriding in out File;
procedure Look_Ahead (Item : out Character;
End_Of_Line : out Boolean)
with Global => in out all;
44/5
procedure Get_Immediate(File : in File_Type;
Item : out Character)
with Global => overriding in out File;
procedure Get_Immediate(Item : out Character)
with Global => in out all;
45/5
procedure Get_Immediate(File : in File_Type;
Item : out Character;
Available : out Boolean)
with Global => overriding in out File;
procedure Get_Immediate(Item : out Character;
Available : out Boolean)
with Global => in out all;
46
-- String Input-Output
47/5
procedure Get(File : in File_Type; Item : out String)
with Global => overriding in out File;
procedure Get(Item : out String)
with Global => in out all;
48/5
procedure Put(File : in File_Type; Item : in String)
with Global => overriding in out File;
procedure Put(Item : in String)
with Global => in out all;
49/5
procedure Get_Line(File : in File_Type;
Item : out String;
Last : out Natural)
with Global => overriding in out File;
procedure Get_Line(Item : out String; Last : out Natural)
with Global => in out all;
49.1/5
function Get_Line(File : in File_Type) return String
with Global => overriding in out File;
function Get_Line return String
with Global => in out all;
50/5
procedure Put_Line(File : in File_Type; Item : in String)
with Global => overriding in out File;
procedure Put_Line(Item : in String)
with Global => in out all;
51
-- Generic packages for Input-Output of Integer Types
52
generic
type Num is range <>;
package Integer_IO is
53
Default_Width : Field := Num'Width;
Default_Base : Number_Base := 10;
54/5
procedure Get(File : in File_Type;
Item : out Num;
Width : in Field := 0)
with Global => overriding in out File;
procedure Get(Item : out Num;
Width : in Field := 0)
with Global => in out all;
55/5
procedure Put(File : in File_Type;
Item : in Num;
Width : in Field := Default_Width;
Base : in Number_Base := Default_Base)
with Global => overriding in out File;
procedure Put(Item : in Num;
Width : in Field := Default_Width;
Base : in Number_Base := Default_Base)
with Global => in out all;
procedure Get(From : in String;
Item : out Num;
Last : out Positive)
with Nonblocking;
procedure Put(To : out String;
Item : in Num;
Base : in Number_Base := Default_Base)
with Nonblocking;
56
end Integer_IO;
57
generic
type Num is mod <>;
package Modular_IO is
58
Default_Width : Field := Num'Width;
Default_Base : Number_Base := 10;
59/5
procedure Get(File : in File_Type;
Item : out Num;
Width : in Field := 0)
with Global => overriding in out File;
procedure Get(Item : out Num;
Width : in Field := 0)
with Global => in out all;
60/5
procedure Put(File : in File_Type;
Item : in Num;
Width : in Field := Default_Width;
Base : in Number_Base := Default_Base)
with Global => overriding in out File;
procedure Put(Item : in Num;
Width : in Field := Default_Width;
Base : in Number_Base := Default_Base)
with Global => in out all;
procedure Get(From : in String;
Item : out Num;
Last : out Positive)
with Nonblocking;
procedure Put(To : out String;
Item : in Num;
Base : in Number_Base := Default_Base)
with Nonblocking;
61
end Modular_IO;
62
-- Generic packages for Input-Output of Real Types
63
generic
type Num is digits <>;
package Float_IO is
64
Default_Fore : Field := 2;
Default_Aft : Field := Num'Digits-1;
Default_Exp : Field := 3;
65/5
procedure Get(File : in File_Type;
Item : out Num;
Width : in Field := 0)
with Global => overriding in out File;
procedure Get(Item : out Num;
Width : in Field := 0)
with Global => in out all;
66/5
procedure Put(File : in File_Type;
Item : in Num;
Fore : in Field := Default_Fore;
Aft : in Field := Default_Aft;
Exp : in Field := Default_Exp)
with Global => overriding in out File;
procedure Put(Item : in Num;
Fore : in Field := Default_Fore;
Aft : in Field := Default_Aft;
Exp : in Field := Default_Exp)
with Global => in out all;
67/5
procedure Get(From : in String;
Item : out Num;
Last : out Positive)
with Nonblocking;
procedure Put(To : out String;
Item : in Num;
Aft : in Field := Default_Aft;
Exp : in Field := Default_Exp)
with Nonblocking;
end Float_IO;
68
generic
type Num is delta <>;
package Fixed_IO is
69
Default_Fore : Field := Num'Fore;
Default_Aft : Field := Num'Aft;
Default_Exp : Field := 0;
70/5
procedure Get(File : in File_Type;
Item : out Num;
Width : in Field := 0)
with Global => overriding in out File;
procedure Get(Item : out Num;
Width : in Field := 0)
with Global => in out all;
71/5
procedure Put(File : in File_Type;
Item : in Num;
Fore : in Field := Default_Fore;
Aft : in Field := Default_Aft;
Exp : in Field := Default_Exp)
with Global => overriding in out File;
procedure Put(Item : in Num;
Fore : in Field := Default_Fore;
Aft : in Field := Default_Aft;
Exp : in Field := Default_Exp)
with Global => in out all;
72/5
procedure Get(From : in String;
Item : out Num;
Last : out Positive)
with Nonblocking;
procedure Put(To : out String;
Item : in Num;
Aft : in Field := Default_Aft;
Exp : in Field := Default_Exp)
with Nonblocking;
end Fixed_IO;
73
generic
type Num is delta <> digits <>;
package Decimal_IO is
74
Default_Fore : Field := Num'Fore;
Default_Aft : Field := Num'Aft;
Default_Exp : Field := 0;
75/5
procedure Get(File : in File_Type;
Item : out Num;
Width : in Field := 0)
with Global => overriding in out File;
procedure Get(Item : out Num;
Width : in Field := 0)
with Global => in out all;
76/5
procedure Put(File : in File_Type;
Item : in Num;
Fore : in Field := Default_Fore;
Aft : in Field := Default_Aft;
Exp : in Field := Default_Exp)
with Global => overriding in out File;
procedure Put(Item : in Num;
Fore : in Field := Default_Fore;
Aft : in Field := Default_Aft;
Exp : in Field := Default_Exp)
with Global => in out all;
77/5
procedure Get(From : in String;
Item : out Num;
Last : out Positive)
with Nonblocking;
procedure Put(To : out String;
Item : in Num;
Aft : in Field := Default_Aft;
Exp : in Field := Default_Exp)
with Nonblocking;
end Decimal_IO;
78
-- Generic package for Input-Output of Enumeration Types
79
generic
type Enum is (<>);
package Enumeration_IO is
80
Default_Width : Field := 0;
Default_Setting : Type_Set := Upper_Case;
81/5
procedure Get(File : in File_Type;
Item : out Enum)
with Global => overriding in out File;
procedure Get(Item : out Enum)
with Global => in out all;
82/5
procedure Put(File : in File_Type;
Item : in Enum;
Width : in Field := Default_Width;
Set : in Type_Set := Default_Setting)
with Global => overriding in out File;
procedure Put(Item : in Enum;
Width : in Field := Default_Width;
Set : in Type_Set := Default_Setting)
with Global => in out all;
83/5
procedure Get(From : in String;
Item : out Enum;
Last : out Positive)
with Nonblocking;
procedure Put(To : out String;
Item : in Enum;
Set : in Type_Set := Default_Setting)
with Nonblocking;
end Enumeration_IO;
84
-- Exceptions
85/5
Status_Error : exception renames IO_Exceptions.Status_Error;
Mode_Error : exception renames IO_Exceptions.Mode_Error;
Name_Error : exception renames IO_Exceptions.Name_Error;
Use_Error : exception renames IO_Exceptions.Use_Error;
Device_Error : exception renames IO_Exceptions.Device_Error;
End_Error : exception renames IO_Exceptions.End_Error;
Data_Error : exception renames IO_Exceptions.Data_Error;
Layout_Error : exception renames IO_Exceptions.Layout_Error;
85.1/5
package Wide_File_Names is
85.2/5
-- File management
85.3/5
procedure Create (File : in out File_Type;
Mode : in File_Mode := Out_File;
Name : in Wide_String := "";
Form : in Wide_String := "");
85.4/5
procedure Open (File : in out File_Type;
Mode : in File_Mode;
Name : in Wide_String;
Form : in Wide_String := "");
85.5/5
function Name (File : in File_Type) return Wide_String;
85.6/5
function Form (File : in File_Type) return Wide_String;
85.7/5
end Wide_File_Names;
85.8/5
package Wide_Wide_File_Names is
85.9/5
-- File management
85.10/5
procedure Create (File : in out File_Type;
Mode : in File_Mode := Out_File;
Name : in Wide_Wide_String := "";
Form : in Wide_Wide_String := "");
85.11/5
procedure Open (File : in out File_Type;
Mode : in File_Mode;
Name : in Wide_Wide_String;
Form : in Wide_Wide_String := "");
85.12/5
function Name (File : in File_Type) return Wide_Wide_String;
85.13/5
function Form (File : in File_Type) return Wide_Wide_String;
85.14/5
end Wide_Wide_File_Names;
85.15/5
private
... -- not specified by the language
end Ada.Text_IO;
The type File_Type needs finalization (see 7.6).
Incompatibilities With Ada 83
Append_File is a new element of enumeration type File_Mode.
Extensions to Ada 83
Get_Immediate, Look_Ahead, the subprograms for dealing with standard error, the type File_Access and its associated subprograms, and the generic packages Modular_IO and Decimal_IO are new in Ada 95.
Incompatibilities With Ada 95
Amendment Text_IO.File_Type is defined to need finalization. If the restriction No_Nested_Finalization (see D.7) applies to the partition, and File_Type does not have a controlled part, it will not be allowed in local objects in Ada 2005 whereas it would be allowed in original Ada 95. Such code is not portable, as another Ada compiler may have a controlled part in File_Type, and thus would be illegal.
Wording Changes from Ada 95
{8652/0051} Corrigendum: Corrected the parameter mode of Flush; otherwise it could not be used on Standard_Output.
The Text_IO.Get_Line functions are new; they are described in A.10.7, “Input-Output of Characters and Strings”.
Incompatibilities With Ada 2012
The Wide_File_Names and Wide_Wide_File_Names nested packages are newly added to Ada.Text_IO. Therefore, a use clause conflict is possible; see the introduction of Annex A for more on this topic.
A.10.2 Text File Management
Static Semantics
1/5The only allowed file modes for text files are the modes In_File, Out_File, and Append_File. The subprograms given in A.8.2 for the control of external files, and the function End_Of_File given in A.8.3 for sequential input-output, are also available for text files. There is also a version of End_Of_File that refers to the current default input file. For text files, the procedures have the following additional effects:
- For the procedures Create and Open: After a file with mode Out_File or Append_File is opened, the page length and line length are unbounded (both have the conventional value zero). After a file (of any mode) is opened, the current column, current line, and current page numbers are set to one. If the mode is Append_File, it is implementation defined whether a page terminator will separate preexisting text in the file from the new text to be written.
For a file with mode Append_File, although it may seem more sensible for Open to set the current column, line, and page number based on the number of pages in the file, the number of lines on the last page, and the number of columns in the last line, we rejected this approach because of implementation costs; it would require the implementation to scan the file before doing the append, or to do processing that would be equivalent in effect.
For similar reasons, there is no requirement to erase the last page terminator of the file, nor to insert an explicit page terminator in the case when the final page terminator of a file is represented implicitly by the implementation.
- For the procedure Close: If the file has the current mode Out_File or Append_File, has the effect of calling New_Page, unless the current page is already terminated; then outputs a file terminator.
- For the procedure Reset: If the file has the current mode Out_File or Append_File, has the effect of calling New_Page, unless the current page is already terminated; then outputs a file terminator. The current column, line, and page numbers are set to one, and the line and page lengths to Unbounded. If the new mode is Append_File, it is implementation defined whether a page terminator will separate preexisting text in the file from the new text to be written.
The behavior of Reset should be similar to closing a file and reopening it with the given mode
The exception Mode_Error is propagated by the procedure Reset upon an attempt to change the mode of a file that is the current default input file, the current default output file, or the current default error file.
NOTE An implementation can define the Form parameter of Create and Open to control effects including the following:
- the interpretation of line and column numbers for an interactive file, and
- the interpretation of text formats in a file created by a foreign program.
A.10.3 Default Input, Output, and Error Files
Static Semantics
1The following subprograms provide for the control of the particular default files that are used when a file parameter is omitted from a Get, Put, or other operation of text input-output described below, or when application-dependent error-related text is to be output.
procedure Set_Input(File : in File_Type);
Operates on a file of mode In_File. Sets the current default input file to File.
The exception Status_Error is propagated if the given file is not open. The exception Mode_Error is propagated if the mode of the given file is not In_File.
procedure Set_Output(File : in File_Type);
procedure Set_Error (File : in File_Type);
Each operates on a file of mode Out_File or Append_File. Set_Output sets the current default output file to File. Set_Error sets the current default error file to File. The exception Status_Error is propagated if the given file is not open. The exception Mode_Error is propagated if the mode of the given file is not Out_File or Append_File.
function Standard_Input return File_Type;
function Standard_Input return File_Access;
Returns the standard input file (see A.10), or an access value designating the standard input file, respectively.
function Standard_Output return File_Type;
function Standard_Output return File_Access;
Returns the standard output file (see A.10) or an access value designating the standard output file, respectively.
function Standard_Error return File_Type;
function Standard_Error return File_Access;
{8652/0052} Returns the standard error file (see A.10), or an access value designating the standard error file, respectively.
The Form strings implicitly associated with the opening of Standard_Input, Standard_Output, and Standard_Error at the start of program execution are implementation defined.
function Current_Input return File_Type;
function Current_Input return File_Access;
Returns the current default input file, or an access value designating the current default input file, respectively.
function Current_Output return File_Type;
function Current_Output return File_Access;
Returns the current default output file, or an access value designating the current default output file, respectively.
function Current_Error return File_Type;
function Current_Error return File_Access;
Returns the current default error file, or an access value designating the current default error file, respectively.
{8652/0051} procedure Flush (File : in File_Type);
procedure Flush;
[The effect of Flush is the same as the corresponding subprogram in Sequential_IO (see A.8.2).] If File is not explicitly specified, Current_Output is used.
For the purpose of determining whether concurrent calls on text input-output subprograms are required to perform as specified, subprograms that implicitly operate on one of the default input-output files are considered to have a parameter of Current_Input or Current_Output (as appropriate). The result of Current_Output is considered to be overlapping with the file given to the latest call of Set_Output (or Standard_Output if Set_Output hasn't been called); a corresponding consideration applies to the result of Current_Input. See the introduction of Annex A for details.
Erroneous Execution
22/1{8652/0053} The execution of a program is erroneous if it invokes an operation on a current default input, default output, or default error file, and if the corresponding file object is closed or no longer exists.
{8652/0053} Closing a default file, then setting the default file to another open file before accessing it is not erroneous.
This paragraph was deleted.{8652/0053}
NOTE 1 The standard input, standard output, and standard error files cannot be opened, closed, reset, or deleted, because the parameter File of the corresponding procedures has the mode in out.
NOTE 2 The standard input, standard output, and standard error files are different file objects, but not necessarily different external files.
Wording Changes from Ada 95
{8652/0051} Corrigendum: Corrected the parameter mode of Flush; otherwise it could not be used on Standard_Output.
{8652/0053} Corrigendum: Clarified that execution is erroneous only when a closed default file is accessed.
Wording Changes from Ada 2012
Corrigendum: Moved the definition of Flush to A.8.2, as all input-output packages now have it.
A.10.4 Specification of Line and Page Lengths
Static Semantics
1/5The subprograms described in this subclause are concerned with the line and page structure of a file of mode Out_File or Append_File. They operate either on the file given as the first parameter, or, in the absence of such a file parameter, on the current default output file. They provide for output of text with a specified maximum line length or page length. In these cases, line and page terminators are output implicitly and automatically when necessary. When line and page lengths are unbounded (that is, when they have the conventional value zero), as in the case of a newly opened file, new lines and new pages are only started when explicitly called for.
In all cases, the exception Status_Error is propagated if the file to be used is not open; the exception Mode_Error is propagated if the mode of the file is not Out_File or Append_File.
procedure Set_Line_Length(File : in File_Type; To : in Count);
procedure Set_Line_Length(To : in Count);
Sets the maximum line length of the specified output or append file to the number of characters specified by To. The value zero for To specifies an unbounded line length.
The setting does not affect the lengths of lines in the existing file, rather it only influences subsequent output operations.
The exception Use_Error is propagated if the specified line length is inappropriate for the associated external file.
procedure Set_Page_Length(File : in File_Type; To : in Count);
procedure Set_Page_Length(To : in Count);
Sets the maximum page length of the specified output or append file to the number of lines specified by To. The value zero for To specifies an unbounded page length.
The exception Use_Error is propagated if the specified page length is inappropriate for the associated external file.
function Line_Length(File : in File_Type) return Count;
function Line_Length return Count;
Returns the maximum line length currently set for the specified output or append file, or zero if the line length is unbounded.
function Page_Length(File : in File_Type) return Count;
function Page_Length return Count;
Returns the maximum page length currently set for the specified output or append file, or zero if the page length is unbounded.
A.10.5 Operations on Columns, Lines, and Pages
Static Semantics
1The subprograms described in this subclause provide for explicit control of line and page structure; they operate either on the file given as the first parameter, or, in the absence of such a file parameter, on the appropriate (input or output) current default file. The exception Status_Error is propagated by any of these subprograms if the file to be used is not open.
procedure New_Line(File : in File_Type; Spacing : in Positive_Count := 1);
procedure New_Line(Spacing : in Positive_Count := 1);
Operates on a file of mode Out_File or Append_File.
For a Spacing of one: Outputs a line terminator and sets the current column number to one. Then increments the current line number by one, except in the case that the current line number is already greater than or equal to the maximum page length, for a bounded page length; in that case a page terminator is output, the current page number is incremented by one, and the current line number is set to one.
For a Spacing greater than one, the above actions are performed Spacing times.
The exception Mode_Error is propagated if the mode is not Out_File or Append_File.
procedure Skip_Line(File : in File_Type; Spacing : in Positive_Count := 1);
procedure Skip_Line(Spacing : in Positive_Count := 1);
Operates on a file of mode In_File.
For a Spacing of one: Reads and discards all characters until a line terminator has been read, and then sets the current column number to one. If the line terminator is not immediately followed by a page terminator, the current line number is incremented by one. Otherwise, if the line terminator is immediately followed by a page terminator, then the page terminator is skipped, the current page number is incremented by one, and the current line number is set to one.
For a Spacing greater than one, the above actions are performed Spacing times.
The exception Mode_Error is propagated if the mode is not In_File. The exception End_Error is propagated if an attempt is made to read a file terminator.
function End_Of_Line(File : in File_Type) return Boolean;
function End_Of_Line return Boolean;
Operates on a file of mode In_File. Returns True if a line terminator or a file terminator is next; otherwise, returns False.
The exception Mode_Error is propagated if the mode is not In_File.
procedure New_Page(File : in File_Type);
procedure New_Page;
Operates on a file of mode Out_File or Append_File. Outputs a line terminator if the current line is not terminated, or if the current page is empty (that is, if the current column and line numbers are both equal to one). Then outputs a page terminator, which terminates the current page. Adds one to the current page number and sets the current column and line numbers to one.
The exception Mode_Error is propagated if the mode is not Out_File or Append_File.
procedure Skip_Page(File : in File_Type);
procedure Skip_Page;
Operates on a file of mode In_File. Reads and discards all characters and line terminators until a page terminator has been read. Then adds one to the current page number, and sets the current column and line numbers to one.
The exception Mode_Error is propagated if the mode is not In_File. The exception End_Error is propagated if an attempt is made to read a file terminator.
function End_Of_Page(File : in File_Type) return Boolean;
function End_Of_Page return Boolean;
Operates on a file of mode In_File. Returns True if the combination of a line terminator and a page terminator is next, or if a file terminator is next; otherwise, returns False.
The exception Mode_Error is propagated if the mode is not In_File.
function End_Of_File(File : in File_Type) return Boolean;
function End_Of_File return Boolean;
Operates on a file of mode In_File. Returns True if a file terminator is next, or if the combination of a line, a page, and a file terminator is next; otherwise, returns False.
The exception Mode_Error is propagated if the mode is not In_File.
The following subprograms provide for the control of the current position of reading or writing in a file. In all cases, the default file is the current output file.
procedure Set_Col(File : in File_Type; To : in Positive_Count);
procedure Set_Col(To : in Positive_Count);
If the file mode is Out_File or Append_File:
- If the value specified by To is greater than the current column number, outputs spaces, adding one to the current column number after each space, until the current column number equals the specified value. If the value specified by To is equal to the current column number, there is no effect. If the value specified by To is less than the current column number, has the effect of calling New_Line (with a spacing of one), then outputs (To – 1) spaces, and sets the current column number to the specified value.
- The exception Layout_Error is propagated if the value specified by To exceeds Line_Length when the line length is bounded (that is, when it does not have the conventional value zero).
If the file mode is In_File:
- Reads (and discards) individual characters, line terminators, and page terminators, until the next character to be read has a column number that equals the value specified by To; there is no effect if the current column number already equals this value. Each transfer of a character or terminator maintains the current column, line, and page numbers in the same way as a Get procedure (see A.10.6). (Short lines will be skipped until a line is reached that has a character at the specified column position.)
- The exception End_Error is propagated if an attempt is made to read a file terminator.
procedure Set_Line(File : in File_Type; To : in Positive_Count);
procedure Set_Line(To : in Positive_Count);
If the file mode is Out_File or Append_File:
- If the value specified by To is greater than the current line number, has the effect of repeatedly calling New_Line (with a spacing of one), until the current line number equals the specified value. If the value specified by To is equal to the current line number, there is no effect. If the value specified by To is less than the current line number, has the effect of calling New_Page followed, if To is greater than 1, by a call of New_Line with a spacing equal to (To – 1).
- The exception Layout_Error is propagated if the value specified by To exceeds Page_Length when the page length is bounded (that is, when it does not have the conventional value zero).
If the mode is In_File:
- Has the effect of repeatedly calling Skip_Line (with a spacing of one), until the current line number equals the value specified by To; there is no effect if the current line number already equals this value. (Short pages will be skipped until a page is reached that has a line at the specified line position.)
- The exception End_Error is propagated if an attempt is made to read a file terminator.
function Col(File : in File_Type) return Positive_Count;
function Col return Positive_Count;
Returns the current column number.
The exception Layout_Error is propagated if this number exceeds Count'Last.
function Line(File : in File_Type) return Positive_Count;
function Line return Positive_Count;
Returns the current line number.
The exception Layout_Error is propagated if this number exceeds Count'Last.
function Page(File : in File_Type) return Positive_Count;
function Page return Positive_Count;
Returns the current page number.
The exception Layout_Error is propagated if this number exceeds Count'Last.
The column number, line number, or page number are allowed to exceed Count'Last (as a consequence of the input or output of sufficiently many characters, lines, or pages). These events do not cause any exception to be propagated. However, a call of Col, Line, or Page propagates the exception Layout_Error if the corresponding number exceeds Count'Last.
NOTE A page terminator is always skipped whenever the preceding line terminator is skipped. An implementation can represent the combination of these terminators by a single character, provided that it is properly recognized on input.
Inconsistencies With Ada 2005
Fixed a glitch in Set_Line such that we could have called New_Line(0), which would have to raise Constraint_Error. It's now defined to work. The bug occurred in Ada 95 and Ada 2005. It's very unlikely that any real programs depend on this exception being raised.
A.10.6 Get and Put Procedures
Static Semantics
1The procedures Get and Put for items of the type Character, String, numeric types, and enumeration types are described in subsequent subclauses. Features of these procedures that are common to most of these types are described in this subclause. The Get and Put procedures for items of type Character and String deal with individual character values; the Get and Put procedures for numeric and enumeration types treat the items as lexical elements.
All procedures Get and Put have forms with a file parameter, written first. Where this parameter is omitted, the appropriate (input or output) current default file is understood to be specified. Each procedure Get operates on a file of mode In_File. Each procedure Put operates on a file of mode Out_File or Append_File.
All procedures Get and Put maintain the current column, line, and page numbers of the specified file: the effect of each of these procedures upon these numbers is the result of the effects of individual transfers of characters and of individual output or skipping of terminators. Each transfer of a character adds one to the current column number. Each output of a line terminator sets the current column number to one and adds one to the current line number. Each output of a page terminator sets the current column and line numbers to one and adds one to the current page number. For input, each skipping of a line terminator sets the current column number to one and adds one to the current line number; each skipping of a page terminator sets the current column and line numbers to one and adds one to the current page number. Similar considerations apply to the procedures Get_Line, Put_Line, and Set_Col.
Several Get and Put procedures, for numeric and enumeration types, have format parameters which specify field lengths; these parameters are of the nonnegative subtype Field of the type Integer.
Input-output of enumeration values uses the syntax of the corresponding lexical elements. Any Get procedure for an enumeration type begins by skipping any leading blanks, or line or page terminators. A blank is defined as a space or a horizontal tabulation character. Next, characters are input only so long as the sequence input is an initial sequence of an identifier or of a character literal (in particular, input ceases when a line terminator is encountered). The character or line terminator that causes input to cease remains available for subsequent input.
For a numeric type, the Get procedures have a format parameter called Width. If the value given for this parameter is zero, the Get procedure proceeds in the same manner as for enumeration types, but using the syntax of numeric literals instead of that of enumeration literals. If a nonzero value is given, then exactly Width characters are input, or the characters up to a line terminator, whichever comes first; any skipped leading blanks are included in the count. The syntax used for numeric literals is an extended syntax that allows a leading sign (but no intervening blanks, or line or page terminators) and that also allows (for real types) an integer literal as well as forms that have digits only before the point or only after the point.
Any Put procedure, for an item of a numeric or an enumeration type, outputs the value of the item as a numeric literal, identifier, or character literal, as appropriate. This is preceded by leading spaces if required by the format parameters Width or Fore (as described in later subclauses), and then a minus sign for a negative value; for an enumeration type, the spaces follow instead of leading. The format given for a Put procedure is overridden if it is insufficiently wide, by using the minimum necessary width.
Two further cases arise for Put procedures for numeric and enumeration types, if the line length of the specified output file is bounded (that is, if it does not have the conventional value zero). If the number of characters to be output does not exceed the maximum line length, but is such that they cannot fit on the current line, starting from the current column, then (in effect) New_Line is called (with a spacing of one) before output of the item. Otherwise, if the number of characters exceeds the maximum line length, then the exception Layout_Error is propagated and nothing is output.
The exception Status_Error is propagated by any of the procedures Get, Get_Line, Put, and Put_Line if the file to be used is not open. The exception Mode_Error is propagated by the procedures Get and Get_Line if the mode of the file to be used is not In_File; and by the procedures Put and Put_Line, if the mode is not Out_File or Append_File.
The exception End_Error is propagated by a Get procedure if an attempt is made to skip a file terminator. The exception Data_Error is propagated by a Get procedure if the sequence finally input is not a lexical element corresponding to the type, in particular if no characters were input; for this test, leading blanks are ignored; for an item of a numeric type, when a sign is input, this rule applies to the succeeding numeric literal. The exception Layout_Error is propagated by a Put procedure that outputs to a parameter of type String, if the length of the actual string is insufficient for the output of the item.
Examples
11/5In the examples, here and in A.10.8 and A.10.9, the string quotes and the lower case letter b are not transferred: they are shown only to reveal the layout and spaces.
N : Integer;
...
Get(N);
13
-- Characters at input Sequence input Value of N
-- bb–12535b –12535 –12535
-- bb12_535e1b 12_535e1 125350
-- bb12_535e; 12_535e (none) Data_Error raised
Example of overridden width parameter:
Put(Item => -23, Width => 2); -- "–23"
Wording Changes from Ada 95
A.10.7 Input-Output of Characters and Strings
Static Semantics
1For an item of type Character the following procedures are provided:
procedure Get(File : in File_Type; Item : out Character);
procedure Get(Item : out Character);
After skipping any line terminators and any page terminators, reads the next character from the specified input file and returns the value of this character in the out parameter Item.
The exception End_Error is propagated if an attempt is made to skip a file terminator.
procedure Put(File : in File_Type; Item : in Character);
procedure Put(Item : in Character);
If the line length of the specified output file is bounded (that is, does not have the conventional value zero), and the current column number exceeds it, has the effect of calling New_Line with a spacing of one. Then, or otherwise, outputs the given character to the file.
procedure Look_Ahead (File : in File_Type;
Item : out Character;
End_Of_Line : out Boolean);
procedure Look_Ahead (Item : out Character;
End_Of_Line : out Boolean);
Status_Error is propagated if the file is not open. Mode_Error is propagated if the mode of the file is not In_File. Sets End_Of_Line to True if at end of line, including if at end of page or at end of file; in each of these cases the value of Item is not specified. Otherwise, End_Of_Line is set to False and Item is set to the next character (without consuming it) from the file.
procedure Get_Immediate(File : in File_Type;
Item : out Character);
procedure Get_Immediate(Item : out Character);
Reads the next character, either control or graphic, from the specified File or the default input file. Status_Error is propagated if the file is not open. Mode_Error is propagated if the mode of the file is not In_File. End_Error is propagated if at the end of the file. The current column, line and page numbers for the file are not affected.
procedure Get_Immediate(File : in File_Type;
Item : out Character;
Available : out Boolean);
procedure Get_Immediate(Item : out Character;
Available : out Boolean);
If a character, either control or graphic, is available from the specified File or the default input file, then the character is read; Available is True and Item contains the value of this character. If a character is not available, then Available is False and the value of Item is not specified. Status_Error is propagated if the file is not open. Mode_Error is propagated if the mode of the file is not In_File. End_Error is propagated if at the end of the file. The current column, line and page numbers for the file are not affected.
For an item of type String the following subprograms are provided:
procedure Get(File : in File_Type; Item : out String);
procedure Get(Item : out String);
Determines the length of the given string and attempts that number of Get operations for successive characters of the string (in particular, no operation is performed if the string is null).
procedure Put(File : in File_Type; Item : in String);
procedure Put(Item : in String);
Determines the length of the given string and attempts that number of Put operations for successive characters of the string (in particular, no operation is performed if the string is null).
function Get_Line(File : in File_Type) return String;
function Get_Line return String;
Returns a result string constructed by reading successive characters from the specified input file, and assigning them to successive characters of the result string. The result string has a lower bound of 1 and an upper bound of the number of characters read. Reading stops when the end of the line is met; Skip_Line is then (in effect) called with a spacing of 1.
Constraint_Error is raised if the length of the line exceeds Positive'Last; in this case, the line number and page number are unchanged, and the column number is unspecified but no less than it was before the call. The exception End_Error is propagated if an attempt is made to skip a file terminator.
Precisely what is left in the file is unspecified if Constraint_Error is raised because the line doesn't fit in a String; it should be consistent with column number. This allows implementers to use whatever buffering scheme makes sense. But the line terminator is not skipped in this case.
procedure Get_Line(File : in File_Type;
Item : out String;
Last : out Natural);
procedure Get_Line(Item : out String;
Last : out Natural);
Reads successive characters from the specified input file and assigns them to successive characters of the specified string. Reading stops if the end of the string is met. Reading also stops if the end of the line is met before meeting the end of the string; in this case Skip_Line is (in effect) called with a spacing of 1. The values of characters not assigned are not specified.
If characters are read, returns in Last the index value such that Item(Last) is the last character assigned (the index of the first character assigned is Item'First). If no characters are read, returns in Last an index value that is one less than Item'First. The exception End_Error is propagated if an attempt is made to skip a file terminator.
procedure Put_Line(File : in File_Type; Item : in String);
procedure Put_Line(Item : in String);
Calls the procedure Put for the given string, and then the procedure New_Line with a spacing of one.
Implementation Advice
23The Get_Immediate procedures should be implemented with unbuffered input. For a device such as a keyboard, input should be “available” if a key has already been typed, whereas for a disk file, input should always be available except at end of file. For a file associated with a keyboard-like device, any line-editing features of the underlying operating system should be disabled during the execution of Get_Immediate.
Get_Immediate should be implemented with unbuffered input; input should be available immediately; line-editing should be disabled.
NOTE 1 Get_Immediate can be used to read a single key from the keyboard “immediately”; that is, without waiting for an end of line. In a call of Get_Immediate without the parameter Available, the caller will wait until a character is available.
NOTE 2 In a literal string parameter of Put, the enclosing string bracket characters are not output. Each doubled string bracket character in the enclosed string is output as a single string bracket character, as a consequence of the rule for string literals (see 2.6).
NOTE 3 A string read by Get or written by Put can extend over several lines. An implementation is allowed to assume that certain external files do not contain page terminators, in which case Get_Line and Skip_Line can return as soon as a line terminator is read.
Incompatibilities With Ada 95
The Get_Line functions are added to Ada.Text_IO. If Ada.Text_IO is referenced in a use_clause, and a function Get_Line is defined in a package that is also referenced in a use_clause, the user-defined Get_Line may no longer be use-visible, resulting in errors. This should be rare and is easily fixed if it does occur.
Extensions to Ada 95
Wording Changes from Ada 2005
A.10.8 Input-Output for Integer Types
Static Semantics
1The following procedures are defined in the generic packages Integer_IO and Modular_IO, which have to be instantiated for the appropriate signed integer or modular type respectively (indicated by Num in the specifications).
Values are output as decimal or based literals, without low line characters or exponent, and, for Integer_IO, preceded by a minus sign if negative. The format (which includes any leading spaces and minus sign) can be specified by an optional field width parameter. Values of widths of fields in output formats are of the nonnegative integer subtype Field. Values of bases are of the integer subtype Number_Base.
subtype Number_Base is Integer range 2 .. 16;
The default field width and base to be used by output procedures are defined by the following variables that are declared in the generic packages Integer_IO and Modular_IO:
Default_Width : Field := Num'Width;
Default_Base : Number_Base := 10;
The following procedures are provided:
procedure Get(File : in File_Type; Item : out Num; Width : in Field := 0);
procedure Get(Item : out Num; Width : in Field := 0);
If the value of the parameter Width is zero, skips any leading blanks, line terminators, or page terminators, then reads a plus sign if present or (for a signed type only) a minus sign if present, then reads the longest possible sequence of characters matching the syntax of a numeric literal without a point. 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.
Returns, in the parameter Item, the value of type Num that corresponds to the sequence input.
The exception Data_Error is propagated if the sequence of characters read does not form a legal integer literal or if the value obtained is not of the subtype Num.
procedure Put(File : in File_Type;
Item : in Num;
Width : in Field := Default_Width;
Base : in Number_Base := Default_Base);
procedure Put(Item : in Num;
Width : in Field := Default_Width;
Base : in Number_Base := Default_Base);
Outputs the value of the parameter Item as an integer literal, with no low lines, no exponent, and no leading zeros (but a single zero for the value zero), and a preceding minus sign for a negative value.
If the resulting sequence of characters to be output has fewer than Width characters, then leading spaces are first output to make up the difference.
Uses the syntax for decimal literal if the parameter Base has the value ten (either explicitly or through Default_Base); otherwise, uses the syntax for based literal, with any letters in upper case.
procedure Get(From : in String; Item : out Num; Last : out Positive);
Reads an integer value from the beginning of the given string, following the same rules as the Get procedure that reads an integer 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.
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.
procedure Put(To : out String;
Item : in Num;
Base : in Number_Base := Default_Base);
Outputs the value of the parameter Item to the given string, following the same rule as for output to a file, using the length of the given string as the value for Width.
Integer_Text_IO is a library package that is a nongeneric equivalent to Text_IO.Integer_IO for the predefined type Integer:
with Ada.Text_IO;
package Ada.Integer_Text_IO is new Ada.Text_IO.Integer_IO(Integer);
For each predefined signed integer type, a nongeneric equivalent to Text_IO.Integer_IO is provided, with names such as Ada.Long_Integer_Text_IO.
Implementation Permissions
23/5The nongeneric equivalent packages can be actual instantiations of the generic package for the appropriate predefined type, though that is not required.
Examples
Examples of use of an instantiation of Text_IO.Integer_IO:
subtype Byte_Int is Integer range -127 .. 127;
package Int_IO is new Integer_IO(Byte_Int); use Int_IO;
-- default format used at instantiation,
-- Default_Width = 4, Default_Base = 10
26
Put(126); -- "b126"
Put(-126, 7); -- "bbb–126"
Put(126, Width => 13, Base => 2); -- "bbb2#1111110#"
Inconsistencies With Ada 2005
Changed wording to make Integer_IO and Modular_IO raise Data_Error in the same way when the bounds of the subtype are exceeded. There is no value to different behavior, and all surveyed compilers already treat integer and modular values the same way. This could only cause a problem if a program was compiled with some unsurveyed compiler, and the Ada 95-defined behavior is expected for Modular_IO. But note that such code is not portable anyway, as most widely used compilers behave consistently with the new wording, so it is unlikely that such code exists.
A.10.9 Input-Output for Real Types
Static Semantics
1The 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).
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:
Fore . Aft
and to:
Fore . Aft E Exp
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).
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:
Default_Fore : Field := 2;
Default_Aft : Field := Num'Digits-1;
Default_Exp : Field := 3;
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:
Default_Fore : Field := Num'Fore;
Default_Aft : Field := Num'Aft;
Default_Exp : Field := 0;
The following procedures are provided:
procedure Get(File : in File_Type; Item : out Num; Width : in Field := 0);
procedure Get(Item : out Num; Width : in Field := 0);
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):
- [+|–]
numeric_literal15 - [+|–]
numeral.[exponent] 16 - [+|–].
numeral[exponent] 17 - [+|–]
base#based_numeral.#[exponent] 18 - [+|–]
base#.based_numeral#[exponent]
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.
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.
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.
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);
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.
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.
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.
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.
procedure Get(From : in String; Item : out Num; Last : out Positive);
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.
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.
procedure Put(To : out String;
Item : in Num;
Aft : in Field := Default_Aft;
Exp : in Field := Default_Exp);
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.
Float_Text_IO is a library package that is a nongeneric equivalent to Text_IO.Float_IO for the predefined type Float:
with Ada.Text_IO;
package Ada.Float_Text_IO is new Ada.Text_IO.Float_IO(Float);
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
35An implementation may extend Get [and Put] for floating point types to support special values such as infinities and NaNs.
See also the similar permission for the Wide_Wide_Value, Wide_Value, and Value attributes in 3.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.
The required accuracy is thus Num'Base'Digits digits if Num is a floating point subtype. For a fixed point subtype the required accuracy is a function of the subtype's Fore, Aft, and Delta attributes.
The accuracy of the value produced by Put.
The nongeneric equivalent packages can be actual instantiations of the generic package for the appropriate predefined type, though that is not required.
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.
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/5Examples of use of an instantiation of Text_IO.Float_IO:
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"
A.10.10 Input-Output for Enumeration Types
Static Semantics
1The following procedures are defined in the generic package Enumeration_IO, which has to be instantiated for the appropriate enumeration type (indicated by Enum in the specification).
Values are output using either upper or lower case letters for identifiers. This is specified by the parameter Set, which is of the enumeration type Type_Set.
type Type_Set is (Lower_Case, Upper_Case);
The format (which includes any trailing spaces) can be specified by an optional field width parameter. The default field width and letter case are defined by the following variables that are declared in the generic package Enumeration_IO:
Default_Width : Field := 0;
Default_Setting : Type_Set := Upper_Case;
The following procedures are provided:
procedure Get(File : in File_Type; Item : out Enum);
procedure Get(Item : out Enum);
After skipping any leading blanks, line terminators, or page terminators, reads an identifier according to the syntax of this lexical element (lower and upper case being considered equivalent), or a character literal according to the syntax of this lexical element (including the apostrophes). Returns, in the parameter Item, the value of type Enum that corresponds to the sequence input.
The exception Data_Error is propagated if the sequence input does not have the required syntax, or if the identifier or character literal does not correspond to a value of the subtype Enum.
procedure Put(File : in File_Type;
Item : in Enum;
Width : in Field := Default_Width;
Set : in Type_Set := Default_Setting);
procedure Put(Item : in Enum;
Width : in Field := Default_Width;
Set : in Type_Set := Default_Setting);
Outputs the value of the parameter Item as an enumeration literal (either an identifier or a character literal). The optional parameter Set indicates whether lower case or upper case is used for identifiers; it has no effect for character literals. If the sequence of characters produced has fewer than Width characters, then trailing spaces are finally output to make up the difference. If Enum is a character type, the sequence of characters produced is as for Enum'Image(Item), as modified by the Width and Set parameters.
For a character type, the literal might be a Wide_Wide_Character, Wide_Character, or a control character. Whatever Image does for these things is appropriate here, too.
The “characters produced” defines the “characters to be output” in the sense of A.10.6, so a result that cannot fit on any bounded line will raise Layout_Error.
procedure Get(From : in String; Item : out Enum; Last : out Positive);
Reads an enumeration value from the beginning of the given string, following the same rule as the Get procedure that reads an enumeration value from a file, but treating the end of the string as a file terminator. Returns, in the parameter Item, the value of type Enum that corresponds to the sequence input. Returns in Last the index value such that From(Last) is the last character read.
The exception Data_Error is propagated if the sequence input does not have the required syntax, or if the identifier or character literal does not correspond to a value of the subtype Enum.
To be honest: For a character type, it is permissible for the implementation to make Get do the inverse of what Put does, in the case of wide and wide_wide character_literals and control characters.
procedure Put(To : out String;
Item : in Enum;
Set : in Type_Set := Default_Setting);
Outputs the value of the parameter Item to the given string, following the same rule as for output to a file, using the length of the given string as the value for Width.
{8652/0054} Although the specification of the generic package Enumeration_IO would allow instantiation for an integer type, this is not the intended purpose of this generic package, and the effect of such instantiations is not defined by the language.
NOTE 1 There is a difference between Put defined for characters, and for enumeration values. Thus
Ada.Text_IO.Put('A'); -- outputs the character A
20
package Char_IO is new Ada.Text_IO.Enumeration_IO(Character);
Char_IO.Put('A'); -- outputs the character 'A', between apostrophes
NOTE 2 The type Boolean is an enumeration type, hence Enumeration_IO can be instantiated for this type.
Wording Changes from Ada 95
{8652/0054} Corrigendum: Corrected the wording to say Enumeration_IO can be instantiated with an integer type, not a float type.
A.10.11 Input-Output for Bounded Strings
1/2The package Text_IO.Bounded_IO provides input-output in human-readable form for Bounded_Strings.
Static Semantics
2/2The generic library package Text_IO.Bounded_IO has the following declaration:
with Ada.Strings.Bounded;
generic
with package Bounded is
new Ada.Strings.Bounded.Generic_Bounded_Length (<>);
package Ada.Text_IO.Bounded_IO
with Global => in out synchronized is
4/2
procedure Put
(File : in File_Type;
Item : in Bounded.Bounded_String);
5/2
procedure Put
(Item : in Bounded.Bounded_String);
6/2
procedure Put_Line
(File : in File_Type;
Item : in Bounded.Bounded_String);
7/2
procedure Put_Line
(Item : in Bounded.Bounded_String);
8/2
function Get_Line
(File : in File_Type)
return Bounded.Bounded_String;
9/2
function Get_Line
return Bounded.Bounded_String;
10/2
procedure Get_Line
(File : in File_Type; Item : out Bounded.Bounded_String);
11/2
procedure Get_Line
(Item : out Bounded.Bounded_String);
12/2
end Ada.Text_IO.Bounded_IO;
For an item of type Bounded_String, the following subprograms are provided:
procedure Put
(File : in File_Type;
Item : in Bounded.Bounded_String);
Equivalent to Text_IO.Put (File, Bounded.To_String(Item));
procedure Put
(Item : in Bounded.Bounded_String);
Equivalent to Text_IO.Put (Bounded.To_String(Item));
procedure Put_Line
(File : in File_Type;
Item : in Bounded.Bounded_String);
Equivalent to Text_IO.Put_Line (File, Bounded.To_String(Item));
procedure Put_Line
(Item : in Bounded.Bounded_String);
Equivalent to Text_IO.Put_Line (Bounded.To_String(Item));
function Get_Line
(File : in File_Type)
return Bounded.Bounded_String;
Returns Bounded.To_Bounded_String(Text_IO.Get_Line(File));
function Get_Line
return Bounded.Bounded_String;
Returns Bounded.To_Bounded_String(Text_IO.Get_Line);
procedure Get_Line
(File : in File_Type; Item : out Bounded.Bounded_String);
Equivalent to Item := Get_Line (File);
procedure Get_Line
(Item : out Bounded.Bounded_String);
Equivalent to Item := Get_Line;
Extensions to Ada 95
A.10.12 Input-Output for Unbounded Strings
1/2The package Text_IO.Unbounded_IO provides input-output in human-readable form for Unbounded_Strings.
Static Semantics
2/2The library package Text_IO.Unbounded_IO has the following declaration:
with Ada.Strings.Unbounded;
package Ada.Text_IO.Unbounded_IO
with Global => in out synchronized is
4/2
procedure Put
(File : in File_Type;
Item : in Strings.Unbounded.Unbounded_String);
5/2
procedure Put
(Item : in Strings.Unbounded.Unbounded_String);
6/2
procedure Put_Line
(File : in File_Type;
Item : in Strings.Unbounded.Unbounded_String);
7/2
procedure Put_Line
(Item : in Strings.Unbounded.Unbounded_String);
8/2
function Get_Line
(File : in File_Type)
return Strings.Unbounded.Unbounded_String;
9/2
function Get_Line
return Strings.Unbounded.Unbounded_String;
10/2
procedure Get_Line
(File : in File_Type; Item : out Strings.Unbounded.Unbounded_String);
11/2
procedure Get_Line
(Item : out Strings.Unbounded.Unbounded_String);
12/2
end Ada.Text_IO.Unbounded_IO;
For an item of type Unbounded_String, the following subprograms are provided:
procedure Put
(File : in File_Type;
Item : in Strings.Unbounded.Unbounded_String);
Equivalent to Text_IO.Put (File, Strings.Unbounded.To_String(Item));
procedure Put
(Item : in Strings.Unbounded.Unbounded_String);
Equivalent to Text_IO.Put (Strings.Unbounded.To_String(Item));
procedure Put_Line
(File : in File_Type;
Item : in Strings.Unbounded.Unbounded_String);
Equivalent to Text_IO.Put_Line (File, Strings.Unbounded.To_String(Item));
procedure Put_Line
(Item : in Strings.Unbounded.Unbounded_String);
Equivalent to Text_IO.Put_Line (Strings.Unbounded.To_String(Item));
function Get_Line
(File : in File_Type)
return Strings.Unbounded.Unbounded_String;
Returns Strings.Unbounded.To_Unbounded_String(Text_IO.Get_Line(File));
function Get_Line
return Strings.Unbounded.Unbounded_String;
Returns Strings.Unbounded.To_Unbounded_String(Text_IO.Get_Line);
procedure Get_Line
(File : in File_Type; Item : out Strings.Unbounded.Unbounded_String);
Equivalent to Item := Get_Line (File);
procedure Get_Line
(Item : out Strings.Unbounded.Unbounded_String);
Equivalent to Item := Get_Line;