bdlbb::Blob Class Reference

#include <bdlbb_blob.h>

Detailed Description

Blob is an in-core container for BlobBuffer objects. This class is exception-neutral with no guarantee of rollback: if an exception is thrown during the invocation of a method on a pre-existing instance, the container is left in a valid state, but its value is undefined. In no event is memory leaked.

See bdlbb_blob

Public Member Functions
	Blob (bslma::Allocator *basicAllocator=0)
	Blob (BlobBufferFactory *factory, bslma::Allocator *basicAllocator=0)
	Blob (const BlobBuffer *buffers, int numBuffers, BlobBufferFactory *factory, bslma::Allocator *basicAllocator=0)
	Blob (const Blob &original, BlobBufferFactory *factory, bslma::Allocator *basicAllocator=0)
	Blob (const Blob &original, bslma::Allocator *basicAllocator=0)
	Blob (bslmf::MovableRef< Blob > original) BSLS_KEYWORD_NOEXCEPT
	Blob (bslmf::MovableRef< Blob > original, bslma::Allocator *basicAllocator)
	~Blob ()
Blob &	operator= (const Blob &rhs)
Blob &	operator= (bslmf::MovableRef< Blob > rhs)
void	appendBuffer (const BlobBuffer &buffer)
void	appendBuffer (bslmf::MovableRef< BlobBuffer > buffer)
void	appendDataBuffer (const BlobBuffer &buffer)
void	appendDataBuffer (bslmf::MovableRef< BlobBuffer > buffer)
void	insertBuffer (int index, const BlobBuffer &buffer)
void	insertBuffer (int index, bslmf::MovableRef< BlobBuffer > buffer)
void	prependDataBuffer (const BlobBuffer &buffer)
void	prependDataBuffer (bslmf::MovableRef< BlobBuffer > buffer)
void	removeAll ()
void	removeBuffer (int index)
void	removeBuffers (int index, int numBuffers)
void	removeUnusedBuffers ()
void	replaceDataBuffer (int index, const BlobBuffer &buffer)
void	reserveBufferCapacity (int numBuffers)
void	setLength (int length)
void	swap (Blob &other)
void	swapBufferRaw (int index, BlobBuffer *srcBuffer)
BlobBuffer	trimLastDataBuffer ()
void	moveBuffers (Blob *srcBlob)
void	moveDataBuffers (Blob *srcBlob)
void	moveAndAppendDataBuffers (Blob *srcBlob)
bslma::Allocator *	allocator () const
const BlobBuffer &	buffer (int index) const
BlobBufferFactory *	factory () const
int	lastDataBufferLength () const
int	length () const
int	numDataBuffers () const
int	numBuffers () const
int	totalSize () const

Friends
bool	operator== (const Blob &, const Blob &)
bool	operator!= (const Blob &, const Blob &)

Constructor & Destructor Documentation

Blob() [1/7]

bdlbb::Blob::Blob ( bslma::Allocator *  basicAllocator = 0 )

explicit

Create an empty blob having no factory to allocate blob buffers. Since there is no factory, the behavior is undefined if the length of the blob is set beyond the total size. Optionally specify a basicAllocator used to supply memory. If basicAllocator is 0, the currently installed default allocator is used.

Blob() [2/7]

bdlbb::Blob::Blob ( BlobBufferFactory *  factory, bslma::Allocator *  basicAllocator = 0  )

explicit

Create an empty blob using the specified factory to allocate blob buffers. Optionally specify a basicAllocator used to supply memory. If basicAllocator is 0, the currently installed default allocator is used.

Blob() [3/7]

bdlbb::Blob::Blob	(	const BlobBuffer *	buffers,
		int	numBuffers,
		BlobBufferFactory *	factory,
		bslma::Allocator *	basicAllocator = 0
	)

Create a blob that initially holds the specified numBuffers buffers referenced by the specified buffers, and uses the specified factory to allocate blob buffers. Optionally specify a basicAllocator used to supply memory. If basicAllocator is 0, the currently installed default allocator is used.

Blob() [4/7]

bdlbb::Blob::Blob	(	const Blob &	original,
		BlobBufferFactory *	factory,
		bslma::Allocator *	basicAllocator = 0
	)

Create a blob that holds the same buffers as the specified original blob, and uses the specified factory to allocate blob buffers. Optionally specify a basicAllocator used to supply memory. If basicAllocator is 0, the currently installed default allocator is used.

