Next: , Previous: A.12, Up: A.12


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

1.1/1
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.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 .. implementation−defined;
         subtype Positive_Count is Count range .. 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

         procedure Flush(File in 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;

27.1/2
The type File_Type needs finalization (see 7.6).

28/2
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.

28.1/2
The End_Of_File function:

28.2/2

28.3/2

28.4/2

28.5/2
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.

28.6/1
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
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
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
The Size function returns the current size of the file.

31/1
The Index function returns the current index.

32
The Set_Index procedure sets the current index to the specified value.

32.1/1
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.

Paragraphs 34 through 36 were deleted.

Erroneous Execution

36.1/1
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.