Documents

A CBLDocument is essentially a JSON object with an ID string that's unique in its database. More...

Typedefs
typedef struct CBLDocument	CBLDocument
	An in-memory copy of a document.

Variables
CBL_PUBLIC const FLSlice	kCBLTypeProperty
	"@type"

Document lifecycle
enum	CBLConcurrencyControl : uint8_t { kCBLConcurrencyControlLastWriteWins , kCBLConcurrencyControlFailOnConflict }
typedef bool(*	CBLConflictHandler) (void *_cbl_nullable context, CBLDocument *_cbl_nullable documentBeingSaved, const CBLDocument *_cbl_nullable conflictingDocument)
	Custom conflict handler for use when saving or deleting a document.
CBLINLINE const CBLDocument *	CBLDocument_Retain (const CBLDocument *_cbl_nullable t)
CBLINLINE void	CBLDocument_Release (const CBLDocument *_cbl_nullable t)

Mutable documents
The type CBLDocument* without a const qualifier refers to a mutable document instance. A mutable document exposes its properties as a mutable dictionary, so you can change them in place and then call CBLDatabase_SaveDocument to persist the changes.
_cbl_warn_unused CBLDocument *	CBLDocument_Create (void)
	Creates a new, empty document in memory, with a randomly-generated unique ID.
_cbl_warn_unused CBLDocument *	CBLDocument_CreateWithID (FLString docID)
	Creates a new, empty document in memory, with the given ID.
_cbl_warn_unused CBLDocument *	CBLDocument_MutableCopy (const CBLDocument *original)
	Creates a new mutable CBLDocument instance that refers to the same document as the original.

Document properties and metadata
A document's body is essentially a JSON object. The properties are accessed in memory using the Fleece API, with the body itself being a dictionary).
FLString	CBLDocument_ID (const CBLDocument *)
	Returns a document's ID.
FLString	CBLDocument_RevisionID (const CBLDocument *)
	Returns a document's revision ID, which is a short opaque string that's guaranteed to be unique to every change made to the document.
uint64_t	CBLDocument_Timestamp (const CBLDocument *)
	The hybrid logical timestamp in nanoseconds since epoch that the revision was created.
uint64_t	CBLDocument_Sequence (const CBLDocument *)
	Returns a document's current sequence in the local database.
CBLCollection *_cbl_nullable	CBLDocument_Collection (const CBLDocument *)
	Returns a document's collection or NULL for the new document that hasn't been saved.
FLDict	CBLDocument_Properties (const CBLDocument *)
	Returns a document's properties as a dictionary.
FLMutableDict	CBLDocument_MutableProperties (CBLDocument *)
	Returns a mutable document's properties as a mutable dictionary.
void	CBLDocument_SetProperties (CBLDocument *, FLMutableDict properties)
	Sets a mutable document's properties.
_cbl_warn_unused FLSliceResult	CBLDocument_CreateJSON (const CBLDocument *)
	Returns a document's properties as JSON.
bool	CBLDocument_SetJSON (CBLDocument *, FLSlice json, CBLError *_cbl_nullable outError)
	Sets a mutable document's properties from a JSON string.

Detailed Description

A CBLDocument is essentially a JSON object with an ID string that's unique in its database.

Typedef Documentation

CBLConflictHandler

typedef bool(* CBLConflictHandler) (void *_cbl_nullable context, CBLDocument *_cbl_nullable documentBeingSaved, const CBLDocument *_cbl_nullable conflictingDocument)

Custom conflict handler for use when saving or deleting a document.

This handler is called if the save would cause a conflict, i.e. if the document in the database has been updated (probably by a pull replicator, or by application code on another thread) since it was loaded into the CBLDocument being saved.

Parameters

context	The value of the context parameter you passed to CBLCollection_SaveDocumentWithConflictHandler.
documentBeingSaved	The document being saved (same as the parameter you passed to CBLCollection_SaveDocumentWithConflictHandler.) The callback may modify this document's properties as necessary to resolve the conflict.
conflictingDocument	The revision of the document currently in the database, which has been changed since documentBeingSaved was loaded. May be NULL, meaning that the document has been deleted.

Returns

True to save the document, false to abort the save.

CBLDocument

typedef struct CBLDocument CBLDocument

An in-memory copy of a document.

CBLDocument objects can be mutable or immutable. Immutable objects are referenced by const pointers; mutable ones by non-const pointers. This prevents you from accidentally calling a mutable-document function on an immutable document.

Enumeration Type Documentation

CBLConcurrencyControl

enum CBLConcurrencyControl : uint8_t

Enumerator
kCBLConcurrencyControlLastWriteWins	The current save/delete will overwrite a conflicting revision if there is a conflict.
kCBLConcurrencyControlFailOnConflict	The current save/delete will fail if there is a conflict.

Function Documentation

