Ada Programming/Libraries/Ada.Streams

is a unit of the Predefined Language Environment since Ada 95.

Description
Ada streams are a  powerful I/O mechanism that allows reading and writing any type of object to any type of "medium" (e.g., a network connection, a file on a disk, a magnetic tape, a memory buffer). Streams are somewhat obscure for a beginner; this is because of the "double generality": generality about the object to be written/read and generality about the medium involved. The objective of this section is to give an intuitive introduction to Ada streams, skipping some of the finer details. The reader is referred for a more precise and detailed description of Ada streams to the Ada Reference Manual, in particular.

Concepts
The language designers split the problem of writing an object over a medium into two sub-problems:


 * 1) Convert the object in a sequence of bits
 * 2) Write the bits over the stream

Note that the first step depends only on the object to be sent and not on the actual medium. On the other hand, the details of the second step depend only on the employed medium and not on the object type.

Similarly, in order to "read" an object from a network connection one must


 * 1) Read a block of bits from the stream
 * 2) Parse the read block and convert it into an object

Note again that the first step depends only on the medium, while the second one depends only on the object type.

Abstract streams
The abstract model for an Ada stream is, basically, a sequence of raw data (Stream_Element) that can be read and written in blocks. This abstract view is formalized in the Stream package definition (from RM with some omissions and comments added)

Ada.Streams Root_Stream_Type    ; Stream_Element  implementation defined; Stream_Element_Offset  implementation defined; Stream_Element_Array (Stream_Element_Offset <>)   Stream_Element; Read (          Stream :   Root_Stream_Type;           Item   :  Stream_Element_Array;           Last   :  Stream_Element_Offset)  ; Write (          Stream :   Root_Stream_Type;           Item   :  Stream_Element_Array)  ; implementation defined... Ada.Streams;

Since the type Root_Stream_Type is, one cannot create objects of type Root_Stream_Type, but must first derive a new type from Root_Stream_Type. Ada.Streams just specifies the minimal interface that a stream must grant: with a stream we must be able to


 * read a block of data (with the procedure Read) and
 * write a block of data (with Write).

Typically for every new medium (for example, network connections, disk files, memory buffers) one will derive  a new type specialized to read and write to that medium. Note that both Read and Write are abstract, so that any non- type must necessarily override them with new procedures that will take care of the details of reading/writing from/to a specific medium.

Note that the minimal interface of Ada.Streams does not include, for example, functions to open or close a stream, nor functions to check, say, an End-Of-Stream condition. This is reasonable since the details of the interfaces of those functions depend on the specific medium: a function that opens a stream associated to a file will expect a file name as argument, a function for opening a network stream will probably expect a network address and a function for opening the stream associated to a memory buffer will probably need the address and size of the buffer. It will be the duty of the package that derives from Root_Stream_Type to define those "auxiliary" functions.

Serialization functions
The second ingredient in the Ada stream system is what we called serialization functions, that is, the functions whose duty is to convert an Ada object to a sequence of Stream_Elements and vice-versa. Actually, we will see in a moment that the serialization functions do not interact with the caller by passing back and forth arrays of Stream_Element's, rather they interact directly with the streams.

The serialization functions associated to a given type are defined as type attributes. For every subtype S of a type T, Ada defines the following attributes associated to stream-related functions and procedures

We will first describe S'Read and S'Write since they are the simplest and, in some sense, the most "primitive" ones.

Write attribute
Procedure S'Write is defined in as follows (remember that S is a subtype of type T)

S'Write(        Stream :    Ada.Streams.Root_Stream_Type'Class;         Item   :   T);

The duty of S'Write is to convert Item to a sequence of Stream_Elements and write the result on Stream. Note that Stream is an access to class-wide type Root_Stream_Type', therefore the programmer can use S'Write with any stream type derived from Root_Stream_Type.