Blob() [5/7]

bdlbb::Blob::Blob	(	const Blob &	original,
		bslma::Allocator *	basicAllocator = 0
	)

Create a blob that holds the same buffers as the specified original blob, and has no factory to allocate blob buffers. Since there is no factory, the behavior is undefined if the length of the blob is set beyond the total size. Optionally specify a basicAllocator used to supply memory. If basicAllocator is 0, the currently installed default allocator is used.

Blob() [6/7]

bdlbb::Blob::Blob

(

bslmf::MovableRef< Blob >

original

)

Create a blob object having the same value as the specified original object by moving the contents of original to the newly-created object. The allocator associated with original is propagated for use in the newly-created object. original is left in a valid but unspecified state.

Blob() [7/7]

bdlbb::Blob::Blob	(	bslmf::MovableRef< Blob >	original,
		bslma::Allocator *	basicAllocator
	)

Create a blob object having the same value as the specified original object that uses the specified basicAllocator to supply memory. If basicAllocator is 0, the currently installed default allocator is used. The contents of original are moved to the newly-created object. original is left in a valid but unspecified state.

~Blob()

bdlbb::Blob::~Blob

(

)

Destroy this blob.

Member Function Documentation

allocator()

bslma::Allocator * bdlbb::Blob::allocator ( ) const

inline

Return the allocator used by this object to supply memory.

appendBuffer() [1/2]

void bdlbb::Blob::appendBuffer

(

bslmf::MovableRef< BlobBuffer >

buffer

)

Append the specified move-insertable buffer after the last buffer of this blob. The buffer is left in a valid but unspecified state. The length of this blob is unaffected.

Precondition

The behavior is undefined unless neither the total size of the resulting blob nor its total number of buffers exceeds INT_MAX.

Note

Note that this operation is equivalent to insertBuffer(numBuffers(), buffer), but is more efficient.

appendBuffer() [2/2]

void bdlbb::Blob::appendBuffer ( const BlobBuffer &  buffer )

inline

Append the specified buffer after the last buffer of this blob. The length of this blob is unaffected.

Precondition

The behavior is undefined unless neither the total size of the resulting blob nor its total number of buffers exceeds INT_MAX.

Note

Note that this operation is equivalent to insertBuffer(numBuffers(), buffer), but is more efficient.

appendDataBuffer() [1/2]

void bdlbb::Blob::appendDataBuffer

(

bslmf::MovableRef< BlobBuffer >

buffer

)

Append the specified move-insertable buffer after the last data buffer of this blob; the last data buffer is trimmed, if necessary. The buffer is left in a valid but unspecified state. The length of this blob is incremented by the size of buffer.

Precondition

The behavior is undefined unless neither the total size of the resulting blob nor its total number of buffers exceeds INT_MAX.

Note

Note that this operation is equivalent to:

const int n = blob.length();
blob.trimLastDataBuffer();
blob.insertBuffer(numDataBuffers(), MoveUtil::move(buffer));
blob.setLength(n + buffer.size());

but is more efficient.

appendDataBuffer() [2/2]

void bdlbb::Blob::appendDataBuffer ( const BlobBuffer &  buffer )

inline

Append the specified buffer after the last data buffer of this blob; the last data buffer is trimmed, if necessary. The length of this blob is incremented by the size of buffer.

Precondition

The behavior is undefined unless neither the total size of the resulting blob nor its total number of buffers exceeds INT_MAX.

Note

Note that this operation is equivalent to:

const int n = blob.length();
blob.trimLastDataBuffer();
blob.insertBuffer(numDataBuffers(), buffer);
blob.setLength(n + buffer.size());

but is more efficient.

buffer()

const BlobBuffer & bdlbb::Blob::buffer ( int  index ) const

inline

Return a reference to the non-modifiable blob buffer at the specified index in this blob.

Precondition

The behavior is undefined unless 0 <= index < numBuffers().

factory()

BlobBufferFactory * bdlbb::Blob::factory ( ) const

inline

Return the factory used by this object.

insertBuffer() [1/2]

void bdlbb::Blob::insertBuffer	(	int	index,
		bslmf::MovableRef< BlobBuffer >	buffer
	)

