Buffered stream

BufStream implements two one-way buffered streams: the streams store all data from (or for) the source stream in a memory buffer, and only flush the buffer when it's full (or refill it when it's empty). The buffer size can be specified at creation time. 2 streams are implemented: which is for reading only, and which is for writing only.

Buffered streams can help in speeding up read or write operations, especially when a lot of small read/write operations are done: it avoids doing a lot of operating system calls.

Stream definitions Exception support Default buffer size If no buffer size is specified when the stream is created, then this size is used. Common ancestor for buffered streams TBufStream is the common ancestor for the and streams. It completely handles the buffer memory management and position management. An instance of TBufStream should never be created directly. It also keeps the instance of the source stream. Create a new TBufStream instance.

Create creates a new TBufStream instance. A buffer of size ACapacity is allocated, and the ASource source (or destination) stream is stored. If no capacity is specified, then is used as the capacity.

An instance of TBufStream should never be instantiated directly. Instead, an instance of or should be created.

If not enough memory is available for the buffer, then an exception may be raised. Destroys the TBufStream instance Destroy destroys the instance of TBufStream. It flushes the buffer, deallocates it, and then destroys the TBufStream instance. The current buffer Buffer is a pointer to the actual buffer in use. Current buffer capacity Capacity is the amount of memory the buffer occupies. To change the buffer size, the capacity can be set. Note that the capacity cannot be set to a value that is less than the current buffer size, i.e. the current amount of data in the buffer. Current buffer position. BufPos is the current stream position in the buffer. Depending on whether the stream is used for reading or writing, data will be read from this position, or will be written at this position in the buffer. Amount of data in the buffer BufferSize is the actual amount of data in the buffer. This is always less than or equal to the Capacity. Read-only buffered stream.

TReadBufStream is a read-only buffered stream. It implements the needed methods to read data from the buffer and fill the buffer with additional data when needed.

The stream provides limited forward-seek possibilities.

Set location in the buffer

Seek sets the location in the buffer. Currently, only a forward seek is allowed. It is emulated by reading and discarding data. For an explanation of the parameters, see TStream.Seek"

The seek method needs enhancement to enable it to do a full-featured seek. This may be implemented in a future release of Free Pascal.

In case an illegal seek operation is attempted, an exception is raised. Reads data from the stream

Read reads at most ACount bytes from the stream and places them in Buffer. The number of actually read bytes is returned.

TReadBufStream first reads whatever data is still available in the buffer, and then refills the buffer, after which it continues to read data from the buffer. This is repeated untill ACount bytes are read, or no more data is available.

Writes data to the stream Write always raises an EStreamError exception, because the stream is read-only. A write stream must be used to write data in a buffered way. Write-only buffered stream.

TWriteBufStream is a write-only buffered stream. It implements the needed methods to write data to the buffer and flush the buffer (i.e., write its contents to the source stream) when needed.

Remove the TWriteBufStream instance from memory Destroy flushes the buffer and then calls the inherited Destroy. If an error occurs during flushing of the buffer, an exception may be raised. Create Set stream position.

Seek always raises an EStreamError exception, except when the seek operation would not alter the current position.

A later implementation may perform a proper seek operation by flushing the buffer and doing a seek on the source stream.

Read data from the stream Read always raises an EStreamError exception since TWriteBufStream is write-only. To read data in a buffered way, should be used. Write data to the stream Write writes at most ACount bytes from ABuffer to the stream. The data is written to the internal buffer first. As soon as the internal buffer is full, it is flushed to the destination stream, and the internal buffer is filled again. This process continues till all data is written (or an error occurs). An exception may occur if the destination stream has problems writing. Source stream to buffer data from Buffer capacity New position Offset (in bytes) of origin Origin of seek operation Number of bytes read Buffer to place read data in Number of bytes to read Number of bytes actually read Buffer containing data to write to stream Number of bytes to write to stream New position Offset (in bytes) of origin Origin of seek operation Number of bytes read Buffer to place read bytes in Number of bytes to read Number of bytes written Buffer containing data to write Number of bytes to write to stream