Streams

The abstract type Root_Stream_Type is the root type of the class of stream types. The types in this class represent different kinds of streams. A new stream type is defined by extending the root type (or some other stream type), overriding the Read and Write operations, and optionally defining additional primitive subprograms, according to the requirements of the particular kind of stream. The predefined stream-oriented attributes like T'Read and T'Write make dispatching calls on the Read and Write procedures of the Root_Stream_Type. (User-defined T'Read and T'Write attributes can also make such calls, or can call the Read and Write attributes of other types.)

package Ada.Streams
    with Pure, Nonblocking => False is

   type Root_Stream_Type is abstract tagged limited private
      with Preelaborable_Initialization;

   type Stream_Element        is mod   <implementation-defined>;
   type Stream_Element_Offset is range <implementation-defined>;
   type Stream_Element_Array  is array(Stream_Element_Offset range <>) of aliased Stream_Element;
   subtype Stream_Element_Count is Stream_Element_Offset range 0 .. Stream_Element_Offset'Last;

   procedure Read(Stream: in out Root_Stream_Type;
                  Item  : out Stream_Element_Array;
                  Last  : out Stream_Element_Offset) is abstract;
   procedure Write(Stream: in out Root_Stream_Type;
                   Item  : Stream_Element_Array) is abstract;
end Ada.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.

with Ada.IO_Exceptions;

package Ada.Streams.Stream_IO
   with Preelaborate, Global => in out synchronized is

   type Stream_Access is access all Root_Stream_Type'Class;
   type File_Type is limited private
      with Preelaborable_Initialization;
   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: File_Mode := Out_File;
                    Name: String    := "";
                    Form: String    := "");
   procedure Open(File: in out File_Type;
                  Mode: File_Mode;
                  Name: String;
                  Form: String := "");
   procedure Close (File: in out File_Type);
   procedure Delete(File: in out File_Type);
   procedure Reset (File: in out File_Type; Mode: File_Mode);
   procedure Reset (File: in out File_Type);

   function Mode       (File: File_Type) return File_Mode;
   function Name       (File: File_Type) return String;
   function Form       (File: File_Type) return String;
   function Is_Open    (File: File_Type) return Boolean;
   function End_Of_File(File: File_Type) return Boolean;
   function Stream     (File: File_Type) return Stream_Access;
      -- Return stream access for use with T'Input and T'Output

   -- Read array of stream elements from file
   procedure Read(File: File_Type;
                  Item: out Stream_Element_Array;
                  Last: out Stream_Element_Offset;
                  From: Positive_Count)
      with Global => overriding in out File;
   procedure Read(File: File_Type;
                  Item: out Stream_Element_Array;
                  Last: out Stream_Element_Offset)
      with Global => overriding in out File;
   
   -- Write array of stream elements into file
   procedure Write(File: File_Type; Item: Stream_Element_Array; To: Positive_Count)
      with Global => overriding in out File;
   procedure Write(File: File_Type; Item: Stream_Element_Array)
      with Global => overriding in out File;

   -- Operations on position within file
   procedure Set_Index(File: File_Type; To: Positive_Count)
      with Global => overriding in out File;

   function Index(File: File_Type) return Positive_Count;
   function Size (File: File_Type) return Count;

   procedure Set_Mode(File: in out File_Type; Mode: File_Mode);
   procedure Flush   (File: File_Type);

   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;

   package Wide_File_Names is
      procedure Create(File: in out File_Type;
                       Mode: File_Mode   := Out_File;
                       Name: Wide_String := "";
                       Form: Wide_String := "");
      procedure Open(File: in out File_Type;
                     Mode: File_Mode;
                     Name: Wide_String;
                     Form: Wide_String := "");

      function Name(File: File_Type) return Wide_String;
      function Form(File: File_Type) return Wide_String;
   end Wide_File_Names;

   package Wide_Wide_File_Names is
      procedure Create(File: in out File_Type;
                       Mode: File_Mode        := Out_File;
                       Name: Wide_Wide_String := "";
                       Form: Wide_Wide_String := "");
      procedure Open(File: in out File_Type;
                     Mode: File_Mode;
                     Name: Wide_Wide_String;
                     Form: Wide_Wide_String := "");

      function Name(File: File_Type) return Wide_Wide_String;
      function Form(File: File_Type) return Wide_Wide_String;
   end Wide_Wide_File_Names;
end Ada.Streams.Stream_IO;

Erroneous Execution

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.