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

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.

The library package Streams.Stream_IO has the following declaration:

with Ada.IO_Exceptions; package Ada.Streams.Stream_IO is

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

14/1

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

17/1

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

20/1

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

25/1

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

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

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.

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

The Size function returns the current size of the file.

31/1

The Index function returns the current index.

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

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

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

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

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

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.

34/1

This paragraph was deleted.

35/1

This paragraph was deleted.

36/1

This paragraph was 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.

Contents Index Search Previous Next Legal