VMemoryStream is a concrete subclass of VStream, that provides stream i/o to a buffer in memory; during writes the buffer will expand automatically as necessary. More...

#include <vmemorystream.h>

Inheritance diagram for VMemoryStream:

List of all members.

Public Types
enum	BufferAllocationType { kAllocatedByOperatorNew, kAllocatedByMalloc, kAllocatedOnStack, kAllocatedUnknown }
Public Member Functions
	VMemoryStream (Vs64 initialBufferSize=kDefaultBufferSize, Vs64 resizeIncrement=kIncrement2x)
	Constructs the object with a specified buffer size and resizing increment.
	VMemoryStream (const VMemoryStream &other)
	VMemoryStream (Vu8 *buffer, BufferAllocationType allocationType, bool adoptsBuffer, Vs64 suppliedBufferSize, Vs64 suppliedEOFOffset, Vs64 resizeIncrement=kIncrement2x)
	Constructs the object with an existing buffer.
virtual	~VMemoryStream ()
	Destructor.
VMemoryStream &	operator= (const VMemoryStream &other)
	Same semantics as with the copy constructor described above; if the other stream owns its buffer, we make a copy that we own; if it's sharing a buffer owned by someone else, then we will also share it.
virtual Vs64	read (Vu8 *targetBuffer, Vs64 numBytesToRead)
	Attempts to read a specified number of bytes from the stream.
virtual Vs64	write (const Vu8 *buffer, Vs64 numBytesToWrite)
	Writes bytes to the stream.
virtual void	flush ()
	Flushes any pending or buffered write data to the stream.
virtual bool	skip (Vs64 numBytesToSkip)
	Skips forward in the stream a specified number of bytes.
virtual bool	seek (Vs64 offset, int whence)
	Seeks in the stream using Unix seek() semantics.
virtual Vs64	getIOOffset () const
	Returns the current offset in the stream.
virtual Vs64	available () const
	Returns the number of bytes that are available to be read from this stream.
void	adoptBuffer (Vu8 *buffer, BufferAllocationType allocationType, bool adoptsBuffer, Vs64 suppliedBufferSize, Vs64 suppliedEOFOffset)
	Makes the object use a specified buffer instead of the one it is currently using.
void	orphanBuffer ()
	Notifies the VMemoryStream that it no longer owns the buffer; it will continue to use the buffer, but may not reallocate nor delete/free it.
Vu8 *	getBuffer () const
	Returns the memory buffer pointer.
Vs64	getBufferSize () const
	Returns the size of the memory buffer.
Vs64	getEOFOffset () const
	Returns the EOF offset, that is, the length of "valid" data in the buffer.
void	setEOF (Vs64 eofOffset)
	Sets the EOF offset, constrained to the buffer size.
Static Public Attributes
static const Vs64	kIncrement2x = 0
	Special constant for resize increment, causes buffer to double when expanded.
static const Vs64	kDefaultBufferSize = 32768
	The default size of the buffer allocated on construction.
Protected Member Functions
virtual Vu8 *	_getReadIOPtr () const
	Returns a pointer to the current read i/o position in the stream's buffer, or NULL if the stream does not have a buffer or support direct copying from that buffer (for example, a file or socket stream).
virtual Vu8 *	_getWriteIOPtr () const
	Returns a pointer to the current write i/o position in the stream's buffer, or NULL if the stream does not have a buffer or support direct copying to that buffer (for example, a file or socket stream).
virtual Vs64	_prepareToRead (Vs64 numBytesToRead) const
	Returns the number of bytes available for reading from the stream's buffer, or zero by default for streams without buffers.
virtual void	_prepareToWrite (Vs64 numBytesToWrite)
	Preflights the stream's buffer so that it can have the specified number of bytes written to it subsequently.
virtual void	_finishRead (Vs64 numBytesRead)
	Postflights a copy by advancing the i/o offset to reflect the specified number of bytes having just been read.
virtual void	_finishWrite (Vs64 numBytesWritten)
	Postflights a copy by advancing the i/o offset to reflect the specified number of bytes having just been written.
void	_assertInvariant () const
	Asserts if any invariant is broken.
Protected Attributes
Vs64	mBufferSize
	The physical size of the buffer.
Vs64	mIOOffset
	The offset in the buffer of the next read/write.
Vs64	mEOFOffset
	The offset in the buffer of the end of the data.
Vs64	mResizeIncrement
	The amount to increment when expanding the buffer.
bool	mOwnsBuffer
	True means we delete the buffer on destruction; false means it's someone else's responsibility.
