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