Insert the specified move-insertable buffer at the specified index in this blob. Increment the length of this blob by the size of buffer if buffer is inserted before the logical end of this blob. The length of this blob is unchanged if inserting at a position following all data buffers (e.g., inserting into an empty blob or inserting a buffer to increase capacity); in that case, the blob length must be changed by an explicit call to setLength. Buffers at index and higher positions (if any) are shifted up by one index position. The buffer is left in a valid but unspecified state.

Precondition

The behavior is undefined unless 0 <= index <= numBuffers() and neither the total size of the resulting blob nor its total number of buffers exceeds INT_MAX.

insertBuffer() [2/2]

void bdlbb::Blob::insertBuffer ( int  index, const BlobBuffer &  buffer  )

inline

Insert the specified buffer at the specified index in this blob. Increment the length of this blob by the size of buffer if buffer is inserted before the logical end of this blob. The length of this blob is unchanged if inserting at a position following all data buffers (e.g., inserting into an empty blob or inserting a buffer to increase capacity); in that case, the blob length must be changed by an explicit call to setLength. Buffers at index and higher positions (if any) are shifted up by one index position.

Precondition

The behavior is undefined unless 0 <= index <= numBuffers() and neither the total size of the resulting blob nor its total number of buffers exceeds INT_MAX.

lastDataBufferLength()

int bdlbb::Blob::lastDataBufferLength ( ) const

inline

Return the length of the last blob buffer in this blob, or 0 if this blob is of 0 length.

length()

int bdlbb::Blob::length ( ) const

inline

Return the length of this blob.

moveAndAppendDataBuffers()

void bdlbb::Blob::moveAndAppendDataBuffers

(

Blob *

srcBlob

)

Move the data buffers held by the specified srcBlob to this blob appending them to the current data buffers of this blob.

Precondition

The behavior is undefined unless the total size of the resulting blob and the total number of buffers in this blob are less than or equal to INT_MAX.

moveBuffers()

void bdlbb::Blob::moveBuffers

(

Blob *

srcBlob

)

Remove all blob buffers from this blob and move the buffers held by the specified srcBlob to this blob.

Note

Note that this method is logically equivalent to:

*this = *srcBlob;
srcBlob->removeAll();

but its implementation is more efficient.

moveDataBuffers()

void bdlbb::Blob::moveDataBuffers

(

Blob *

srcBlob

)

Remove all blob buffers from this blob and move the data buffers held by the specified srcBlob to this blob.

numBuffers()

int bdlbb::Blob::numBuffers ( ) const

inline

Return the number of blob buffers held by this blob.

numDataBuffers()

int bdlbb::Blob::numDataBuffers ( ) const

inline

Return the number of blob buffers containing data in this blob.

operator=() [1/2]

Blob & bdlbb::Blob::operator=

(

bslmf::MovableRef< Blob >

rhs

)

Assign to this object the value of the specified rhs, and return a reference providing modifiable access to this object. The contents of rhs are move-assigned to this object. rhs is left in a valid but unspecified state.

operator=() [2/2]

Blob & bdlbb::Blob::operator=

(

const Blob &

rhs

)

Assign to this blob the value of the specified rhs blob, and return a reference to this modifiable blob.

prependDataBuffer() [1/2]

void bdlbb::Blob::prependDataBuffer

(

bslmf::MovableRef< BlobBuffer >

buffer

)

Insert the specified move-insertable buffer before the beginning of this blob. The length of this blob is incremented by the length of the prepended buffer. The buffer is left in a valid but unspecified state.

Precondition

The behavior is undefined unless neither the total size of the resulting blob nor its total number of buffers exceeds INT_MAX.

Note

Note that this operation is equivalent to:

const int n = blob.length();
blob.insertBuffer(0, MoveUtil::move(buffer));
blob.setLength(n + buffer.size());

but is more efficient.

prependDataBuffer() [2/2]

void bdlbb::Blob::prependDataBuffer ( const BlobBuffer &  buffer )

inline

Insert the specified buffer before the beginning of this blob. The length of this blob is incremented by the length of the prepended buffer.

Precondition

The behavior is undefined unless neither the total size of the resulting blob nor its total number of buffers exceeds INT_MAX.

Note

Note that this operation is equivalent to:

const int n = blob.length();
blob.insertBuffer(0, buffer);
blob.setLength(n + buffer.size());

