FLDoc
An FLDoc points to (and often owns) Fleece-encoded data and provides access to its Fleece values.
enum	FLTrust { kFLUntrusted , kFLTrusted }
	Specifies whether not input data is trusted to be 100% valid Fleece. More...

typedef struct _FLDoc *	FLDoc
	A reference to a document. More...

typedef struct _FLSharedKeys *	FLSharedKeys
	A reference to a shared-keys mapping. More...

FLDoc	FLDoc_FromResultData (FLSliceResult data, FLTrust, FLSharedKeys, FLSlice externData)
	Creates an FLDoc from Fleece-encoded data that's been returned as a result from FLSlice_Copy or other API. More...

FLDoc	FLDoc_FromJSON (FLSlice json, FLError *outError)
	Creates an FLDoc from JSON-encoded data. More...

void	FLDoc_Release (FLDoc)
	Releases a reference to an FLDoc. More...

FLDoc	FLDoc_Retain (FLDoc)
	Adds a reference to an FLDoc. More...

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

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

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

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

bool	FLDoc_SetAssociated (FLDoc doc, void pointer, const char type)
	Associates an arbitrary pointer value with a document, and thus its contained values. More...

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

FLDoc	FLValue_FindDoc (FLValue) FLPURE
	Looks up the Doc containing the Value, or NULL if the Value was created without a Doc. More...

Parsing And Converting Values Directly
FLValue	FLValue_FromData (FLSlice data, FLTrust) FLPURE
	Returns a pointer to the root value in the encoded data, or NULL if validation failed. More...

FLSliceResult	FLData_ConvertJSON (FLSlice json, FLError *outError)
	Directly converts JSON data to Fleece-encoded data. More...

FLStringResult	FLData_Dump (FLSlice data)
	Produces a human-readable dump of the Value encoded in the data. More...

Detailed Description

Typedef Documentation

◆ FLDoc

typedef struct _FLDoc* FLDoc

A reference to a document.

◆ FLSharedKeys

typedef struct _FLSharedKeys* FLSharedKeys

A reference to a shared-keys mapping.

Enumeration Type Documentation

◆ FLTrust

enum FLTrust

Specifies whether not input data is trusted to be 100% valid Fleece.

Enumerator

kFLUntrusted

Input data is not trusted to be valid, and will be fully validated by the API call.

kFLTrusted

Input data is trusted to be valid.

The API will perform only minimal validation when reading it. This is faster than kFLUntrusted, but should only be used if the data was generated by a trusted encoder and has not been altered or corrupted. For example, this can be used to parse Fleece data previously stored by your code in local storage. If invalid data is read by this call, subsequent calls to Value accessor functions can crash or return bogus results (including data from arbitrary memory locations.)

Function Documentation

◆ FLData_ConvertJSON()

FLSliceResult FLData_ConvertJSON	(	FLSlice	json,
		FLError *	outError
	)

Directly converts JSON data to Fleece-encoded data.

You can then call FLValue_FromData (in kFLTrusted mode) to get the root as a Value.

◆ FLData_Dump()

FLStringResult FLData_Dump ( FLSlice data )

Produces a human-readable dump of the Value encoded in the data.

This is only useful if you already know, or want to learn, the encoding format.

◆ FLDoc_FromJSON()

FLDoc FLDoc_FromJSON	(	FLSlice	json,
		FLError *	outError
	)

Creates an FLDoc from JSON-encoded data.

The data is first encoded into Fleece, and the Fleece data is kept by the doc; the input JSON data is no longer needed after this function returns.

◆ FLDoc_FromResultData()

FLDoc FLDoc_FromResultData	(	FLSliceResult	data,
		FLTrust	,
		FLSharedKeys	,
		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()

FLSliceResult FLDoc_GetAllocedData ( FLDoc )

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

◆ FLDoc_GetAssociated()

void * FLDoc_GetAssociated	(	FLDoc	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()

FLSlice FLDoc_GetData ( FLDoc )

Returns the encoded Fleece data backing the document.

◆ FLDoc_GetRoot()

FLValue FLDoc_GetRoot ( FLDoc )

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

◆ FLDoc_GetSharedKeys()

FLSharedKeys FLDoc_GetSharedKeys ( FLDoc )

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

◆ FLDoc_Release()

void FLDoc_Release ( FLDoc )

Releases a reference to an FLDoc.

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

◆ FLDoc_Retain()

FLDoc FLDoc_Retain ( FLDoc )

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()

bool FLDoc_SetAssociated	(	FLDoc	doc,
		void *	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");.