RWDBBlob


RWDBBlob  RWCollectable

Data Type and Member Function Indexes
Synopsis
Description
Public Constructors
Public Member Operator
Public Member Functions

Data Type and Member Function Indexes
(exclusive of constructors and destructors)

Member Functions
acquire() binaryStoreSize() capacity() clear()	compareTo() data() getBytes() hash()	isA() isEqual() length() operator=()	putBytes() release() restoreGuts() saveGuts()

Synopsis

#include <rw/db/blob.h>

RWDBBlob b;          // default; zero capacity and length
RWDBBlob b(2048);
RWDBBlob b((void*)&myGif.data(),myGif.size());

Description

Most database vendors supply one or more datatypes that can store binary data of any length. These datatypes are commonly known as Binary Large Objects, or Blobs. DBTools.h++ stores data of these types as RWDBBlob. Class RWDBBlob provides storage and rudimentary access to the binary data. Applications may want to derive from RWDBBlob to add semantics to the data.

This class is implemented using a technique called copy on write. With this technique, the copy constructor and assignment operators still reference the old object and hence are very fast. An actual copy is made only when a write is performed, that is, if the object is about to be changed. The net result is excellent performance, but with easy-to-understand value semantics.

The member function putBytes() is used to populate an RWDBBlob. This method is safe and robust, but can be inconvenient in cases where large objects have already been loaded into memory. The constructor RWDBBlob(void* data, size_t length) is provided to allow applications to wrap existing data blocks in an RWDBBlob interface. Blobs built with this constructor do not manage the memory addressed by the data pointer; your application continues to be responsible for it.

RWDBBlob inherits from class RWCollectable. The virtual functions of the base class RWCollectable have been redefined.

Public Constructors

RWDBBlob();

The default constructor creates a blob with zero capacity and length.

RWDBBlob(size_t size);

Creates a blob which has an initial capacity to store size bytes of binary data. The length is set to zero.

RWDBBlob(void* data, size_t length);

Creates a blob using the data block provided. The caller retains ownership of the data, and is responsible for providing an accurate length, for ensuring that the data pointer is valid for the lifetime of the blob, and for deallocation of the data, if necessary.

RWDBBlob(const RWDBBlob& blob);

Copy constructor. The created blob shares data with blob until the data is modified.

Public Member Operator

virtual RWDBBlob&
operator=(const RWDBBlob& blob);

Assignment operator. Self shares data with blob until the data is modified. Returns a reference to self.

Public Member Functions

void
acquire() const;

Attempts to acquire the internal mutex lock. If the mutex is already locked by another thread, the function blocks until the mutex is released. This function can be called from a const object. Note: in nonmultithreaded builds, this function evaluates to a no-op.

virtual RWspace
binaryStoreSize()const;

Returns the number of bytes needed to store self.

size_t
capacity()const;

Returns the current capacity of self in bytes. This is the number of bytes self can hold without resizing.

void
clear(size_t size=0);

Replaces this blob's data with a new blob whose length and capacity are zero. The previously held blob is deallocated if needed.

virtual int
compareTo(const RWCollectable* c) const;

Redefined from RWCollectable. Returns 0, if self and c share data; returns 1, if self has length greater than c; returns -1, if c has length greater than self. Otherwise, returns an integer less than, greater than, or equal to zero, depending upon whether self's data is less than, greater than, or equal to c's data, according to the semantics of the standard C library function memcmp().

unsigned char*
data() const;

Provides access to the blob's data as a pointer to the data storage. The data storage is owned by the RWDBBlob and may not be changed or deleted. If the data must be manipulated, the application should derive from RWDBBlob to gain access to the protected data storage and controls.

void
getBytes(void* buffer, size_t size, 
         size_t offset = 0) const;

Copies size bytes starting at self's offset to buffer. The buffer is assumed to be large enough to contain the bytes. Failure to provide a large enough buffer will result in a memory overwrite, which may have unpredictable results.

virtual unsigned
hash()const;

Redefined from RWCollectable. Returns a hash value for use in collection classes.

virtual RWClassID
isA()const;

Redefined from class RWCollectable. Returns __RWDBBLOB.

virtual RWBoolean
isEqual(const RWCollectable* c) const;

Redefined from RWCollectable. Returns TRUE if self and c are byte for byte the same. Actually calls compareTo() to do the comparison.

size_t
length() const;

Returns the current length of self's data in bytes.

void
putBytes(const void* buffer, size_t size, size_t offset = 0
         size_t resize = 256);

Copies size bytes from buffer into self starting at self's offset. Exactly size bytes are copied, and therefore buffer is assumed to contain at least size bytes. Self's capacity is enlarged by multiples of resize bytes if the existing capacity is insufficient.

void
release() const;

Releases a previously acquired mutex. This function can be called from a const object. Note: in nonmultithreaded builds, this function evaluates to a no-op.

virtual void
restoreGuts(RWFile& file) const;

Redefined from RWCollectable. Reads file, replacing the contents of self.

virtual void
restoreGuts(RWvistream& stream) const;

Redefined from RWCollectable. Reads stream, replacing the contents of self.

virtual void
saveGuts(RWFile& file) const;

Redefined from RWCollectable. Writes the contents of self to file.

virtual void
saveGuts(RWvostream& stream) const;

Redefined from RWCollectable. Writes the contents of self to stream.