BufferAllocationType	mAllocationType
	Indicates how the buffer was allocated, and thus how it should be deallocated.
Vu8 *	mBuffer
	The buffer itself.
Friends
bool	operator== (const VMemoryStream &m1, const VMemoryStream &m2)
	Returns true if the two memory streams contain exactly the same number of bytes (that is, they have the same EOF offsets) and those bytes contain identical values.

Detailed Description

VMemoryStream is a concrete subclass of VStream, that provides stream i/o to a buffer in memory; during writes the buffer will expand automatically as necessary.

Normally VMemoryStream allocates its own buffer; however, you may supply it with a buffer you have already allocated, though if VMemoryStream needs to expand the buffer to accomodate a write, it will delete your buffer and allocate a new one.

You specify a resize increment by which the buffer will be expanded when it needs expansion. There is a special constant, VMemoryStream::kIncrement2x, which makes the buffer expand by doubling in size each time. This is often the most efficient way to deal with streams whose size is not known in advance, because it allows the buffer to grow in a way that slows down the number of re-allocations as more expansion is needed. kIncrement2x is the default value of the resize increment.

VMemoryStream normally allocates its own buffer using new[] rather than the old C style malloc() function. However, when the caller supplies the buffer via adoptBuffer() or the constructor that takes a buffer, it indicates how the buffer was allocated, and VMemoryStream then knows how whether to delete[] or free() it, and should VMemoryStream need to reallocate it, it will continue with the same kind of allocation (unless you allow VMemoryStream to adopt a stack-based buffer, in which case it will reallocate on the heap with new if it needs to expand; normally you would use a stack-base buffer only in a read-only or other non-expandable situation). You also indicate in these methods whether VMemoryStream is adopting (taking ownership of) the buffer; if it is not adopting the buffer, it cannot reallocate it, and so any write operation that needs to expand the buffer will cause a VEOFException to be thrown. You can tell VMemoryStream to relinquish ownership of the buffer by calling orphanBuffer(); this means VMemoryStream will neither reallocate nor delete/free the buffer.

Definition at line 52 of file vmemorystream.h.

Constructor & Destructor Documentation

VMemoryStream::VMemoryStream	(	Vs64	initialBufferSize = `kDefaultBufferSize`,
		Vs64	resizeIncrement = `kIncrement2x`
	)

Constructs the object with a specified buffer size and resizing increment.

Parameters:

initialBufferSize	the size of the buffer to allocate initially
resizeIncrement	the "chunk size" in which the buffer will expand when needed

Definition at line 27 of file vmemorystream.cpp.

References ASSERT_INVARIANT, mAllocationType, mBuffer, and mBufferSize.

VMemoryStream::VMemoryStream	(	Vu8 *	buffer,
		BufferAllocationType	allocationType,
		bool	adoptsBuffer,
		Vs64	suppliedBufferSize,
		Vs64	suppliedEOFOffset,
		Vs64	resizeIncrement = `kIncrement2x`
	)

Constructs the object with an existing buffer.

Parameters:

buffer	the buffer that the VMemoryStream will work on
allocationType	how the buffer was allocated, so that VMemoryStream knows the proper way to reallocate it and to delete/free it
adoptsBuffer	true means VMemoryStream takes ownership of the buffer, and can reallocate to expand it, and will delete/free it on destruction
suppliedBufferSize	the size of the supplied buffer
suppliedEOFOffset	the offset of the end of the "valid" data in the supplied buffer
resizeIncrement	the "chunk size" in which the buffer will expand when needed

Definition at line 82 of file vmemorystream.cpp.

References ASSERT_INVARIANT.

Member Function Documentation

VMemoryStream & VMemoryStream::operator= ( const VMemoryStream & other )

Same semantics as with the copy constructor described above; if the other stream owns its buffer, we make a copy that we own; if it's sharing a buffer owned by someone else, then we will also share it.

Parameters:

other the other VMemoryStream that we are assigned from

Definition at line 99 of file vmemorystream.cpp.

References ASSERT_INVARIANT, VStream::copyMemory(), mAllocationType, mBuffer, mBufferSize, mEOFOffset, mIOOffset, VStream::mName, mOwnsBuffer, and mResizeIncrement.

Vs64 VMemoryStream::read	(	Vu8 *	targetBuffer,
		Vs64	numBytesToRead
	)		`[virtual]`

Attempts to read a specified number of bytes from the stream.

Parameters:

targetBuffer	the buffer to read into
numBytesToRead	the number of bytes to read

