Couchbase Lite C
Couchbase Lite C API
Reading Fleece Data

FLDoc

An FLDoc points to (and often owns) Fleece-encoded data and provides access to its Fleece values.

NODISCARD FLEECE_PUBLIC FLDoc FLDoc_FromResultData (FLSliceResult data, FLTrust, FLSharedKeys FL_NULLABLE, FLSlice externData)
 Creates an FLDoc from Fleece-encoded data that's been returned as a result from FLSlice_Copy or other API. More...
 
FLEECE_PUBLIC void FLDoc_Release (FLDoc FL_NULLABLE)
 Releases a reference to an FLDoc. More...
 
FLEECE_PUBLIC FLDoc FLDoc_Retain (FLDoc FL_NULLABLE)
 Adds a reference to an FLDoc. More...
 
FLEECE_PUBLIC FLSlice FLDoc_GetData (FLDoc FL_NULLABLE) FLPURE
 Returns the encoded Fleece data backing the document. More...
 
FLEECE_PUBLIC FLSliceResult FLDoc_GetAllocedData (FLDoc FL_NULLABLE) FLPURE
 Returns the FLSliceResult data owned by the document, if any, else a null slice. More...
 
FLEECE_PUBLIC FLValue FLDoc_GetRoot (FLDoc FL_NULLABLE) FLPURE
 Returns the root value in the FLDoc, usually an FLDict. More...
 
FLEECE_PUBLIC FLSharedKeys FLDoc_GetSharedKeys (FLDoc FL_NULLABLE) FLPURE
 Returns the FLSharedKeys used by this FLDoc, as specified when it was created. More...
 
NODISCARD FLEECE_PUBLIC FLDoc FL_NULLABLE FLValue_FindDoc (FLValue FL_NULLABLE) FLPURE
 Looks up the Doc containing the Value, or NULL if there is none. More...
 
FLEECE_PUBLIC bool FLDoc_SetAssociated (FLDoc FL_NULLABLE doc, void *FL_NULLABLE pointer, const char *type)
 Associates an arbitrary pointer value with a document, and thus its contained values. More...
 
FLEECE_PUBLIC void * FLDoc_GetAssociated (FLDoc FL_NULLABLE doc, const char *type) FLPURE
 Returns the pointer associated with the document. More...
 

Detailed Description

Function Documentation

◆ FLDoc_FromResultData()

NODISCARD FLEECE_PUBLIC FLDoc FLDoc_FromResultData ( FLSliceResult  data,
FLTrust  ,
FLSharedKeys  FL_NULLABLE,
FLSlice  externData 
)

Creates an FLDoc from Fleece-encoded data that's been returned as a result from FLSlice_Copy or other API.

The resulting document retains the data, so you don't need to worry about it remaining valid.

◆ FLDoc_GetAllocedData()

FLEECE_PUBLIC FLSliceResult FLDoc_GetAllocedData ( FLDoc  FL_NULLABLE)

Returns the FLSliceResult data owned by the document, if any, else a null slice.

◆ FLDoc_GetAssociated()

FLEECE_PUBLIC void * FLDoc_GetAssociated ( FLDoc FL_NULLABLE  doc,
const char *  type 
)

Returns the pointer associated with the document.

You can use this together with FLValue_FindDoc to associate your own object with Fleece values, for instance to find your object that "owns" a value: myDoc = (app::Document*)FLDoc_GetAssociated(FLValue_FindDoc(val), "app::Document");.

Parameters
docThe FLDoc to get a pointer from.
typeThe type of object expected, i.e. the same string literal passed to FLDoc_SetAssociated.
Returns
The associated pointer of that type, if any.

◆ FLDoc_GetData()

FLEECE_PUBLIC FLSlice FLDoc_GetData ( FLDoc  FL_NULLABLE)

Returns the encoded Fleece data backing the document.

◆ FLDoc_GetRoot()

FLEECE_PUBLIC FLValue FLDoc_GetRoot ( FLDoc  FL_NULLABLE)

Returns the root value in the FLDoc, usually an FLDict.

◆ FLDoc_GetSharedKeys()

FLEECE_PUBLIC FLSharedKeys FLDoc_GetSharedKeys ( FLDoc  FL_NULLABLE)

Returns the FLSharedKeys used by this FLDoc, as specified when it was created.

◆ FLDoc_Release()

FLEECE_PUBLIC void FLDoc_Release ( FLDoc  FL_NULLABLE)

Releases a reference to an FLDoc.

This must be called once to free an FLDoc you created.

◆ FLDoc_Retain()

FLEECE_PUBLIC FLDoc FLDoc_Retain ( FLDoc  FL_NULLABLE)

Adds a reference to an FLDoc.

This extends its lifespan until at least such time as you call FLRelease to remove the reference.

◆ FLDoc_SetAssociated()

FLEECE_PUBLIC bool FLDoc_SetAssociated ( FLDoc FL_NULLABLE  doc,
void *FL_NULLABLE  pointer,
const char *  type 
)

Associates an arbitrary pointer value with a document, and thus its contained values.

Allows client code to associate its own pointer with this FLDoc and its Values, which can later be retrieved with FLDoc_GetAssociated. For example, this could be a pointer to an app::Document object, of which this Doc's root FLDict is its properties. You would store it by calling FLDoc_SetAssociated(doc, myDoc, "app::Document");.

Parameters
docThe FLDoc to store a pointer in.
pointerThe pointer to store in the FLDoc.
typeA C string literal identifying the type. This is used to avoid collisions with unrelated code that might try to store a different type of value.
Returns
True if the pointer was stored, false if a pointer of a different type is already stored.
Warning
Be sure to clear this before the associated object is freed/invalidated!
This function is not thread-safe. Do not concurrently get & set objects.

◆ FLValue_FindDoc()

NODISCARD FLEECE_PUBLIC FLDoc FL_NULLABLE FLValue_FindDoc ( FLValue  FL_NULLABLE)

Looks up the Doc containing the Value, or NULL if there is none.

Note
Caller must release the FLDoc reference!!