tango.io.stream.Buffered

alias Bin;
alias Bout;

Shorthand aliases.

int printf(char*,...);

class BufferedInput: tango.io.device.Conduit.InputFilter, tango.io.model.IConduit.InputBuffer;

Buffers the flow of data from a upstream input. A downstream neighbour can locate and use this buffer instead of creating another instance of their own.

(Note that upstream is closer to the source, and downstream is further away.)

alias clear;

Clear/flush are the same.

alias input;

Access the source.

this(InputStream stream);

Construct a buffer.

Params:

InputStream stream	An input stream.
capacity	Desired buffer capacity.

Remarks:
Construct a Buffer upon the provided input stream.

this(InputStream stream, ulong capacity);

Construct a buffer.

Params:

InputStream stream	An input stream.
ulong capacity	Desired buffer capacity.

Remarks:
Construct a Buffer upon the provided input stream.

static InputBuffer create(InputStream stream);

Attempt to share an upstream Buffer, and create an instance where there's not one available.

Params:

InputStream stream

An input stream.

Remarks:
If an upstream Buffer instances is visible, it will be shared. Otherwise, a new instance is created based upon the bufferSize exposed by the stream endpoint (conduit).

final size_t populate();

Place more data from the source stream into this buffer, and return the number of bytes added. This does not compress the current buffer content, so consider doing that explicitly.

Returns:
Number of bytes added, which will be Eof when there is no further input available. Zero is also a valid response, meaning no data was actually added.

final void[] opSlice(size_t start, size_t end);

Return a void[] slice of the buffer from start to end, where end is exclusive.

final void[] slice();

Retrieve the valid content.

Returns:
A void[] slice of the buffer.

Remarks:
Return a void[] slice of the buffer, from the current position up to the limit of valid content. The content remains in the buffer for future extraction.

final void[] slice(size_t size, bool eat = true);

Access buffer content.

Params:

size_t size	Number of bytes to access.
bool eat	Whether to consume the content or not.

Returns:
The corresponding buffer slice when successful, or null if there's not enough data available (Eof; Eob).

Remarks:
Read a slice of data from the buffer, loading from the conduit as necessary. The specified number of bytes is sliced from the buffer, and marked as having been read when the 'eat' parameter is set true. When 'eat' is set false, the read position is not adjusted.

Note that the slice cannot be larger than the size of the buffer ~ use method fill(void[]) instead where you simply want the content copied, or use conduit.read() to extract directly from an attached conduit. Also note that if you need to retain the slice, then it should be .dup'd before the buffer is compressed or repopulated.

Examples:

                // create a buffer with some content
                auto buffer = new Buffer ("hello world");

                // consume everything unread
                auto slice = buffer.slice (buffer.readable);

final size_t reader(scope ulong delegate(const(void)[]) dg);

Read directly from this buffer.

Params:

ulong delegate(const(void)[]) dg

Callback to provide buffer access to.

Returns:
Returns whatever the delegate returns.

Remarks:
Exposes the raw data buffer at the current read position. The delegate is provided with a void[] representing the available data, and should return zero to leave the current read position intact.

If the delegate consumes data, it should return the number of bytes consumed; or IConduit.Eof to indicate an error.

size_t writer(scope ulong delegate(void[]) dg);

Write into this buffer.

Params:

ulong delegate(void[]) dg

The callback to provide buffer access to.

Returns:
Returns whatever the delegate returns.

Remarks:
Exposes the raw data buffer at the current write position, The delegate is provided with a void[] representing space available within the buffer at the current write position.

The delegate should return the appropriate number of bytes if it writes valid content, or IConduit.Eof on error.

final size_t read(void[] dst);

Transfer content into the provided dst.

Params:

void[] dst

Destination of the content.

Returns:
Return the number of bytes read, which may be less than dst.length. Eof is returned when no further content is available.

Remarks:
Populates the provided array with content. We try to satisfy the request from the buffer content, and read directly from an attached conduit when the buffer is empty.

final size_t fill(void[] dst, bool exact = false);

Fill the provided buffer. Returns the number of bytes actually read, which will be less that dst.length when Eof has been reached and Eof thereafter.

Params:

void[] dst	Where data should be placed.
bool exact	Whether to throw an exception when dst is not filled (an Eof occurs first). Defaults to false.