Returns:: the actual number of bytes that could be read

Implements VStream.

Reimplemented in VWriteBufferedStream.

Definition at line 130 of file vmemorystream.cpp.

References _finishRead(), ASSERT_INVARIANT, VStream::copyMemory(), mBuffer, mEOFOffset, mIOOffset, and V_MIN.

Vs64 VMemoryStream::write	(	const Vu8 *	buffer,
		Vs64	numBytesToWrite
	)		`[virtual]`

Writes bytes to the stream.

Throws a VException if the write extends past the end of the buffer but buffer expansion fails.

Parameters:

buffer	the buffer containing the data
numBytesToWrite	the number of bytes to write to the stream

Returns:: the actual number of bytes written

Implements VStream.

Reimplemented in VReadOnlyMemoryStream.

Definition at line 145 of file vmemorystream.cpp.

References _finishWrite(), _prepareToWrite(), ASSERT_INVARIANT, VStream::copyMemory(), mBuffer, and mIOOffset.

void VMemoryStream::flush ( ) [virtual]

Flushes any pending or buffered write data to the stream.

Until you call flush, you cannot guarantee that your data has actually been written to the underlying physical stream.

Implements VStream.

Reimplemented in VReadOnlyMemoryStream, and VWriteBufferedStream.

Definition at line 159 of file vmemorystream.cpp.

bool VMemoryStream::skip ( Vs64 numBytesToSkip ) [virtual]

Skips forward in the stream a specified number of bytes.

Parameters:

numBytesToSkip the number of bytes to skip

Implements VStream.

Reimplemented in VWriteBufferedStream.

Definition at line 163 of file vmemorystream.cpp.

References ASSERT_INVARIANT, mEOFOffset, mIOOffset, and V_MIN.

bool VMemoryStream::seek	(	Vs64	offset,
		int	whence
	)		`[virtual]`

Seeks in the stream using Unix seek() semantics.

Parameters:

offset	the offset, meaning depends on whence value
whence	SEEK_SET, SEEK_CUR, or SEEK_END

Returns:: true if the seek was successful

Implements VStream.

Definition at line 176 of file vmemorystream.cpp.

References _finishWrite(), _prepareToWrite(), ASSERT_INVARIANT, CONST_S64, mBuffer, mEOFOffset, and mIOOffset.

Vs64 VMemoryStream::getIOOffset ( ) const [virtual]

Returns the current offset in the stream.

For memory streams, this is the same as the i/o offset.

Returns:: the current offset

Implements VStream.

Definition at line 229 of file vmemorystream.cpp.

References ASSERT_INVARIANT, and mIOOffset.

Vs64 VMemoryStream::available ( ) const [virtual]

Returns the number of bytes that are available to be read from this stream.

For file and memory streams, this means the number of bytes from the current i/o mark until the end of the file or buffer. For socket streams, this means the number of bytes that can be read without blocking (that is, the number of bytes that are waiting to be read on the socket at this time).

Returns:: the number of bytes currently available for reading

Implements VStream.

Definition at line 235 of file vmemorystream.cpp.

References mEOFOffset, and mIOOffset.

void VMemoryStream::adoptBuffer	(	Vu8 *	buffer,
		BufferAllocationType	allocationType,
		bool	adoptsBuffer,
		Vs64	suppliedBufferSize,
		Vs64	suppliedEOFOffset
	)

Makes the object use a specified buffer instead of the one it is currently using.

The existing buffer will be deleted/freed if the existing buffer is owned by the VMemoryStream.

Parameters:

buffer	the buffer that the VMemoryStream will work on
allocationType	how the buffer was allocated, so that VMemoryStream knows the proper way to reallocate it and to delete/free it
adoptsBuffer	true means VMemoryStream takes ownership of the buffer, and can reallocate to expand it, and will delete/free it on destruction
suppliedBufferSize	the size of the supplied buffer
suppliedEOFOffset	the offset of the end of the "valid" data in the supplied buffer

Definition at line 346 of file vmemorystream.cpp.

References ASSERT_INVARIANT, mAllocationType, mBuffer, mBufferSize, mEOFOffset, mIOOffset, and mOwnsBuffer.

Vu8 * VMemoryStream::getBuffer ( ) const

Returns the memory buffer pointer.

Returns:: the memory buffer pointer

Definition at line 362 of file vmemorystream.cpp.

References ASSERT_INVARIANT, and mBuffer.

Vs64 VMemoryStream::getBufferSize ( ) const

Returns the size of the memory buffer.

