Magick::Blob

Blob provides the means to contain any opaque data. It is named after the term Binary Large OBject commonly used to describe unstructured data (such as encoded images) which are stored in a database. While the function of Blob is very simple (store a pointer and and size associated with allocated data), the Blob class provides some very useful capabilities. In particular, it is fully reference counted just like the Image class.

The Blob class supports value assignment while preserving any outstanding earlier versions of the object. Since assignment is via a pointer internally, Blob is efficient enough to be stored directly in an STL container or any other data structure which requires assignment. In particular, by storing a Blob in an associative container (such as STL's map) it is possible to create simple indexed in-memory "database" of Blobs.

Magick++ currently uses Blob to contain encoded images (e.g. JPEG) as well as ICC and IPTC profiles. Since Blob is a general-purpose class, it may be used for other purposes as well.

The following is the definition of the Magick::Blob class:

class Blob
{

public:

  enum Allocator
  {
    MallocAllocator,
    NewAllocator
  };

  // Default constructor
  Blob ( void );

  // Construct object with data, making a copy of the supplied data.
  Blob ( const void* data_, size_t length_ );

  // Copy constructor (reference counted)
  Blob ( const Blob& blob_ );

  // Destructor (reference counted)
  virtual       ~Blob ();

  // Assignment operator (reference counted)
  Blob&         operator= ( const Blob& blob_ );

  // Update object contents from Base64-encoded string representation.
  void          base64 ( const std::string base64_ );
  // Return Base64-encoded string representation.
  std::string   base64 ( void );

  // Update object contents, making a copy of the supplied data.
  // Any existing data in the object is deallocated.
  void          update ( const void* data_, size_t length_ );

  // Update object contents, using supplied pointer directly (no
  // copy). Any existing data in the object is deallocated.  The user
  // must ensure that the pointer supplied is not deleted or
  // otherwise modified after it has been supplied to this method.
  // Specify allocator_ as "MallocAllocator" if memory is allocated
  // via the C language malloc() function, or "NewAllocator" if
  // memory is allocated via C++ 'new'.
  void          updateNoCopy ( void* data_, size_t length_,
                               Allocator allocator_ = NewAllocator );

  // Obtain pointer to data. The user should never try to modify or
  // free this data since the Blob class manages its own data. The
  // user must be finished with the data before allowing the Blob to
  // be destroyed since the pointer is invalid once the Blob is
  // destroyed.
  const void*   data ( void ) const;

  // Obtain data length
  size_t length ( void ) const;

};