cbl::Blob Class Reference

A reference to a binary data blob associated with a document. More...

#include <cbl++/Blob.hh>

Inheritance diagram for cbl::Blob:

Public Member Functions
	Blob (std::optional< std::string_view > contentType, slice contents)
	Creates a new blob, given its contents as a single block of data.
	Blob (std::optional< std::string_view > contentType, BlobWriteStream &writer)
	Creates a new blob from the data written to a CBLBlobWriteStream.
	Blob (fleece::Dict d)
	Creates a Blob instance on an existing blob reference in a document or query result.
bool	blobEquals (const Blob &other) const
	Compares whether this blob and another are equal based on their content.
uint64_t	length () const
	Returns the length in bytes of a blob's content (from its length property).
std::string	contentType () const
	Returns a blob's MIME type, if its metadata has a content_type property.
std::string	digest () const
	Returns the cryptographic digest of a blob's content (from its digest property).
fleece::Dict	properties () const
	Returns a blob's metadata.
std::string	createJSON () const
	Returns the JSON representation of the blob's metadata dictionary.
	operator fleece::Dict () const
	Implicit conversion to the blob's underlying Fleece dictionary.
alloc_slice	loadContent ()
	Reads the blob's content into memory and returns it.
BlobReadStream *	openContentStream ()
	Opens a stream for reading a blob's content.
	Blob () noexcept
	Constructs a null reference (one that points to no object).
Blob &	operator= (std::nullptr_t)
	Releases the underlying object and resets this to a null reference.
bool	valid () const
	Returns true if this references an object, or false if it is a null reference.
	operator bool () const
	Returns true if this references an object (same as valid).
bool	operator== (const Blob &other) const
	Returns true if both sides reference the same object, or are both null references.
bool	operator!= (const Blob &other) const
	Returns true if the two sides reference different objects.
CBLBlob *_Nullable	ref () const
	Returns a pointer to the underlying C object (CBLBlob), or NULL if this is a null reference.
	Blob (const Blob &other) noexcept
	Copy constructor: creates another reference to the same object as other.
	Blob (Blob &&other) noexcept
	Move constructor: takes over the reference from other, leaving it a null reference.
Blob &	operator= (const Blob &other) noexcept
	Copy assignment: replaces this reference with a reference to other's object.
Blob &	operator= (Blob &&other) noexcept
	Move assignment: replaces this reference with other's, leaving other a null reference.

Static Public Member Functions
static bool	isBlob (fleece::Dict d)
	Returns true if a dictionary in a document is a blob reference.

Protected Member Functions
	Blob (CBLBlob *_Nullable ref)
	(Internal) Constructs a reference wrapping, and retaining, a C object pointer.

Friends
class	Database

Detailed Description

A reference to a binary data blob associated with a document.

A blob's persistent form is a special dictionary in the document properties. To work with a blob, you construct a Blob object with that dictionary.

Constructor & Destructor Documentation

Blob() [1/7]

cbl::Blob::Blob ( std::optional< std::string_view > contentType, slice contents )

inline

Creates a new blob, given its contents as a single block of data.

Note

The memory pointed to by contents is no longer needed after this call completes (it will have been written to the database.)

Parameters

contentType	The MIME type (optional).
contents	The data's address and length.

Blob() [2/7]

cbl::Blob::Blob ( std::optional< std::string_view > contentType, BlobWriteStream & writer )

inline

Creates a new blob from the data written to a CBLBlobWriteStream.

Parameters

contentType	The MIME type (optional).
writer	The blob-writing stream the data was written to.

Blob() [3/7]

cbl::Blob::Blob ( fleece::Dict d )

inline

Creates a Blob instance on an existing blob reference in a document or query result.

Note

If the dict argument is not actually a blob reference, this Blob object will be invalid; you can check that by calling its valid method or testing it with its operator bool.

Blob() [4/7]

cbl::Blob::Blob ( )

inlinenoexcept