final bool skip(ptrdiff_t size);

Move the current read location.

Params:

ptrdiff_t size

The number of bytes to move.

Returns:
Returns true if successful, false otherwise.

Remarks:
Skip ahead by the specified number of bytes, streaming from the associated conduit as necessary.

Can also reverse the read position by 'size' bytes, when size is negative. This may be used to support lookahead operations. Note that a negative size will fail where there is not sufficient content available in the buffer (can't skip beyond the beginning).

final long seek(long offset, Anchor start = (Anchor).Begin);

Move the current read location.

final bool next(scope ulong delegate(const(void)[]) scan);

Iterator support.

Params:

ulong delegate(const(void)[]) scan

The delegate to invoke with the current content.

Returns:
Returns true if a token was isolated, false otherwise.

Remarks:
Upon success, the delegate should return the byte-based index of the consumed pattern (tail end of it). Failure to match a pattern should be indicated by returning an Eof

Each pattern is expected to be stripped of the delimiter. An end-of-file condition causes trailing content to be placed into the token. Requests made beyond Eof result in empty matches (length is zero).

Note that additional iterator and/or reader instances will operate in lockstep when bound to a common buffer.

final size_t reserve(size_t space);

Reserve the specified space within the buffer, compressing existing content as necessary to make room.

Returns the current read point, after compression if that was required.

final @property BufferedInput compress();

Compress buffer space.

Returns:
The buffer instance.

Remarks:
If we have some data left after an export, move it to front-of-buffer and set position to be just after the remains. This is for supporting certain conduits which choose to write just the initial portion of a request.

Limit is set to the amount of data remaining. Position is always reset to zero.

final size_t drain(OutputStream dst);

Drain buffer content to the specific conduit.

Returns:
Returns the number of bytes written, or Eof.

Remarks:
Write as much of the buffer that the associated conduit can consume. The conduit is not obliged to consume all content, so some may remain within the buffer.

const final const @property size_t limit();

Access buffer limit.

Returns:
Returns the limit of readable content within this buffer.

Remarks:
Each buffer has a capacity, a limit, and a position. The capacity is the maximum content a buffer can contain, limit represents the extent of valid content, and position marks the current read location.

const final const size_t capacity();

Access buffer capacity.

Returns:
Returns the maximum capacity of this buffer.

Remarks:
Each buffer has a capacity, a limit, and a position. The capacity is the maximum content a buffer can contain, limit represents the extent of valid content, and position marks the current read location.

const final const @property size_t position();

Access buffer read position.

Returns:
Returns the current read-position within this buffer.

Remarks:
Each buffer has a capacity, a limit, and a position. The capacity is the maximum content a buffer can contain, limit represents the extent of valid content, and position marks the current read location.

const final const @property size_t readable();

Available content.

Remarks:
Return count of readable bytes remaining in buffer. This is calculated simply as limit() - position().

inout(T)[] convert(T)(inout(void)[] x);

Cast to a target type without invoking the wrath of the runtime checks for misalignment. Instead, we truncate the array length.

final BufferedInput flush();

Clear buffer content.

Remarks:
Reset 'position' and 'limit' to zero. This effectively clears all content from the buffer.

final @property void input(InputStream source);

Set the input stream.

final void[] load(size_t max = (ulong).max);

Load the bits from a stream, up to an indicated length, and return them all in an array. The function may consume more than the indicated size where additional data is available during a block read operation, but will not wait for more than specified. An Eof terminates the operation.

Returns an array representing the content, and throws IOException on error.

class BufferedOutput: tango.io.device.Conduit.OutputFilter, tango.io.model.IConduit.OutputBuffer;

Buffers the flow of data from a upstream output. A downstream neighbour can locate and use this buffer instead of creating another instance of their own.

(Note that upstream is closer to the source, and downstream is further away.)

Don't forget to flush() buffered content before closing.

alias output;

access the sink

this(OutputStream stream);

Construct a buffer.

Params:

OutputStream stream	An input stream.
capacity	Desired buffer capacity.

Remarks:
Construct a Buffer upon the provided input stream.

this(OutputStream stream, ulong capacity);

Construct a buffer.

Params:

OutputStream stream	An input stream.
ulong capacity	Desired buffer capacity.

Remarks:
Construct a Buffer upon the provided input stream.

static OutputBuffer create(OutputStream stream);

Attempts to share an upstream BufferedOutput, and creates a new instance where there's not a shared one available.

Params:

OutputStream stream

An output stream.

Remarks:
Where an upstream instance is visible it will be returned. Otherwise, a new instance is created based upon the bufferSize exposed by the associated conduit

final void[] slice();

Retrieve the valid content.

Returns:
A void[] slice of the buffer.

Remarks:
Return a void[] slice of the buffer, from the current position up to the limit of valid content. The content remains in the buffer for future extraction.

final size_t write(const(void)[] src);

Emulate OutputStream.write().

Params:

const(void)[] src

The content to write.

Returns:
Return the number of bytes written, which may be less than provided (conceptually).

Remarks:
Appends src content to the buffer, flushing to an attached conduit as necessary. An IOException is thrown upon write failure.

final BufferedOutput append(const(void)[] src);

Append content.

Params:

const(void)[] src

The content to append. Returns a chaining reference if all content was written. Throws an IOException indicating Eof or Eob if not.

Remarks:
Append an array to this buffer, and flush to the conduit as necessary. This is often used in lieu of a Writer.

final BufferedOutput append(const(void)* src, size_t length);

Append content.

Params:

const(void)* src	The content to append.
size_t length	The number of bytes in src. Returns a chaining reference if all content was written. Throws an IOException indicating Eof or Eob if not.

Remarks:
Append an array to this buffer, and flush to the conduit as necessary. This is often used in lieu of a Writer.

const final const @property size_t writable();

Available space.

Remarks:
Return count of writable bytes available in buffer. This is calculated as capacity() - limit().

const final const @property size_t limit();

Access buffer limit.

Returns:
Returns the limit of readable content within this buffer.

Remarks:
Each buffer has a capacity, a limit, and a position. The capacity is the maximum content a buffer can contain, limit represents the extent of valid content, and position marks the current read location.

const final const size_t capacity();

Access buffer capacity.

Returns:
Returns the maximum capacity of this buffer.

Remarks:
Each buffer has a capacity, a limit, and a position. The capacity is the maximum content a buffer can contain, limit represents the extent of valid content, and position marks the current read location.

final bool truncate(size_t length);

Truncate buffer content.

Remarks:
Truncate the buffer within its extent. Returns true if the new length is valid, false otherwise.

T[] convert(T)(void[] x);

Cast to a target type without invoking the wrath of the runtime checks for misalignment. Instead, we truncate the array length.

final BufferedOutput flush();

Flush all buffer content to the specific conduit.

Remarks:
Flush the contents of this buffer. This will block until all content is actually flushed via the associated conduit, whereas drain() will not.

Throws an IOException on premature Eof.

final BufferedOutput copy(InputStream src, size_t max = -1);

Copy content via this buffer from the provided src conduit.

Remarks:
The src conduit has its content transferred through this buffer via a series of fill & drain operations, until there is no more content available. The buffer content should be explicitly flushed by the caller.

Throws an IOException on premature Eof.

final size_t drain(OutputStream dst);

Drain buffer content to the specific conduit.

Returns:
Returns the number of bytes written, or Eof.

Remarks:
Write as much of the buffer that the associated conduit can consume. The conduit is not obliged to consume all content, so some may remain within the buffer.

final BufferedOutput clear();

Clear buffer content.

Remarks:
Reset 'position' and 'limit' to zero. This effectively clears all content from the buffer.

final @property void output(OutputStream sink);

Set the output stream.

final long seek(long offset, Anchor start = (Anchor).Begin);

Seek within this stream. Any and all buffered output is disposed before the upstream is invoked. Use an explicit flush() to emit content prior to seeking.

final size_t writer(scope ulong delegate(void[]) dg);

Write into this buffer.

Params:

ulong delegate(void[]) dg

The callback to provide buffer access to.

Returns:
Returns whatever the delegate returns.

Remarks:
Exposes the raw data buffer at the current write position, The delegate is provided with a void[] representing space available within the buffer at the current write position.

The delegate should return the appropriate number of bytes if it writes valid content, or Eof on error.