A.12.1 The Package Streams.Stream_IO
1
{heterogeneous input-output}
[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
{
8652/0055}
{
AI95-00026-01}
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.{Current
index (of an open stream file)} {Current
size (of a stream file)}
1.a.1/1
Implementation defined:
Current size for a stream file for which
positioning is not supported.
2
The library package
Streams.Stream_IO has the following declaration:
3
with Ada.IO_Exceptions;
package Ada.Streams.Stream_IO
is
4
type Stream_Access
is access all Root_Stream_Type'Class;
5
type File_Type
is limited private;
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
--
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);
16
procedure Read (File :
in File_Type;
Item :
out Stream_Element_Array;
Last :
out Stream_Element_Offset);
17/1
This paragraph
was deleted.
18
--
Write array of stream elements into file
procedure Write (File :
in File_Type;
Item :
in Stream_Element_Array;
To :
in Positive_Count);
19
procedure Write (File :
in File_Type;
Item :
in Stream_Element_Array);
20/1
This paragraph
was deleted.
21
-- Operations on position within file
22
procedure Set_Index(File :
in File_Type; To :
in Positive_Count);
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
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;
27
private
... -- not specified by the language
end Ada.Streams.Stream_IO;
27.1/2
28/2
{
AI95-00283-01}
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, and End_of_File
have the same effect as the corresponding subprograms in Sequential_IO
(see A.8.2).
28.1/2
28.2/2
- Propagates Mode_Error
if the mode of the file is not In_File;
28.3/2
- 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/2
- 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
{
8652/0055}
{
AI95-00026-01}
{
AI95-00085-01}
The Set_Mode procedure sets changes 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/1
{
8652/0055}
{
AI95-00026-01}
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.
29/1
{
8652/0056}
{
AI95-00001-01}
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
{
AI95-00256-01}
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
31/1
{
8652/0055}
{
AI95-00026-01}
The Index function returns the current
file index
,
as a count (in stream elements) from the beginning of the file. The position
of the first element in the file is 1.
31.a/1
This paragraph
was deleted.Ramification: The
notion of Index for Stream_IO is analogous to that of Index in Direct_IO,
except that the former is measured in Stream_Element units, whereas the
latter is in terms of Element_Type values.
32
The Set_Index procedure sets the current index to
the specified value.
32.1/1
{
8652/0055}
{
AI95-00026-01}
If positioning is supported for the external file,
the current index is maintained as follows:
32.2/1
- {8652/0055}
{AI95-00026-01}
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
- {8652/0055}
{AI95-00026-01}
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
- {8652/0055}
{AI95-00026-01}
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
- {8652/0055}
{AI95-00026-01}
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
- {8652/0055}
{AI95-00026-01}
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.
33.a/2
Implementation Note:
{
AI95-00085-01}
It is permissible for an implementation to implement
mode Append_File using the Unix append mode (the O_APPEND bit). Such
an implementation does not support positioning when the mode is Append_File,
and therefore the operations listed above must raise Use_Error. This
is acceptable as there is no requirement that any particular file support
positioning; therefore it is acceptable that a file support positioning
when opened with mode Out_File, and the same file not support positioning
when opened with mode Append_File. But it is not acceptable for a file
to support positioning (by allowing the above operations), but to do
something other than the defined semantics (that is, always write at
the end, even when explicitly commanded to write somewhere else).
34/1
This paragraph was
deleted.{
8652/0055}
{
AI95-00026-01}
The Size function returns the current size of the
file, in stream elements.
35/1
This paragraph was
deleted.{
8652/0055}
{
AI95-00026-01}
The Set_Mode procedure changes 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.
36/1
This paragraph was
deleted.{
8652/0055}
{
AI95-00026-01}
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.
Erroneous Execution
36.1/1
{
8652/0056}
{
AI95-00001-01}
{erroneous execution
(cause) [partial]} 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.
36.a.1/1
Reason: These rules
are analogous to the rule for the result of the Current_Input, Current_Output,
and Current_Error functions. These rules make it possible to represent
a value of (some descendant of) Root_Stream_Type which represents a file
as an access value, with a null value corresponding to a closed file.
Inconsistencies With Ada 95
36.a/2
{
AI95-00283-01}
{inconsistencies with Ada 95} Amendment
Correction: The description of the subprograms for managing files
was corrected so that they do not require truncation of the external
file — a stream file is not a sequential file. An Ada 95 program
that expects truncation of the stream file may not work under Ada 2005.
Note that the Ada 95 standard was ambiguous on this point (the normative
wording seemed to require truncation, but didn't explain where; the AARM
notes seemed to expect behavior like Direct_IO), and implementations
varied widely. Therefore, as a practical matter, code that depends on
stream truncation may not work even in Ada 95; deleting the file before
opening it provides truncation that works in both Ada 95 and Ada 2005.
Incompatibilities With Ada 95
36.b/2
{
AI95-00360-01}
{incompatibilities with Ada 95} Amendment
Correction: Stream_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
36.c/2
{
8652/0051}
{
AI95-00057-01}
Corrigendum: Corrected the parameter mode
of Flush; otherwise it could not be used on Standard_Output.
36.d/2
{
8652/0055}
{
AI95-00026-01}
{
AI95-00256-01}
Corrigendum: Added wording to describe the
effects of the various operations on the current index. The Amendment
adds an explanation of the use of current index for Read and Write.
36.e/2
{
8652/0056}
{
AI95-00001-01}
Corrigendum: Clarified that Stream can raise
Status_Error, and clarified that using a Stream_Access whose file has
been closed is erroneous.
36.f/2
{
AI95-00085-01}
Clarified that Set_Mode can be called with the
current mode.