Array manipulation typically involves appending, as in the
following example:
// 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:
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.
- this(ulong capacity, ulong growing = cast(ulong)0);
- Construct a buffer.
Params:
ulong capacity |
The number of bytes to make available. |
ulong growing |
Chunk 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:
void[] data |
The 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, ulong readable);
- Construct a buffer.
Params:
void[] data |
The backing array to buffer within. |
ulong readable |
The 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.
- final immutable(char)[] toString();
- Return the name of this conduit.
- 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 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). 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).
- const final const size_t bufferSize();
- Return a preferred size for buffering conduit I/O.
- void detach();
- Release external resources.
- long seek(long offset, Anchor anchor = (Anchor).Begin);
- Seek within the constraints of assigned content.
- Array assign(void[] data);
- Reset the buffer content.
Params:
void[] data |
The 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:
void[] data |
The backing array to buffer within. |
size_t readable |
The 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).
- final void[] assign();
- Access buffer content.
Remarks:
Return the entire backing array.
- final void[] opSlice(size_t start, size_t end);
- Return a void[] read of the buffer from start to end, where
end is exclusive.
- final void[] slice();
- 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.
- 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:
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:
// create a buffer with some content
auto buffer = new Buffer ("hello world");
// consume everything unread
auto slice = buffer.slice (buffer.readable);
- final Array append(const(void)[] src);
- Append content.
Params:
const(void)[] src |
The content to append. |
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.
- final bool next(scope ulong delegate(const(void)[]) scan);
- Iterator support.
Params:
ulong delegate(const(void)[]) scan |
The 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.
- 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().
- const final const @property size_t writable();
- Available space.
Remarks:
Return count of writable bytes available in buffer. This is
calculated simply 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.
- const final const 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.
- final Array clear();
- Clear array content.
Remarks:
Reset 'position' and 'limit' to zero. This effectively
clears all content from the array.
- final Array flush();
- Emit/purge buffered content.
- 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 IConduit.Eof on error.
- 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.
- 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.