13.13.1 The Package Streams
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.)
2
package Ada.Streams
is
pragma Pure(Streams)
{unpolluted}
;
3/2
{
AI95-00161-01}
type Root_Stream_Type
is abstract tagged limited private;
pragma Preelaborable_Initialization(Root_Stream_Type);4/1
{
8652/0044}
{
AI95-00181-01}
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
{
AI95-00227-01}
The Read operation transfers
Item'Length 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 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.
9.a/2
Discussion: {
AI95-00114-01}
The index subtype of Stream_Element_Array is Stream_Element_Offset
because we wish to allow maximum flexibility. Most Stream_Element_Arrays
will probably have a lower bound of 0 or 1, but other lower bounds, including
negative ones, make sense in some situations.
9.b/2
{
AI95-00114-01}
Note that there are some language-defined subprograms
that fill part of a Stream_Element_Array, and return the index of the
last element filled as a Stream_Element_Offset. The Read procedures declared
here, Streams.Stream_IO (see A.12.1), and
System.RPC (see E.5) behave in this manner.
These will raise Constraint_Error if the resulting Last value is not
in Stream_Element_Offset. This implies that the Stream_Element_Array
passed to these subprograms should not have a lower bound of Stream_Element_Offset'First,
because then a read of 0 elements would always raise Constraint_Error.
A better choice of lower bound is 1. Implementation Permissions
9.1/1
{
8652/0044}
{
AI95-00181-01}
If Stream_Element'Size is not a multiple of System.Storage_Unit,
then the components of Stream_Element_Array need not be aliased.
9.b.1/2
Ramification: {
AI95-00114-01}
If the Stream_Element'Size is less than the size
of System.Storage_Unit, then components of Stream_Element_Array need
not be aliased. This is necessary as the components of type Stream_Element
size might not be addressable on the target architecture architechture.
10
11/2
33 {
AI95-00227-01}
If the end of stream has been reached, and Item'First
is Stream_Element_Offset'First, Read will raise Constraint_Error.
11.a/2
Ramification: Thus,
Stream_Element_Arrays should start at 0 or 1, not Stream_Element_Offset'First.
Extensions to Ada 95
11.b/2
{
AI95-00161-01}
{extensions to Ada 95} Amendment
Correction: Added pragma Preelaborable_Initialization
to type Root_Stream_Type. Wording Changes from Ada 95
11.c/2
11.d/2
{
AI95-00227-01}
Fixed the wording for Read to properly define the
result in Last when no stream elements are transfered.
Sponsored by Ada-Europe