tango.io.device.Array

License:

BSD style: see license.txt

Version:

Mar 2004: Initial release Dec 2006: Outback release

Authors:

Kris
class Array : Conduit, InputBuffer, OutputBuffer, Conduit.Seek #
Array manipulation typically involves appending, as in the following example:
1
2
3
4
5
6
7
// create a small buffer
auto buf = new Array (256);

auto foo = "to write some D";

// append some text directly to it
buf.append ("now is the time for all good men ").append(foo);
Alternatively, one might use a formatter to append content:
1
2
auto output = new TextOutput (new Array(256));
output.format ("now is the time for {} good men {}", 3, foo);

A slice() method returns all valid content within the array.

invariant #
Ensure the buffer remains valid between method calls
this(size_t capacity, size_t growing = 0) #
Construct a buffer

Params:

capacitythe number of bytes to make available
growingchunk size of a growable instance, or zero to prohibit expansion

Remarks:

Construct a Buffer with the specified number of bytes and expansion policy.
this(void[] data) #
Construct a buffer

Params:

datathe backing array to buffer within

Remarks:

Prime a buffer with an application-supplied array. All content is considered valid for reading, and thus there is no writable space initially available.
this(void[] data, size_t readable) #
Construct a buffer

Params:

datathe backing array to buffer within
readablethe number of bytes initially made readable

Remarks:

Prime buffer with an application-supplied array, and indicate how much readable data is already there. A write operation will begin writing immediately after the existing readable content.

This is commonly used to attach a Buffer instance to a local array.

char[] toString() [override, final] #
Return the name of this conduit
size_t read(void[] dst) [override, final] #
Transfer content into the provided dst

Params:

dstdestination 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.
size_t write(void[] src) [override, final] #
Emulate OutputStream.write()

Params:

srcthe content to write

Returns:

return the number of bytes written, which may be less than provided (conceptually). Returns Eof when the buffer becomes full.

Remarks:

Appends src content to the buffer, expanding as required if configured to do so (via the ctor).
size_t bufferSize() [override, final] #
Return a preferred size for buffering conduit I/O
void detach() [override] #
Release external resources
long seek(long offset, Anchor anchor = Anchor.Begin) [override] #
Seek within the constraints of assigned content
Array assign(void[] data) #
Reset the buffer content

Params:

datathe backing array to buffer within. All content is considered valid

Returns:

the buffer instance

Remarks:

Set the backing array with all content readable.
Array assign(void[] data, size_t readable) #
Reset the buffer content

Params:

datathe backing array to buffer within
readablethe number of bytes within data considered valid

Returns:

the buffer instance

Remarks:

Set the backing array with some content readable. Use clear() to reset the content (make it all writable).
void[] assign() [final] #
Access buffer content

Remarks:

Return the entire backing array.
void[] opSlice(size_t start, size_t end) [final] #
Return a void[] read of the buffer from start to end, where end is exclusive
void[] slice() [final] #
Retrieve all readable content

Returns:

a void[] read of the buffer

Remarks:

Return a void[] read of the buffer, from the current position up to the limit of valid content. The content remains in the buffer for future extraction.
void[] slice(size_t size, bool eat = true) [final] #
Access buffer content

Params:

sizenumber of bytes to access
eatwhether 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:

Slices readable data. The specified number of bytes is readd 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 read(void[]) instead where you simply want the content copied. Note also that the slice should be .dup'd if you wish to retain it.

Examples:

1
2
3
4
5
// create a buffer with some content
auto buffer = new Buffer ("hello world");

// consume everything unread
auto slice = buffer.slice (buffer.readable);
Array append(void[] src) [final] #
Append content

Params:

srcthe content to _append
lengththe 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
bool next(size_t delegate (void[]) scan) [final] #
Iterator support

Params:

scanthe delagate 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 IConduit.Eof

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

size_t readable() [final] #
Available content

Remarks:

Return count of _readable bytes remaining in buffer. This is calculated simply as limit() - position()
size_t writable() [final] #
Available space

Remarks:

Return count of _writable bytes available in buffer. This is calculated simply as capacity() - limit()
size_t limit() [final] #
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.
size_t capacity() [final] #
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.
size_t position() [final] #
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.
Array clear() [final] #
Clear array content

Remarks:

Reset 'position' and 'limit' to zero. This effectively clears all content from the array.
Array flush() [override, final] #
Emit/purge buffered content
size_t writer(size_t delegate (void[]) dg) [final] #
Write into this buffer

Params:

dgthe 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.

size_t reader(size_t delegate (void[]) dg) [final] #
Read directly from this buffer

Params:

dgcallback 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 expand(size_t size) [private, final] #
Expand existing buffer space

Returns:

Available space, without any expansion

Remarks:

Make some additional room in the buffer, of at least the given size. Should not be public in order to avoid issues with non-growable subclasses
T[] convert(T)(void[] x) [private, static] #
Cast to a target type without invoking the wrath of the runtime checks for misalignment. Instead, we truncate the array length