Streaming transport interfaces: input

[Pelle]

On 10/14/2010 05:34 PM, Andrei Alexandrescu wrote:
> Starting a new thread from Denis' question:
>
>> Can we outline basic Stream interface now so that we could move on?
>
> Here's the input transport layer. Transport has no concern for
> formatting - it just moves stuff around.
>
> interface TransportBase
> {
> /// True if stream has no more data.
> @property bool empty();
> /// True if the position property works
> @property bool positionable();
> /// Gives current position in stream
> @property ulong position();
> /// Moves stream to absolute position pos
> @property void position(ulong pos);
> }
>
> interface InputBinaryTransport : TransportBase
> {
> /// Reads up to target.length bytes into target,
> /// returns size of data read. If target.length < 1 throws.
> size_t read(ubyte[] target);
> /// Appends to target up until delimiter is found or end of stream.
> /// The delimiter is included in the target. Returns number
> /// of bytes read.
> size_t appendDelim(ref ubyte[] target, in ubyte[] delimiter);
> }
>
> interface InputTextTransport : TransportBase
> {
> /// Returns the native character size: 1 for UTF-8, 2 for UTF-16,
> /// 4 for UTF-32, 0 for nonstandard native encodings.
> @property size_t nativeUTFWidth();
>
> /// Reads complete UTF code points into target, without going
> /// beyond target.length. Returns number of code units read.
> /// If target.length < 4 throws.
> size_t read(char[] target);
> /// Appends to target up until delimiter is found or end of stream.
> /// The delimiter is included in the target. Returns number of
> /// code units read.
> size_t appendDelim(ref char[] target, in char[] delimiter);
>
> /// Reads complete UTF code points into target, without going
> /// beyond target.length. Returns number of code units read.
> /// If target.length < 2 throws.
> size_t read(wchar[] target);
> /// Appends to target up until delimiter is found or end of stream.
> /// The delimiter is included in the target. Returns number of
> /// code units read.
> size_t appendDelim(ref wchar[] target, in wchar[] delimiter);
>
> /// Reads complete UTF code points into target, without going
> /// beyond target.length. Returns number of code units read.
> /// If target.length < 1 throws.
> size_t read(dchar[] target);
> /// Appends to target up until delimiter is found or end of stream.
> /// The delimiter is included in the target. Returns number of
> /// code units read.
> size_t appendDelim(ref dchar[] target, in dchar[] delimiter);
> }
>
> Please destroy.
>
>
> Andrei

Why is positionable in TransportBase? Should it not be a separate interface?

Also, shouldn't the reads accept any output range? appendDelim as well. 
This would do away with the two extra versions in the text input.

Why does the reads throw on maybe-too-small arrays? I would expect them 
to read at best effort and return 0 if they fail. As they read 0 bytes.

I am no expert on this subject. Disclaimer, etc :-)