Contents   Index   Previous   Next

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} 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
{8652/0051}
    procedure Flush(File : in out 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;
27
private
   ... -- not specified by the language
end Ada.Streams.Stream_IO;
28
    The subprograms Create, Open, Close, Delete, Reset, Mode, Name, Form, Is_Open, and End_of_File have the same effect as the corresponding subprograms in Sequential_IO (see A.8.2).
28.1/1
        {8652/0055} 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.
28.2/1
        {8652/0055} 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} 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
    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.
30.1/1
        {8652/0055} The Size function returns the current size of the file.
31/1
      {8652/0055} 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} If positioning is supported for the external file, the current index is maintained as follows:
32.2/1
32.3/1
32.4/1
32.5/1
32.6/1
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.
34/1
      This paragraph was deleted.{8652/0055} The Size function returns the current size of the file, in stream elements.
35/1
      This paragraph was deleted.{8652/0055} 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} 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} {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 decendant of) Root_Stream_Type which represents a file as an access value, with a null value corresponding to a closed file.

Contents   Index   Previous   Next   Legal