License:
BSD style: see license.txtVersion:
Mar 2004: Initial release Dec 2006: Outback releaseAuthors:
Kris
1 2 3 4 5 6 7 | // create a small buffer auto buf = new Buffer (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); |
1 2 | auto output = new TextOutput (new Buffer(256)); output.format ("now is the time for {} good men {}", 3, foo); |
1 2 | auto file = new File ("name"); auto buf = new Buffer (file); |
1 | auto input = new DataInput (new File ("name")); |
1 2 3 4 | auto lines = new TextInput (new File ("name")); foreach (line; lines) Cout(line).newline; lines.close; |
Params:
conduit | the conduit to buffer |
Remarks:
Construct a Buffer upon the provided conduit. A relevant buffer size is supplied via the provided conduit.Params:
stream | an input stream |
capacity | desired buffer capacity |
Remarks:
Construct a Buffer upon the provided input stream.Params:
stream | an output stream |
capacity | desired buffer capacity |
Remarks:
Construct a Buffer upon the provided output stream.Params:
capacity | the number of bytes to make available |
Remarks:
Construct a Buffer with the specified number of bytes.Params:
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.Params:
data | the backing array to buffer within |
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.Params:
stream | an input stream |
size | a hint of the desired buffer size. Defaults to the conduit-defined size |
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).Params:
stream | an output stream |
size | a hint of the desired buffer size. Defaults to the conduit-defined size |
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).Params:
data | the backing array to buffer within. All content is considered valid |
Returns:
the buffer instanceRemarks:
Set the backing array with all 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).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:
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:
dst | destination of the content |
bytes | size of dst |
Returns:
A reference to the populated contentRemarks:
Fill the provided array with content. We try to satisfy the request from the buffer content, and read directly from an attached conduit where more is required.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.Params:
other | a buffer with content available |
Returns:
Returns a chaining reference if all content was written. Throws an IOException indicating eof or eob if not.Remarks:
Append another buffer to this one, and flush to the conduit as necessary. This is often used in lieu of a Writer.Params:
raw | The content to consume. This is consumed verbatim, and in raw binary format ~ no implicit conversions are performed. |
Remarks:
This is often used in lieu of a Writer, and enables simple classes, such as FilePath and Uri, to emit content directly into a buffer (thus avoiding potential heap activity)Examples:
1 2 3 | auto path = new FilePath (somepath); path.produce (&buffer.consume); |
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 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 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.Remarks:
Iterators will tend to compress the buffered content in order to maximize space for new data. You can disable this behaviour by setting this boolean to falseRemarks:
Return count of _readable bytes remaining in buffer. This is calculated simply as limit() - position()Remarks:
Return count of _writable bytes available in buffer. This is calculated simply as capacity() - limit()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:
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.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 read, or Conduit.EofRemarks:
Try to _fill the available buffer with content from the specified conduit. We try to read as much as possible by clearing the buffer when all current content has been eaten. If there is no space available, nothing will be read.Returns:
Returns the number of bytes writtenRemarks:
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. Throws an IOException on premature Eof.Remarks:
Truncate the buffer within its extent. Returns true if the new length is valid, false otherwise.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.Params:
conduit | the conduit to attach to |
Remarks:
Sets the external conduit associated with this buffer. Buffers do not require an external conduit to operate, but it can be convenient to associate one. For example, methods fill() & drain() use it to import/export content as necessary.Params:
boutput | the stream to attach to |
Remarks:
Sets the external output stream associated with this buffer. Buffers do not require an external stream to operate, but it can be convenient to associate one. For example, methods fill & drain use them to import/export content as necessary.Params:
binput | the stream to attach to |
Remarks:
Sets the external input stream associated with this buffer. Buffers do not require an external stream to operate, but it can be convenient to associate one. For example, methods fill & drain use them to import/export content as necessary.Remarks:
Return the entire backing array. Exposed for subclass usage onlyParams:
src | the soure of the content |
size | the length of content at src |
Remarks:
Bulk _copy of data from 'src'. The new content is made available for reading. This is exposed for subclass use onlyReturns:
Available space, without any expansionRemarks:
Make some additional room in the buffer, of at least the given size. This can be used by subclasses as appropriateParams:
msg | a text message describing the exception reason |
Remarks:
Throw an IOException with the provided messageRemarks:
Flush the contents of this buffer. This will block until all content is actually flushed via the associated conduit, whereas drain() will not. Do nothing where a conduit is not attached, enabling memory buffers to treat flush as a noop. Throws an IOException on premature Eof.Remarks:
Reset 'position' and 'limit' to zero. This effectively clears all content from the buffer.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 eofParams:
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:
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.Returns:
Returns the conduit associated with this buffer. Returns null if the buffer is purely memory based; that is, it's not backed by some external medium.Remarks:
Buffers do not require an external conduit to operate, but it can be convenient to associate one. For example, methods fill() & drain() use it to import/export content as necessary.Returns:
Returns the OutputStream associated with this buffer. Returns null if the buffer is not attached to an output; that is, it's not backed by some external medium.Remarks:
Buffers do not require an external stream to operate, but it can be convenient to associate them. For example, methods fill & drain use them to import/export content as necessary.Returns:
Returns the InputStream associated with this buffer. Returns null if the buffer is not attached to an input; that is, it's not backed by some external medium.Remarks:
Buffers do not require an external stream to operate, but it can be convenient to associate them. For example, methods fill & drain use them to import/export content as necessary.Remarks:
Propagate request to an attached OutputStream (this is a requirement for the OutputStream interface)Returns:
Available space after adjustmentRemarks:
Make some additional room in the buffer, of at least the given size. This can be used by subclasses as appropriate