[Home] [Prev] [Next] [Index]

A.12 Stream Input-Output

A.12 Stream Input-Output

1
The packages Streams.Stream_IO, Text_IO.Text_Streams, and Wide_Text_IO.Text_Streams provide stream-oriented operations on files.

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

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

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

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

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
    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).

29
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.

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.

31
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
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.

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
The Size function returns the current size of the file, in stream elements.

35
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
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.

A.12.2 The Package Text_IO.Text_Streams

1
The package Text_IO.Text_Streams provides a function for treating a text file as a stream.

Static Semantics

2
The library package Text_IO.Text_Streams has the following declaration:

3
with Ada.Streams;

package Ada.Text_IO.Text_Streams is
   type Stream_Access is access all Streams.Root_Stream_Type'Class;

4
   function Stream (File : in File_Type) return Stream_Access;
end Ada.Text_IO.Text_Streams;

5
The Stream function has the same effect as the corresponding function in Streams.Stream_IO.

NOTES

6 34
The ability to obtain a stream for a text file allows Current_Input, Current_Output, and Current_Error to be processed with the functionality of streams, including the mixing of text and binary input-output, and the mixing of binary input-output for different types.

7 35
Performing operations on the stream associated with a text file does not affect the column, line, or page counts.

A.12.3 The Package Wide_Text_IO.Text_Streams

1
The package Wide_Text_IO.Text_Streams provides a function for treating a wide text file as a stream.

Static Semantics

2
The library package Wide_Text_IO.Text_Streams has the following declaration:

3
with Ada.Streams;

package Ada.Wide_Text_IO.Text_Streams is
   type Stream_Access is access all Streams.Root_Stream_Type'Class;

4
   function Stream (File : in File_Type) return Stream_Access;
end Ada.Wide_Text_IO.Text_Streams;

5
The Stream function has the same effect as the corresponding function in Streams.Stream_IO.



[Home] [Prev] [Next] [Index]

documentation@rational.com
Copyright © 1993-1998, Rational Software Corporation.   All rights reserved.