CBLDocument_Collection()

CBLCollection *_cbl_nullable CBLDocument_Collection

(

const CBLDocument *

)

Returns a document's collection or NULL for the new document that hasn't been saved.

CBLDocument_Create()

_cbl_warn_unused CBLDocument * CBLDocument_Create

(

void

)

Creates a new, empty document in memory, with a randomly-generated unique ID.

It will not be added to a database until saved.

Returns

The new mutable document instance.

CBLDocument_CreateJSON()

_cbl_warn_unused FLSliceResult CBLDocument_CreateJSON

(

const CBLDocument *

)

Returns a document's properties as JSON.

Note

You are responsible for releasing the result by calling FLSliceResult_Release.

CBLDocument_CreateWithID()

_cbl_warn_unused CBLDocument * CBLDocument_CreateWithID

(

FLString

docID

)

Creates a new, empty document in memory, with the given ID.

It will not be added to a database until saved.

Note

If the given ID conflicts with a document already in the database, that will not be apparent until this document is saved. At that time, the result depends on the conflict handling mode used when saving; see the save functions for details.

Parameters

docID

The ID of the new document, or NULL to assign a new unique ID.

Returns

The new mutable document instance.

CBLDocument_ID()

FLString CBLDocument_ID

(

const CBLDocument *

)

Returns a document's ID.

CBLDocument_MutableCopy()

_cbl_warn_unused CBLDocument * CBLDocument_MutableCopy

(

const CBLDocument *

original

)

Creates a new mutable CBLDocument instance that refers to the same document as the original.

If the original document has unsaved changes, the new one will also start out with the same changes; but mutating one document thereafter will not affect the other.

Note

You must release the new reference when you're done with it. Similarly, the original document still exists and must also be released when you're done with it.

CBLDocument_MutableProperties()

FLMutableDict CBLDocument_MutableProperties

(

CBLDocument *

)

Returns a mutable document's properties as a mutable dictionary.

You may modify this dictionary and then call CBLDatabase_SaveDocument to persist the changes.

Note

The dictionary object is owned by the document; you do not need to release it.

Every call to this function returns the same mutable collection. This is the same collection returned by CBLDocument_Properties.

When accessing nested collections inside the properties as a mutable collection for modification, use FLMutableDict_GetMutableDict or FLMutableDict_GetMutableArray.

Warning

When the document is released, this reference to the properties becomes invalid. If you need to use any properties after releasing the document, you must retain them by calling FLValue_Retain (and of course later release them.)

CBLDocument_Properties()

FLDict CBLDocument_Properties

(

const CBLDocument *

)

Returns a document's properties as a dictionary.

Note

The dictionary object is owned by the document; you do not need to release it.

Warning

When the document is released, this reference to the properties becomes invalid. If you need to use any properties after releasing the document, you must retain them by calling FLValue_Retain (and of course later release them.)

This dictionary reference is immutable, but if the document is mutable the underlying dictionary itself is mutable and could be modified through a mutable reference obtained via CBLDocument_MutableProperties. If you need to preserve the properties, call FLDict_MutableCopy to make a deep copy.

CBLDocument_Release()

CBLINLINE void CBLDocument_Release

(

const CBLDocument *_cbl_nullable

t

)

CBLDocument_Retain()

CBLINLINE const CBLDocument * CBLDocument_Retain

(

const CBLDocument *_cbl_nullable

t

)

CBLDocument_RevisionID()

FLString CBLDocument_RevisionID

(

const CBLDocument *

)

Returns a document's revision ID, which is a short opaque string that's guaranteed to be unique to every change made to the document.

If the document doesn't exist yet, this function returns NULL.

CBLDocument_Sequence()

uint64_t CBLDocument_Sequence

(

const CBLDocument *

)

Returns a document's current sequence in the local database.

This number increases every time the document is saved, and a more recently saved document will have a greater sequence number than one saved earlier, so sequences may be used as an abstract 'clock' to tell relative modification times.

CBLDocument_SetJSON()

bool CBLDocument_SetJSON	(	CBLDocument *	,
		FLSlice	json,
		CBLError *_cbl_nullable	outError )

Sets a mutable document's properties from a JSON string.

CBLDocument_SetProperties()

void CBLDocument_SetProperties	(	CBLDocument *	,
		FLMutableDict	properties )

Sets a mutable document's properties.

Call CBLDatabase_SaveDocument to persist the changes.

Note

The dictionary object will be retained by the document. You are responsible for releasing any retained reference(s) you have to it.

CBLDocument_Timestamp()

uint64_t CBLDocument_Timestamp

(

const CBLDocument *

)

The hybrid logical timestamp in nanoseconds since epoch that the revision was created.

Variable Documentation

kCBLTypeProperty

CBL_PUBLIC const FLSlice kCBLTypeProperty

extern

"@type"