License:
BSD style: see license.txtVersion:
Mar 2004: Initial release Dec 2006: Outback releaseAuthors:
KrisParams:
stream | an input stream |
capacity | desired buffer capacity |
Remarks:
Construct a Buffer upon the provided input stream.Params:
stream | an input stream |
capacity | desired buffer capacity |
Remarks:
Construct a Buffer upon the provided input stream.Params:
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).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.Returns:
a void[] slice of the bufferRemarks:
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.Params:
size | number of bytes to access |
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:
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); |
Params:
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.Params:
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.Params:
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.Params:
dst | where data should be placed |
exact | whether to throw an exception when dst is not filled (an Eof occurs first). Defaults to false |
Params:
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).Params:
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.Returns:
the buffer instanceRemarks:
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.Returns:
Returns the number of bytes written, or EofRemarks:
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.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.Returns:
Returns the maximum capacity of this bufferRemarks:
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.Returns:
Returns the current read-position within this bufferRemarks:
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.Remarks:
Return count of _readable bytes remaining in buffer. This is calculated simply as limit() - position()Remarks:
Reset 'position' and 'limit' to zero. This effectively clears all content from the buffer.Params:
data | the backing array to buffer within |
readable | the number of bytes within data considered valid |
Returns:
the buffer instanceRemarks:
Set the backing array with some content readable. Writing to this will either flush it to an associated conduit, or raise an Eof condition. Use clear() to reset the content (make it all writable).Remarks:
Return count of _writable bytes available in buffer. This is calculated simply as capacity() - limit()Params:
stream | an input stream |
capacity | desired buffer capacity |
Remarks:
Construct a Buffer upon the provided input stream.Params:
stream | an input stream |
capacity | desired buffer capacity |
Remarks:
Construct a Buffer upon the provided input stream.Params:
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 conduitReturns:
a void[] slice of the bufferRemarks:
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.Params:
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.Params:
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.Params:
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, and flush to the conduit as necessary. This is often used in lieu of a Writer.Remarks:
Return count of _writable bytes available in buffer. This is calculated as capacity() - 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.Returns:
Returns the maximum capacity of this bufferRemarks:
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.Remarks:
Truncate the buffer within its extent. Returns true if the new length is valid, false otherwise.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.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 eofReturns:
Returns the number of bytes written, or EofRemarks:
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.Remarks:
Reset 'position' and 'limit' to zero. This effectively clears all content from the buffer.Params:
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.Params:
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 Eof to indicate an error.Remarks:
Return count of _readable bytes remaining in buffer. This is calculated simply as limit() - position()Params:
data | the backing array to buffer within |
readable | the number of bytes within data considered valid |
Returns:
the buffer instanceRemarks:
Set the backing array with some content readable. Writing to this will either flush it to an associated conduit, or raise an Eof condition. Use clear() to reset the content (make it all writable).Returns:
the buffer instanceRemarks:
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.