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.

FLEECE_PUBLIC void	FLDoc_Release (FLDoc FL_NULLABLE)
	Releases a reference to an FLDoc.

FLEECE_PUBLIC FLDoc	FLDoc_Retain (FLDoc FL_NULLABLE)
	Adds a reference to an FLDoc.

FLEECE_PUBLIC FLSlice	FLDoc_GetData (FLDoc FL_NULLABLE) FLPURE
	Returns the encoded Fleece data backing the document.

FLEECE_PUBLIC FLSliceResult	FLDoc_GetAllocedData (FLDoc FL_NULLABLE) FLPURE
	Returns the FLSliceResult data owned by the document, if any, else a null slice.

FLEECE_PUBLIC FLValue	FLDoc_GetRoot (FLDoc FL_NULLABLE) FLPURE
	Returns the root value in the FLDoc, usually an FLDict.

FLEECE_PUBLIC FLSharedKeys	FLDoc_GetSharedKeys (FLDoc FL_NULLABLE) FLPURE
	Returns the FLSharedKeys used by this FLDoc, as specified when it was created.

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.

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.

FLEECE_PUBLIC void *	FLDoc_GetAssociated (FLDoc FL_NULLABLE doc, const char *type) FLPURE
	Returns the pointer associated with the document.

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

doc	The FLDoc to get a pointer from.
type	The 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

doc	The FLDoc to store a pointer in.
pointer	The pointer to store in the FLDoc.
type	A 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!!