According to, Ada defines default implementations for S' as follows


 * For elementary types (e.g., Integers, Character, Float) the default implementations write a suitable representation of Item to Stream. That representation is implementation dependent but, most of the time, this corresponds simply to the in-memory representation.
 * For composite types (e.g., record and array) the default implementation writes each component (array entry or record component) using the corresponding S' procedure. Note that no other information is written.  For example, if Item is an array, the array dimensions are not written; if Item has a discriminant with no default value, the discriminant is not written.  In some sense, S' writes a very "raw" representation of Item to Stream.

Clearly, the default implementation, being dependent on the machine and compiler, can be useful only if the data is written and read by programs compiled with the same compiler. If the data, for example, is to be sent across the network and read by a program written in another language, running on an unknown architecture, it is important for the programmer to control the format of the data sent over the wire. Because of this exigence, Ada allows the programmer to override S' (and the other stream-related functions described in the following), using an attribute definition clause (RM ):

S' user_defined_subprogram;

Suppose, for example, a network protocol requires to format data in the following textual length-type-value format


 * Integer values are formatted as "&lt;len&gt; i &lt;value&gt;", where &lt;len&gt; is the number of digits used to represent the integer and &lt;value&gt; is the integer expressed in base 10. (For example, the integer 42 would be represented as "2i42")

The following code defines a suitable S'Write procedure for the integer case (Note: for the sake of simplicity, the following code supposes that each Stream_Element is 8 bits long)

Example Int  Integer; Int_Array  (Int  &lt;&gt;) of Int; Print (            Stream :    Ada.Streams.Root_Stream_Type';             Item   :   Int); Int' Print; Example;

Example Print (          Stream :    Ada.Streams.Root_Stream_Type';           Item   :   Int) -- Convert Item to String (with no trailing space) Value : String := Trim(Int'Image(Item), Left); -- Convert Value'Length to String (with no trailing space) Len   : String := Trim(Integer'Image(Value'Length), Left); Descr : String := Len & 'i' & Value; Buffer : Stream_Element_Array (1 .. Stream_Element_Offset (Descr')); -- Copy Descr to Buffer I Buffer' Buffer (I) := Stream_Element (Character' (Descr (Integer (I)))); ;           -- Write the result to Stream Stream.Write(Buffer); Print; Example;

Note the structure of Print: first Item is "serialized" in a sequence of Stream_Element (contained in Buffer), then such a sequence is written to Stream by calling the Write method (that will take care of the details of writing on Stream). Suppose now that one wants to print the description of 42 to the standard output. The following code can be used

Ada.Text_IO.Text_Streams; Ada.Text_IO; Int'Write (Text_Streams.Stream (Current_Output), 42);

The result will be "2i42" printed on the standard output. Note that the following code

Int_Array'Write (Text_Streams.Stream (Current_Output), (1=>42, 2=>128, 3=>6));

would write on standard output the string "2i42_3i128_1i6" (the '_' are not actually present; they have been added for readability) corresponding to calling Int'Write on 42, 128 and 6 in sequence. Note that the array dimensions are not written.

If one wanted to send the same description across a TCP connection, the following code could be used (with GNAT)

GNAT.Sockets; GNAT; ...    Sock   : Sockets.Socket_Type; Server : Sockets.Sock_Addr_Type := server address; ...    Sockets.Create_Socket (Sock); Sockets.Connect_Socket (Sock, Server); Int'Write (Sockets.Stream (Sock), 42); Int_Array'Write (Sockets.Stream (Sock), (1=>42, 2=>128, 3=>6));

Read attribute
Procedure S'Read is defined in as follows

S'Read(        Stream :    Ada.Streams.Root_Stream_Type'Class;         Item   :   T);

Its behavior is clearly symmetric to the one of S'Write: S'Read reads one or more Stream_Element from Stream and "parse" them to construct Item. Similarly to the case of S'Write, Ada defines default implementations for S'Read that the programmer can override by using the attribute definition clause

S'Read ...

For example, the following procedure could be assigned to type Int with  Int'Read Parse;.

