[m-rev.] for review: add unboxed_readers to the stream module

[Peter Wang]

On Sat, 18 Apr 2020 15:34:40 +1000 (AEST), Julien Fischer <jfischer at opturion.com> wrote:
> 
> For review by anyone.
> 
> ------------------------
> 
> Add unboxed_readers to the stream module.
> 
> library/stream.m:
>      Add a new type of reader, unboxed_reader.  These provide a 'get'
>      operation that does not need to box its output in the non-error case.
> 
> library/io.m:
>      Add an unboxed_reader instance for text_input_streams and chars.
> 
> NEWS:
>     Announce the addition.
> 
> Julien.
> 

> @@ -122,6 +123,30 @@
>           State::di, State::uo) is det
>   ].
> 
> +    % An unboxed_reader stream is like a reader stream except that it provides
> +    % an interface that avoids a memory allocation when there is no error.
> +    %
> +:- typeclass unboxed_reader(Stream, Unit, State, Error)
> +    <= (input(Stream, State), error(Error), (Stream, Unit -> Error)) where
> +[
> +    % Get the next unit from the given stream.
> +    %
> +    % The unboxed_get operation should block until the next unit is available,
> +    % or the end of the stream or an error is detected.
> +    %
> +    % If a call to unboxed_get/5 returns `eof', all further calls to get/4,
> +    % unboxed_get/5 or bulk_get/9 for that stream return `eof'. If a call to
> +    % unboxed_get/5 returns `error(...)', all further calls to get/4,
> +    % unboxed_get/5 or bulk_get/4 for that stream return an error, although not
> +    % necessarily the same one.
> +    %
> +    % XXX We should provide an interface to allow the user to reset the
> +    % error status to try again if an error is transient.
> +    %
> +    pred unboxed_get(Stream::in, result(Error)::out, Unit::out,
> +        State::di, State::uo) is det
> +].
> +

It should say something about the return value in case of eof or error,
i.e. no particular value is guaranteed. io.read_char_unboxed also lacks
that documentation, oops.

I prefer the name io.read_char_unboxed over io.unboxed_read_char as it
is a minor variation on io.read_char, and keeps the important part (the
operation) up front. Therefore, I suggest to name the new method
get_unboxed, but it's only a slight suggestion.

reader_unboxed for the typeclass name does read awkwardly, though.

Peter