Ada Reference Manual (Ada 2022)Legal Information
Contents   Index   References   Search   Previous   Next 

13.13.1 The Streams Subsystem

Static Semantics

1
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.)
1.1/5
 The library package Ada.Streams has the following declaration:
2/5
package Ada.Streams
    with Pure, Nonblocking => False is
3/2
    type Root_Stream_Type is abstract tagged limited private
        with Preelaborable_Initialization;
4/1
    type Stream_Element is mod implementation-defined;
    type Stream_Element_Offset is range implementation-defined;
    subtype Stream_Element_Count is
        Stream_Element_Offset range 0..Stream_Element_Offset'Last;
    type Stream_Element_Array is
        array(Stream_Element_Offset range <>) of aliased Stream_Element;
5
    procedure Read(
      Stream : in out Root_Stream_Type;
      Item   : out Stream_Element_Array;
      Last   : out Stream_Element_Offset) is abstract;
6
    procedure Write(
      Stream : in out Root_Stream_Type;
      Item   : in Stream_Element_Array) is abstract;
7
private
   ... -- not specified by the language
end Ada.Streams;
8/2
The Read operation transfers stream elements from the specified stream to fill the array Item. Elements are transferred until Item'Length elements have been transferred, or until the end of the stream is reached. If any elements are transferred, the index of the last stream element transferred is returned in Last. Otherwise, Item'First - 1 is returned in Last. Last is less than Item'Last only if the end of the stream is reached.
9
The Write operation appends Item to the specified stream.
10/5
Three additional packages provide stream implementations that do not make use of any file operations. These packages provide the same operations, with Streams.Storage providing an abstract interface, and two child packages providing implementations of that interface. The difference is that for Streams.Storage.Bounded, the maximum storage is bounded.
11/5
The library package Ada.Streams.Storage has the following declaration:
12/5
package Ada.Streams.Storage
   with Pure, Nonblocking is
13/5
   type Storage_Stream_Type is abstract new Root_Stream_Type with private;
14/5
   function Element_Count (Stream : Storage_Stream_Type)
      return Stream_Element_Count is abstract;
15/5
   procedure Clear (Stream : in out Storage_Stream_Type) is abstract;
16/5
private
   ... -- not specified by the language
end Ada.Streams.Storage;
17/5
The library package Ada.Streams.Storage.Unbounded has the following declaration:
18/5
package Ada.Streams.Storage.Unbounded
   with Prelaborated, Nonblocking, Global => in out synchronized is
19/5
   type Stream_Type is new Storage_Stream_Type with private
      with Default_Initial_Condition =>
          Element_Count (Stream_Type) = 0;
20/5
   overriding
   procedure Read (
      Stream : in out Stream_Type;
      Item   : out Stream_Element_Array;
      Last   : out Stream_Element_Offset)
      with Post =>
          (declare
              Num_Read : constant Stream_Element_Count :=
                 Stream_Element_Count'Min
                    (Element_Count(Stream)'Old, Item'Length);
           begin
              Last = Num_Read + Item'First - 1 and
              Element_Count (Stream) =
                 Element_Count (Stream)'Old - Num_Read);
21/5
   overriding
   procedure Write (
      Stream : in out Stream_Type;
      Item   : in Stream_Element_Array)
      with Post =>
         Element_Count (Stream) =
         Element_Count (Stream)'Old + Item'Length;
22/5
   overriding
   function Element_Count (Stream : Stream_Type)
      return Stream_Element_Count;
23/5
   overriding
   procedure Clear (Stream : in out Stream_Type)
      with Post => Element_Count (Stream) = 0;
24/5
private
   ... -- not specified by the language
end Ada.Streams.Storage.Unbounded;
25/5
The library package Ada.Streams.Storage.Bounded has the following declaration:
26/5
package Ada.Streams.Storage.Bounded
    with Pure, Nonblocking is
27/5
   type Stream_Type (Max_Elements : Stream_Element_Count)
      is new Storage_Stream_Type with private
         with Default_Initial_Condition =>
            Element_Count (Stream_Type) = 0;
28/5
   overriding
   procedure Read (
      Stream : in out Stream_Type;
      Item   : out Stream_Element_Array;
      Last   : out Stream_Element_Offset)
      with Post =>
          (declare
              Num_Read : constant Stream_Element_Count :=
                 Stream_Element_Count'Min
                    (Element_Count(Stream)'Old, Item'Length);
           begin
              Last = Num_Read + Item'First - 1 and
              Element_Count (Stream) =
                 Element_Count (Stream)'Old - Num_Read);
29/5
   overriding
   procedure Write (
      Stream : in out Stream_Type;
      Item   : in Stream_Element_Array)
      with Pre =>
              Element_Count (Stream) + Item'Length <= Stream.Max_Elements
              or else (raise Constraint_Error),
           Post =>
              Element_Count (Stream) =
              Element_Count (Stream)'Old + Item'Length;
30/5
   overriding
   function Element_Count (Stream : Stream_Type)
      return Stream_Element_Count
      with Post => Element_Count'Result <= Stream.Max_Elements;
31/5
   overriding
    procedure Clear (Stream : in out Stream_Type)
       with Post => Element_Count (Stream) = 0;
32/5
private
   ... -- not specified by the language
end Ada.Streams.Storage.Bounded;
33/5
The Element_Count functions return the number of stream elements that are available for reading from the given stream.
34/5
The Read and Write procedures behave as described for package Ada.Streams above. Stream elements are read in FIFO (first-in, first-out) order; stream elements are available for reading immediately after they are written.
35/5
The Clear procedures remove any available stream elements from the given stream.

Implementation Permissions

36/5
If Stream_Element'Size is not a multiple of System.Storage_Unit, then the components of Stream_Element_Array will not be aliased. 

Implementation Advice

37/5
Streams.Storage.Bounded.Stream_Type objects should be implemented without implicit pointers or dynamic allocation.
38
NOTE 1   See A.12.1, “The Package Streams.Stream_IO” for an example of extending type Root_Stream_Type.
39/2
NOTE 2   If the end of stream has been reached, and Item'First is Stream_Element_Offset'First, Read will raise Constraint_Error. 

Contents   Index   References   Search   Previous   Next 
Ada-Europe Ada 2005 and 2012 Editions sponsored in part by Ada-Europe