pragma Stream_Convert ( [Entity =>] type_LOCAL_NAME, [Read =>] function_NAME, [Write =>] function_NAME);
This pragma provides an efficient way of providing user-defined stream attributes. Not only is it simpler to use than specifying the attributes directly, but more importantly, it allows the specification to be made in such a way that the predefined unit Ada.Streams is not loaded unless it is actually needed (i.e. unless the stream attributes are actually used); the use of the Stream_Convert pragma adds no overhead at all, unless the stream attributes are actually used on the designated type.
The first argument specifies the type for which stream functions are provided. The second parameter provides a function used to read values of this type. It must name a function whose argument type may be any subtype, and whose returned type must be the type given as the first argument to the pragma.
The meaning of the
Read parameter is that if a stream attribute directly
or indirectly specifies reading of the type given as the first parameter,
then a value of the type given as the argument to the Read function is
read from the stream, and then the Read function is used to convert this
to the required target type.
Write parameter specifies how to treat write attributes
that directly or indirectly apply to the type given as the first parameter.
It must have an input parameter of the type specified by the first parameter,
and the return type must be the same as the input type of the Read function.
The effect is to first call the Write function to convert to the given stream
type, and then write the result type to the stream.
The Read and Write functions must not be overloaded subprograms. If necessary renamings can be supplied to meet this requirement. The usage of this attribute is best illustrated by a simple example, taken from the GNAT implementation of package Ada.Strings.Unbounded:
function To_Unbounded (S : String) return Unbounded_String renames To_Unbounded_String; pragma Stream_Convert (Unbounded_String, To_Unbounded, To_String);
The specifications of the referenced functions, as given in the Ada Reference Manual are:
function To_Unbounded_String (Source : String) return Unbounded_String; function To_String (Source : Unbounded_String) return String;
The effect is that if the value of an unbounded string is written to a stream,
then the representation of the item in the stream is in the same format that
would be used for
Standard.String'Output, and this same representation
is expected when a value of this type is read from the stream. Note that the
value written always includes the bounds, even for Unbounded_String’Write,
since Unbounded_String is not an array type.
Note that the
Stream_Convert pragma is not effective in the case of
a derived type of a non-limited tagged type. If such a type is specified then
the pragma is silently ignored, and the default implementation of the stream
attributes is used instead.