Constructs a null reference (one that points to no object).

Blob() [5/7]

cbl::Blob::Blob ( CBLBlob *_Nullable ref )

inlineexplicitprotected

(Internal) Constructs a reference wrapping, and retaining, a C object pointer.

Blob() [6/7]

cbl::Blob::Blob ( const Blob & other )

inlinenoexcept

Copy constructor: creates another reference to the same object as other.

Blob() [7/7]

cbl::Blob::Blob ( Blob && other )

inlinenoexcept

Move constructor: takes over the reference from other, leaving it a null reference.

Member Function Documentation

blobEquals()

bool cbl::Blob::blobEquals ( const Blob & other ) const

inline

Compares whether this blob and another are equal based on their content.

contentType()

std::string cbl::Blob::contentType ( ) const

inline

Returns a blob's MIME type, if its metadata has a content_type property.

createJSON()

std::string cbl::Blob::createJSON ( ) const

inline

Returns the JSON representation of the blob's metadata dictionary.

digest()

std::string cbl::Blob::digest ( ) const

inline

Returns the cryptographic digest of a blob's content (from its digest property).

isBlob()

bool cbl::Blob::isBlob ( fleece::Dict d )

inlinestatic

Returns true if a dictionary in a document is a blob reference.

Note

This method tests whether the dictionary has a @type property, whose value is "blob".

length()

uint64_t cbl::Blob::length ( ) const

inline

Returns the length in bytes of a blob's content (from its length property).

loadContent()

alloc_slice cbl::Blob::loadContent ( )

inline

Reads the blob's content into memory and returns it.

Note

This loads the whole blob at once. For large blobs, prefer openContentStream to read the content incrementally.

Returns

The blob's content as an alloc_slice that owns the loaded bytes.

Exceptions

cbl::Error

If the content cannot be read (for example, the blob's data is not available in the database).

openContentStream()

BlobReadStream * cbl::Blob::openContentStream ( )

inline

Opens a stream for reading a blob's content.

Note

The caller takes ownership of the returned stream and must delete it (e.g. wrap it in a std::unique_ptr<BlobReadStream>).

Returns

A new BlobReadStream positioned at the start of the blob's content.

operator bool()

cbl::Blob::operator bool ( ) const

inlineexplicit

Returns true if this references an object (same as valid).

operator fleece::Dict()

cbl::Blob::operator fleece::Dict ( ) const

inline

Implicit conversion to the blob's underlying Fleece dictionary.

This lets a Blob be assigned to a mutable Dict/Array item, e.g. dict["foo"] = blob.

operator!=()

bool cbl::Blob::operator!= ( const Blob & other ) const

inline

Returns true if the two sides reference different objects.

operator=() [1/3]

Blob & cbl::Blob::operator= ( Blob && other )

inlinenoexcept

Move assignment: replaces this reference with other's, leaving other a null reference.

operator=() [2/3]

Blob & cbl::Blob::operator= ( const Blob & other )

inlinenoexcept

Copy assignment: replaces this reference with a reference to other's object.

operator=() [3/3]

Blob & cbl::Blob::operator= ( std::nullptr_t )

inline

Releases the underlying object and resets this to a null reference.

operator==()

bool cbl::Blob::operator== ( const Blob & other ) const

inline

Returns true if both sides reference the same object, or are both null references.

properties()

fleece::Dict cbl::Blob::properties ( ) const

inline

Returns a blob's metadata.

This includes the digest, length, content_type, and @type properties, as well as any custom ones that may have been added.

ref()

CBLBlob *_Nullable cbl::Blob::ref ( ) const

inline

Returns a pointer to the underlying C object (CBLBlob), or NULL if this is a null reference.

valid()

bool cbl::Blob::valid ( ) const

inline

Returns true if this references an object, or false if it is a null reference.

Friends And Related Symbol Documentation

Database

friend class Database

friend

---

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

• include/cbl++/Blob.hh