Parse (                   Stream :    Root_Stream_Type'Class;                    Item   :  Int) Len   : Integer := 0; Buffer : Stream_Element_Array (1 .. 1); Last  : Stream_Element_Offset; Zero  : Stream_Element := Stream_Element (Character'Pos ('0')); Nine  : Stream_Element := Stream_Element (Character'Pos ('9')); Stream.Read (Buffer, Last); (Buffer (1) Zero .. Nine); Len := Len * 10 + Integer (Buffer (1) - Zero); ;      Character'Val (Integer (Buffer (1))) /= 'i'           Data_Error; ;     Item := 0; I 1 .. Len Stream.Read (Buffer, Last); Item := 10 * Item + Int (Buffer (1) - Zero); ;   Parse;

Output attribute
Procedure S' is defined in as follows

S'(        Stream :    Ada.Streams.Root_Stream_Type';         Item   :   T);

S' differs from S' in that its default implementation


 * first it writes arrays bound (if S is an array) and discriminants (if S is a record).
 * then it calls S' to write Item itself

Note that the bounds or the discriminant are written by calling the respective S' procedures. Therefore, since Int_Array was defined above as an array of Int indexed by Int, the following line

Int_Array'Output (Text_Streams.Stream (Current_Output), (1 => 42, 2 => 128, 3 => 6));

would produce (the '_' are added for readability and are not actually present in the output)

1i1_1i3_2i42_3i128_1i6

Note the array bounds "1i1" and "1i3" at the beginning of the line.

Input attribute
Function S' is defined in as follows

S'Input(        Stream :    Ada.Streams.Root_Stream_Type') T;

S' is for S' what S' is for S' in the sense that S'


 * first it reads the bounds or the discriminants (using the corresponding S')
 * it uses the read values to create the object to be returned
 * it calls the corresponding S' to initialize the object

Note that S' is a function, while S' is a procedure. This is coherent with the fact when S' is called any bound and/or discriminant must be already known, so that the caller can create the object and pass it to S'. With S', on the other hand, the bounds/discriminants are not known, but read from the stream; therefore, the burden of creating the object is on S'.

Class-wide Read and Write
Note that S' and S' are not primitive subprograms of S and they cannot be dynamically dispatching, even if S is a tagged type. In order to allow for dynamical dispatching of S' and S' methods, defines procedures

S''(     Stream :    Ada.Streams.Root_Stream_Type'Class;      Item   :  T'Class); S''(     Stream :    Ada.Streams.Root_Stream_Type'Class;      Item   :  T'Class);

Note that in both cases the type of Item is T', so Item can be of any type derived from T. The behavior of those procedures is to dispatch to the actual S' or S' identified by the tag of Item. See Ada Programming/Input Output/Stream Tutorial/Example for an example of usage of the class-wide stream attributes S and S.

Class-wide Input and Output
Similarly to the case of S' and S', defines the class-wide versions of S' and S'

S''(     Stream :    Ada.Streams.Root_Stream_Type'Class;      Item   :  T') S''(     Stream :    Ada.Streams.Root_Stream_Type'Class) T';

Their default behavior is almost obvious when one remembers that a tagged type can actually be considered as a record with an "hidden discriminant"


 * S first writes the tag to Stream by first converting it to string and then calling String' on the result. Successively, S dispatches to the subprogram S'  of the specific type identified by the tag.
 * S first reads the tag from Stream by first calling String'Input and converting the result to a tag. Successively, S dispatches to the subprogram S' of the specific type identified by the tag.

See for a more detailed and precise explanation. See Ada Programming/Libraries/Ada.Streams/Example for an example of usage of the class-wide stream attributes.

Specification
Pure Streams Root_Stream_Type Preelaborable_Initialization Root_Stream_Type Stream_Element  implementation_defined Stream_Element_Offset implementation_defined implementation_defined Stream_Element_Count Stream_Element_Offset 0Stream_Element_Offset Stream_Element_Array Stream_Element_Offset    Stream_Element Read Stream   Root_Stream_Type Item    Stream_Element_Array Last    Stream_Element_Offset Write Stream   Root_Stream_Type Item    Stream_Element_Array Import Ada Root_Stream_Type AdaStreams

Wikibook

 * Ada Programming
 * Ada Programming/Object Orientation