A.12.1 The Package Streams.Stream_IO
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
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.
The library package
Streams.Stream_IO has the following declaration:
with Ada.IO_Exceptions;
package Ada.Streams.Stream_IO
with Preelaborate, Global =>
in out synchronized is
type Stream_Access
is access all Root_Stream_Type'Class;
type File_Type
is limited private
with Preelaborable_Initialization;
type File_Mode
is (In_File, Out_File, Append_File);
type Count
is range 0 ..
implementation-defined;
subtype Positive_Count
is Count
range 1 .. Count'Last;
--
Index into file, in stream elements.
procedure Create (File :
in out File_Type;
Mode :
in File_Mode := Out_File;
Name :
in String := "";
Form :
in String := "");
procedure Open (File :
in out File_Type;
Mode :
in File_Mode;
Name :
in String;
Form :
in String := "");
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);
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;
function Is_Open (File :
in File_Type)
return Boolean;
function End_Of_File (File :
in File_Type)
return Boolean;
function Stream (File :
in File_Type)
return Stream_Access;
--
Return stream access for use with T'Input and T'Output
This paragraph
was deleted.
--
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;
procedure Read (File :
in File_Type;
Item :
out Stream_Element_Array;
Last :
out Stream_Element_Offset)
with Global =>
overriding in out File;
This paragraph
was deleted.
--
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;
procedure Write (File :
in File_Type;
Item :
in Stream_Element_Array)
with Global =>
overriding in out File;
This paragraph
was deleted.
-- Operations on position within file
procedure Set_Index(File :
in File_Type; To :
in Positive_Count)
with Global =>
overriding in out File;
function Index(File :
in File_Type)
return Positive_Count;
function Size (File :
in File_Type)
return Count;
procedure Set_Mode(File :
in out File_Type; Mode :
in File_Mode);
procedure Flush(File :
in File_Type);
--
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;
package Wide_File_Names
is
-- File management
procedure Create (File :
in out File_Type;
Mode :
in File_Mode := Out_File;
Name :
in Wide_String := "";
Form :
in Wide_String := "");
procedure Open (File :
in out File_Type;
Mode :
in File_Mode;
Name :
in Wide_String;
Form :
in Wide_String := "");
function Name (File :
in File_Type)
return Wide_String;
function Form (File :
in File_Type)
return Wide_String;
end Wide_File_Names;
package Wide_Wide_File_Names
is
-- File management
procedure Create (File :
in out File_Type;
Mode :
in File_Mode := Out_File;
Name :
in Wide_Wide_String := "";
Form :
in Wide_Wide_String := "");
procedure Open (File :
in out File_Type;
Mode :
in File_Mode;
Name :
in Wide_Wide_String;
Form :
in Wide_Wide_String := "");
function Name (File :
in File_Type)
return Wide_Wide_String;
function Form (File :
in File_Type)
return Wide_Wide_String;
end Wide_Wide_File_Names;
private
... -- not specified by the language
end Ada.Streams.Stream_IO;
The type File_Type needs finalization
(see
7.6).
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.
The End_Of_File function:
Propagates Mode_Error if the mode of the file is
not In_File;
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;
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.
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.
This paragraph
was deleted.
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.
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.
The Size function returns the current size of the
file.
The Index function returns the current index.
The Set_Index procedure sets the current index to
the specified value.
If positioning is
supported for the external file, the current index is maintained as follows:
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.
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.
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.
For Read and Write without a Positive_Count parameter,
the current index is incremented by the number of stream elements read
or written.
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.
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
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
