Ada Reference Manual (Ada 2022) — Legal Information

# A.12.1 The Package Streams.Stream_IO

1
The subprograms in the child package Streams.Stream_IO provide control over stream files. Access to a stream file is either sequential, via a call on Read or Write to transfer an array of stream elements, or positional (if supported by the implementation for the given file), by specifying a relative index for an element. Since a stream file can be converted to a Stream_Access value, calling stream-oriented attribute subprograms of different element types with the same Stream_Access value provides heterogeneous input-output. See 13.13 for a general discussion of streams.

#### Static Semantics

1.1/1
The elements of a stream file are stream elements. If positioning is supported for the specified external file, a current index and current size are maintained for the file as described in A.8. If positioning is not supported, a current index is not maintained, and the current size is implementation defined.
2
The library package Streams.Stream_IO has the following declaration:
3/5
with Ada.IO_Exceptions;
package Ada.Streams.Stream_IO
with Preelaborate, Global => in out synchronized is
4
type Stream_Access is access all Root_Stream_Type'Class;
5/5
type File_Type is limited private
with Preelaborable_Initialization;
6
type File_Mode is (In_File, Out_File, Append_File);
7
type Count is range 0 .. implementation-defined;
subtype Positive_Count is Count range 1 .. Count'Last;
-- Index into file, in stream elements.
8
procedure Create (File : in out File_Type;
Mode : in File_Mode := Out_File;
Name : in String := "";
Form : in String := "");
9
procedure Open (File : in out File_Type;
Mode : in File_Mode;
Name : in String;
Form : in String := "");
10
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);
11
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;
12
function Is_Open (File : in File_Type) return Boolean;
function End_Of_File (File : in File_Type) return Boolean;
13
function Stream (File : in File_Type) return Stream_Access;
-- Return stream access for use with T'Input and T'Output
14/1
This paragraph was deleted.
15/5
-- Read array of stream elements from file
procedure Read (File : in File_Type;
Item : out Stream_Element_Array;
Last : out Stream_Element_Offset;
From : in Positive_Count)
with Global => overriding in out File;
16/5
procedure Read (File : in File_Type;
Item : out Stream_Element_Array;
Last : out Stream_Element_Offset)
with Global => overriding in out File;
17/1
This paragraph was deleted.
18/5
-- Write array of stream elements into file
procedure Write (File : in File_Type;
Item : in Stream_Element_Array;
To : in Positive_Count)
with Global => overriding in out File;
19/5
procedure Write (File : in File_Type;
Item : in Stream_Element_Array)
with Global => overriding in out File;
20/1
This paragraph was deleted.
21
-- Operations on position within file
22/5
procedure Set_Index(File : in File_Type; To : in Positive_Count)
with Global => overriding in out File;
23
function Index(File : in File_Type) return Positive_Count;
function Size (File : in File_Type) return Count;
24
procedure Set_Mode(File : in out File_Type; Mode : in File_Mode);
25/1
procedure Flush(File : in File_Type);
26
-- exceptions
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;
26.1/5
package Wide_File_Names is
26.2/5
-- File management
26.3/5
procedure Create (File : in out File_Type;
Mode : in File_Mode := Out_File;
Name : in Wide_String := "";
Form : in Wide_String := "");
26.4/5
procedure Open (File : in out File_Type;
Mode : in File_Mode;
Name : in Wide_String;
Form : in Wide_String := "");
26.5/5
function Name (File : in File_Type) return Wide_String;
26.6/5
function Form (File : in File_Type) return Wide_String;
26.7/5
end Wide_File_Names;
26.8/5
package Wide_Wide_File_Names is
26.9/5
-- File management
26.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 := "");
26.11/5
procedure Open (File : in out File_Type;
Mode : in File_Mode;
Name : in Wide_Wide_String;
Form : in Wide_Wide_String := "");
26.12/5
function Name (File : in File_Type) return Wide_Wide_String;
26.13/5
function Form (File : in File_Type) return Wide_Wide_String;
26.14/5
end Wide_Wide_File_Names;
27
private
... -- not specified by the language
end Ada.Streams.Stream_IO;
27.1/2
The type File_Type needs finalization (see 7.6).
28/5
The subprograms given in A.8.2 for the control of external files (Create, Open, Close, Delete, Reset, Mode, Name, Form, Is_Open, and Flush) are available for stream files.
28.1/2
The End_Of_File function:
28.2/2
Propagates Mode_Error if the mode of the file is not In_File;
28.3/3
If positioning is supported for the given external file, the function returns True if the current index exceeds the size of the external file; otherwise, it returns False;
28.4/3
If positioning is not supported for the given external file, the function returns True if no more elements can be read from the given file; otherwise, it returns False.
28.5/2
The Set_Mode procedure sets the mode of the file. If the new mode is Append_File, the file is positioned to its end; otherwise, the position in the file is unchanged.
28.6/4
This paragraph was deleted.
29/1
The Stream function returns a Stream_Access result from a File_Type object, thus allowing the stream-oriented attributes Read, Write, Input, and Output to be used on the same file for multiple types. Stream propagates Status_Error if File is not open.
30/2
The procedures Read and Write are equivalent to the corresponding operations in the package Streams. Read propagates Mode_Error if the mode of File is not In_File. Write propagates Mode_Error if the mode of File is not Out_File or Append_File. The Read procedure with a Positive_Count parameter starts reading at the specified index. The Write procedure with a Positive_Count parameter starts writing at the specified index. For a file that supports positioning, Read without a Positive_Count parameter starts reading at the current index, and Write without a Positive_Count parameter starts writing at the current index.
30.1/1
The Size function returns the current size of the file.
31/1
The Index function returns the current index.
32
The Set_Index procedure sets the current index to the specified value.
32.1/1
If positioning is supported for the external file, the current index is maintained as follows:
32.2/1
For Open and Create, if the Mode parameter is Append_File, the current index is set to the current size of the file plus one; otherwise, the current index is set to one.
32.3/1
For Reset, if the Mode parameter is Append_File, or no Mode parameter is given and the current mode is Append_File, the current index is set to the current size of the file plus one; otherwise, the current index is set to one.
32.4/1
For Set_Mode, if the new mode is Append_File, the current index is set to current size plus one; otherwise, the current index is unchanged.
32.5/1
For Read and Write without a Positive_Count parameter, the current index is incremented by the number of stream elements read or written.
32.6/1
For Read and Write with a Positive_Count parameter, the value of the current index is set to the value of the Positive_Count parameter plus the number of stream elements read or written.
33
If positioning is not supported for the given file, then a call of Index or Set_Index propagates Use_Error. Similarly, a call of Read or Write with a Positive_Count parameter propagates Use_Error.
Paragraphs 34 through 36 were deleted.

#### Erroneous Execution

36.1/1
If the File_Type object passed to the Stream function is later closed or finalized, and the stream-oriented attributes are subsequently called (explicitly or implicitly) on the Stream_Access value returned by Stream, execution is erroneous. This rule applies even if the File_Type object was opened again after it had been closed.

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