but is more efficient.

removeAll()

void bdlbb::Blob::removeAll

(

)

Remove all blob buffers from this blob, and set its length to 0.

removeBuffer()

void bdlbb::Blob::removeBuffer

(

int

index

)

Remove the buffer at the specified index from this blob, and decrement the length of this blob by the size of buffer if the buffer at index contains data bytes (i.e., if the first byte of buffer occurs before the logical end of this blob). Buffers at positions higher than index (if any) are shifted down by one index position.

Precondition

The behavior is undefined unless 0 <= index < numBuffers().

removeBuffers()

void bdlbb::Blob::removeBuffers	(	int	index,
		int	numBuffers
	)

Remove the specified numBuffers starting at the specified index from this blob. Buffers at positions higher than index (if any) are shifted down by numBuffers index positions.

Precondition

The behavior is undefined unless 0 <= index, 0 <= numBuffers, and index + numBuffers <= numBuffers().

removeUnusedBuffers()

void bdlbb::Blob::removeUnusedBuffers

(

)

Remove any unused capacity buffers from this blob.

Note

Note that this method does not trim the last data buffer, and that the resulting totalSize will be length plus any unused capacity in the last buffer having data.

replaceDataBuffer()

void bdlbb::Blob::replaceDataBuffer	(	int	index,
		const BlobBuffer &	buffer
	)

Replace the data buffer at the specified index with the specified buffer.

Precondition

The behavior is undefined unless 0 <= index < numDataBuffers() and the total size of the resulting blob does not exceed INT_MAX.

Note

Note that this operation is equivalent to:

blob.removeBuffer(index);
const int n = blob.length();
blob.insertBuffer(index, buffer);
blob.setLength(n + buffer.size());

but is more efficient.

reserveBufferCapacity()

void bdlbb::Blob::reserveBufferCapacity ( int  numBuffers )

inline

Allocate sufficient capacity to store at least the specified numBuffers buffers.

Precondition

The behavior is undefined unless 0 <= numBuffers.

Note

Note that this method does not change the length of this blob or add any buffers to it. Note also that the internal capacity will be increased to maintain a geometric growth factor.

setLength()

void bdlbb::Blob::setLength

(

int

length

)

Set the length of this blob to the specified length and, if length is greater than its total size, grow this blob by appending buffers allocated using this object's underlying BlobBufferFactory.

Precondition

The behavior is undefined if length is a negative value, or if the new length requires growing the blob and this blob has no underlying factory.

swap()

void bdlbb::Blob::swap

(

Blob &

other

)

Efficiently exchange the value of this object with the value of the specified other object. This method provides the no-throw exception-safety guarantee.

Precondition

The behavior is undefined unless this object was created with the same allocator as other.

swapBufferRaw()

void bdlbb::Blob::swapBufferRaw	(	int	index,
		BlobBuffer *	srcBuffer
	)

Swap the blob buffer at the specified index with the specified srcBuffer.

Precondition

The behavior is undefined unless 0 <= index < numBuffers() and srcBuffer->size() == buffer(index).size().

Note

Note that other than the buffer swap the state of this object remains unchanged.

totalSize()

int bdlbb::Blob::totalSize ( ) const

inline

Return the sum of the sizes of all blob buffers in this blob (i.e., the capacity of this blob).

trimLastDataBuffer()

BlobBuffer bdlbb::Blob::trimLastDataBuffer

(

)

Set the size of the last data buffer to lastDataBufferLength(). If there are no data buffers, or if the last data buffer is full (i.e., its size is lastDataBufferLength()), then this method has no effect. Return the leftover of the trimmed buffer or default constructed BlobBuffer if nothing to trim.

Note

Note that the length of the blob is unchanged, and that capacity buffers (i.e., of indices numDataBuffers() and higher) are not removed.

Friends And Related Symbol Documentation

operator!=

bool operator!= ( const Blob &  , const Blob &    )

friend

Return true if the specified lhs and rhs blobs do not have the same value, and false otherwise. Two blobs do not have the same value if they do not hold the same buffers, or do not have the same length.

operator==

bool operator== ( const Blob &  , const Blob &    )

friend

Return true if the specified lhs and rhs blobs have the same value, and false otherwise. Two blobs have the same value if they hold the same buffers, and have the same length.

---

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

• bdlbb_blob.h