Returns:: the size of the memory buffer

Definition at line 374 of file vmemorystream.cpp.

References ASSERT_INVARIANT, and mBufferSize.

Vs64 VMemoryStream::getEOFOffset ( ) const

Returns the EOF offset, that is, the length of "valid" data in the buffer.

Returns:: the EOF offset

Definition at line 380 of file vmemorystream.cpp.

References ASSERT_INVARIANT, and mEOFOffset.

void VMemoryStream::setEOF ( Vs64 eofOffset )

Sets the EOF offset, constrained to the buffer size.

That is, if you attempt to set EOF past the end of the buffer, the EOF will be set to the end of the buffer.

Parameters:

eofOffset the new EOF offset

Definition at line 386 of file vmemorystream.cpp.

References ASSERT_INVARIANT, mBufferSize, mEOFOffset, mIOOffset, and V_MIN.

Vu8 * VMemoryStream::_getReadIOPtr ( ) const [protected, virtual]

Returns a pointer to the current read i/o position in the stream's buffer, or NULL if the stream does not have a buffer or support direct copying from that buffer (for example, a file or socket stream).

Returns:: the i/o buffer pointer, or NULL

Reimplemented from VStream.

Definition at line 239 of file vmemorystream.cpp.

References ASSERT_INVARIANT, mBuffer, and mIOOffset.

Vu8 * VMemoryStream::_getWriteIOPtr ( ) const [protected, virtual]

Returns a pointer to the current write i/o position in the stream's buffer, or NULL if the stream does not have a buffer or support direct copying to that buffer (for example, a file or socket stream).

Returns:: the i/o buffer pointer, or NULL

Reimplemented from VStream.

Definition at line 250 of file vmemorystream.cpp.

References ASSERT_INVARIANT, mBuffer, and mIOOffset.

Vs64 VMemoryStream::_prepareToRead ( Vs64 numBytesToRead ) const [protected, virtual]

Returns the number of bytes available for reading from the stream's buffer, or zero by default for streams without buffers.

Parameters:

numBytesToRead the number of bytes that will be read

Returns:: the number of bytes available to read, or zero

Reimplemented from VStream.

Definition at line 261 of file vmemorystream.cpp.

References ASSERT_INVARIANT, mEOFOffset, mIOOffset, and V_MIN.

void VMemoryStream::_prepareToWrite ( Vs64 numBytesToWrite ) [protected, virtual]

Preflights the stream's buffer so that it can have the specified number of bytes written to it subsequently.

Throws a VException if the buffer cannot be expanded to accomodate the data.

Parameters:

numBytesToWrite the number of bytes that will be written

Reimplemented from VStream.

Definition at line 270 of file vmemorystream.cpp.

References ASSERT_INVARIANT, VStream::copyMemory(), kIncrement2x, mAllocationType, mBuffer, mBufferSize, mEOFOffset, mIOOffset, mOwnsBuffer, and mResizeIncrement.

void VMemoryStream::_finishRead ( Vs64 numBytesRead ) [protected, virtual]

Postflights a copy by advancing the i/o offset to reflect the specified number of bytes having just been read.

Parameters:

numBytesRead the number of bytes that were previously read

Reimplemented from VStream.

Definition at line 325 of file vmemorystream.cpp.

References ASSERT_INVARIANT, and mIOOffset.

void VMemoryStream::_finishWrite ( Vs64 numBytesWritten ) [protected, virtual]

Postflights a copy by advancing the i/o offset to reflect the specified number of bytes having just been written.

Parameters:

numBytesWritten the number of bytes that were previously written

Reimplemented from VStream.

Definition at line 333 of file vmemorystream.cpp.

References ASSERT_INVARIANT, mEOFOffset, and mIOOffset.

void VMemoryStream::_assertInvariant ( ) const [protected]

Asserts if any invariant is broken.

Definition at line 443 of file vmemorystream.cpp.

References mAllocationType, mBuffer, mBufferSize, mEOFOffset, mIOOffset, and VSTRING_INT.

Friends And Related Function Documentation

bool operator==	(	const VMemoryStream &	m1,
		const VMemoryStream &	m2
	)		`[friend]`

Returns true if the two memory streams contain exactly the same number of bytes (that is, they have the same EOF offsets) and those bytes contain identical values.

Parameters:

m1	a memory stream
m2	another memory stream

Returns:: true if the streams's lengths and data are the same

Definition at line 452 of file vmemorystream.cpp.

The documentation for this class was generated from the following files:

Public Types

Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation