Vault  4.1
Public Types | Public Member Functions | Static Public Attributes | Protected Member Functions | Protected Attributes | Friends
VMemoryStream Class Reference

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:
VStream VReadOnlyMemoryStream VWriteBufferedStream

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.
VMemoryStreamoperator= (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.
Vu8getBuffer () 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.
Vu8mBuffer
 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:
initialBufferSizethe size of the buffer to allocate initially
resizeIncrementthe "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:
bufferthe buffer that the VMemoryStream will work on
allocationTypehow the buffer was allocated, so that VMemoryStream knows the proper way to reallocate it and to delete/free it
adoptsBuffertrue means VMemoryStream takes ownership of the buffer, and can reallocate to expand it, and will delete/free it on destruction
suppliedBufferSizethe size of the supplied buffer
suppliedEOFOffsetthe offset of the end of the "valid" data in the supplied buffer
resizeIncrementthe "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:
otherthe 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:
targetBufferthe buffer to read into
numBytesToReadthe 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:
bufferthe buffer containing the data
numBytesToWritethe 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:
numBytesToSkipthe 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:
offsetthe offset, meaning depends on whence value
whenceSEEK_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:
bufferthe buffer that the VMemoryStream will work on
allocationTypehow the buffer was allocated, so that VMemoryStream knows the proper way to reallocate it and to delete/free it
adoptsBuffertrue means VMemoryStream takes ownership of the buffer, and can reallocate to expand it, and will delete/free it on destruction
suppliedBufferSizethe size of the supplied buffer
suppliedEOFOffsetthe 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:
eofOffsetthe 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:
numBytesToReadthe 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:
numBytesToWritethe 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:
numBytesReadthe 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:
numBytesWrittenthe 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:
m1a memory stream
m2another 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:

Copyright ©1997-2014 Trygve Isaacson. All rights reserved. This documentation was generated with Doxygen.