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
is
pragma Preelaborate(Stream_IO);
type Stream_Access
is access all Root_Stream_Type'Class;
type File_Type
is limited private;
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);
procedure Read (File :
in File_Type;
Item :
out Stream_Element_Array;
Last :
out Stream_Element_Offset);
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);
procedure Write (File :
in File_Type;
Item :
in Stream_Element_Array);
This paragraph
was deleted.
-- Operations on position within file
procedure Set_Index(File :
in File_Type; To :
in Positive_Count);
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;
private
... -- not specified by the language
end Ada.Streams.Stream_IO;
The type File_Type needs finalization
(see
7.6).
The subprograms given in subclause
A.8.2
for the control of external files (Create, Open, Close, Delete, Reset,
Mode, Name, Form, and Is_Open) 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.
The Flush procedure synchronizes the external
file with the internal file (by flushing any internal buffers) without
closing the file or changing the position. Mode_Error is propagated if
the mode of the file is In_File.
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