Rarely-needed or advanced functions

Macros
#define	kFLTrustedDontParse   FLTrust(-1)
	For use with FLDoc_FromResultData.

Shared Keys
FLSharedKeys represents a mapping from short strings to small integers in the range [0...2047]. It's used by FLDict to abbreviate dictionary keys. A shared key can be stored in a fixed two bytes and is faster to compare against. However, the same mapping has to be used when encoding and when accessing the Dict. To use shared keys: Call FLSharedKeys_New to create a new empty mapping. After creating an FLEncoder, call FLEncoder_SetSharedKeys so dictionary keys will be added to the mapping and written in integer form. When loading Fleece data, use FLDoc_FromResultData and pass the FLSharedKeys as a parameter. Save the mapping somewhere by calling FLSharedKeys_GetStateData or FLSharedKeys_WriteState. You can later reconstitute the mapping by calling FLSharedKeys_LoadStateData or FLSharedKeys_LoadState on a new empty instance.
typedef bool(*	FLSharedKeysReadCallback) (void *FL_NULLABLE context, FLSharedKeys)
typedef struct _FLSharedKeyScope *	FLSharedKeyScope
NODISCARD FLEECE_PUBLIC FLSharedKeys	FLSharedKeys_New (void)
	Creates a new empty FLSharedKeys object, which must eventually be released.
NODISCARD FLEECE_PUBLIC FLSharedKeys	FLSharedKeys_NewWithRead (FLSharedKeysReadCallback, void *FL_NULLABLE context)
NODISCARD FLEECE_PUBLIC FLSliceResult	FLSharedKeys_GetStateData (FLSharedKeys)
	Returns a data blob containing the current state (all the keys and their integers.)
FLEECE_PUBLIC bool	FLSharedKeys_LoadStateData (FLSharedKeys, FLSlice)
	Updates an FLSharedKeys with saved state data created by FLSharedKeys_GetStateData.
FLEECE_PUBLIC void	FLSharedKeys_WriteState (FLSharedKeys, FLEncoder)
	Writes the current state to a Fleece encoder as a single value, which can later be decoded and passed to FLSharedKeys_LoadState.
NODISCARD FLEECE_PUBLIC bool	FLSharedKeys_LoadState (FLSharedKeys, FLValue)
	Updates an FLSharedKeys object with saved state, a Fleece value previously written by FLSharedKeys_WriteState.
FLEECE_PUBLIC int	FLSharedKeys_Encode (FLSharedKeys, FLString, bool add)
	Maps a key string to a number in the range [0...2047], or returns -1 if it isn't mapped.
FLEECE_PUBLIC FLString	FLSharedKeys_Decode (FLSharedKeys, int key)
	Returns the key string that maps to the given integer key, else NULL.
FLEECE_PUBLIC unsigned	FLSharedKeys_Count (FLSharedKeys)
	Returns the number of keys in the mapping.
FLEECE_PUBLIC void	FLSharedKeys_RevertToCount (FLSharedKeys, unsigned oldCount)
	Reverts an FLSharedKeys by "forgetting" any keys added since it had the count oldCount.
FLEECE_PUBLIC void	FLSharedKeys_DisableCaching (FLSharedKeys)
	Disable caching of the SharedKeys.
NODISCARD FLEECE_PUBLIC FLSharedKeys FL_NULLABLE	FLSharedKeys_Retain (FLSharedKeys FL_NULLABLE)
	Increments the reference count of an FLSharedKeys.
FLEECE_PUBLIC void	FLSharedKeys_Release (FLSharedKeys FL_NULLABLE)
	Decrements the reference count of an FLSharedKeys, freeing it when it reaches zero.
NODISCARD FLEECE_PUBLIC FLSharedKeyScope	FLSharedKeyScope_WithRange (FLSlice range, FLSharedKeys)
	Registers a range of memory containing Fleece data that uses the given shared keys.
FLEECE_PUBLIC void	FLSharedKeyScope_Free (FLSharedKeyScope FL_NULLABLE)
	Unregisters a scope created by FLSharedKeyScope_WithRange.

Delta Compression
These functions implement a fairly-efficient "delta" encoding that encapsulates the changes needed to transform one Fleece value into another. The delta is expressed in JSON form. A delta can be stored or transmitted as an efficient way to produce the second value, when the first is already present. Deltas are frequently used in version-control systems and efficient network protocols.
NODISCARD FLEECE_PUBLIC FLSliceResult	FLCreateJSONDelta (FLValue FL_NULLABLE old, FLValue FL_NULLABLE nuu)
	Returns JSON that encodes the changes to turn the value old into nuu.
NODISCARD FLEECE_PUBLIC bool	FLEncodeJSONDelta (FLValue FL_NULLABLE old, FLValue FL_NULLABLE nuu, FLEncoder jsonEncoder)
	Writes JSON that describes the changes to turn the value old into nuu.
NODISCARD FLEECE_PUBLIC FLSliceResult	FLApplyJSONDelta (FLValue FL_NULLABLE old, FLSlice jsonDelta, FLError *FL_NULLABLE outError)
	Applies the JSON data created by CreateJSONDelta to the value old, which must be equal to the old value originally passed to FLCreateJSONDelta, and returns a Fleece document equal to the original nuu value.
FLEECE_PUBLIC bool	FLEncodeApplyingJSONDelta (FLValue FL_NULLABLE old, FLSlice jsonDelta, FLEncoder encoder)
	Applies the (parsed) JSON data created by CreateJSONDelta to the value old, which must be equal to the old value originally passed to FLCreateJSONDelta, and writes the corresponding nuu value to the encoder.

Parsing Fleece Data Directly
FLEECE_PUBLIC FLValue FL_NULLABLE	FLValue_FromData (FLSlice data, FLTrust trust) FLPURE
	Returns a pointer to the root value in the encoded data, or NULL if validation failed.

JSON
NODISCARD FLEECE_PUBLIC FLStringResult	FLJSON5_ToJSON (FLString json5, FLStringResult *FL_NULLABLE outErrorMessage, size_t *FL_NULLABLE outErrorPos, FLError *FL_NULLABLE outError)
	Converts valid JSON5 https://json5.org to JSON.
NODISCARD FLEECE_PUBLIC FLSliceResult	FLData_ConvertJSON (FLSlice json, FLError *FL_NULLABLE outError)
	Directly converts JSON data to Fleece-encoded data.

Encoder
FLEECE_PUBLIC void	FLEncoder_Amend (FLEncoder e, FLSlice base, bool reuseStrings, bool externPointers)
	Tells the encoder to logically append to the given Fleece document, rather than making a standalone document.
FLEECE_PUBLIC FLSlice	FLEncoder_GetBase (FLEncoder)
	Returns the base value passed to FLEncoder_Amend.
FLEECE_PUBLIC void	FLEncoder_SuppressTrailer (FLEncoder)
	Tells the encoder not to write the two-byte Fleece trailer at the end of the data.
FLEECE_PUBLIC size_t	FLEncoder_GetNextWritePos (FLEncoder)
	Returns the byte offset in the encoded data where the next value will be written.
FLEECE_PUBLIC intptr_t	FLEncoder_LastValueWritten (FLEncoder)
	Returns an opaque reference to the last complete value written to the encoder, if possible.
FLEECE_PUBLIC bool	FLEncoder_WriteValueAgain (FLEncoder, intptr_t preWrittenValue)
	Writes another reference (a "pointer") to an already-written value, given a reference previously returned from FLEncoder_LastValueWritten.
NODISCARD FLEECE_PUBLIC FLSliceResult	FLEncoder_Snip (FLEncoder)
	Returns the data written so far as a standalone Fleece document, whose root is the last value written.
NODISCARD FLEECE_PUBLIC size_t	FLEncoder_FinishItem (FLEncoder)
	Finishes encoding the current item, and returns its offset in the output data.
FLEECE_PUBLIC void	FLJSONEncoder_NextDocument (FLEncoder)
	In a JSON encoder, adds a newline (' ') and prepares to start encoding another top-level object.
#define	kFLNoWrittenValue   INTPTR_MIN

Debugging Functions
FLEECE_PUBLIC const char *FL_NULLABLE	FLDump (FLValue FL_NULLABLE)
	Debugging function that returns a C string of JSON.
FLEECE_PUBLIC const char *FL_NULLABLE	FLDumpData (FLSlice data)
	Debugging function that parses Fleece data and returns a C string of JSON.
FLEECE_PUBLIC FLStringResult	FLData_Dump (FLSlice data)
	Produces a human-readable dump of Fleece-encoded data.

Detailed Description

Macro Definition Documentation

kFLNoWrittenValue

#define kFLNoWrittenValue   INTPTR_MIN

kFLTrustedDontParse

#define kFLTrustedDontParse   FLTrust(-1)

For use with FLDoc_FromResultData.

This option prevents the function from parsing the data at all; you are responsible for locating the FLValues in it. This is for the case where you have trusted data in a custom format that contains Fleece- encoded data within it. You still need an FLDoc to access the data safely (especially to retain FLValues), but it can't be parsed as-is.

Typedef Documentation

FLSharedKeyScope

typedef struct _FLSharedKeyScope* FLSharedKeyScope

FLSharedKeysReadCallback

typedef bool(* FLSharedKeysReadCallback) (void *FL_NULLABLE context, FLSharedKeys)

Function Documentation

FLApplyJSONDelta()

NODISCARD FLEECE_PUBLIC FLSliceResult FLApplyJSONDelta	(	FLValue FL_NULLABLE	old,
		FLSlice	jsonDelta,
		FLError *FL_NULLABLE	outError )

Applies the JSON data created by CreateJSONDelta to the value old, which must be equal to the old value originally passed to FLCreateJSONDelta, and returns a Fleece document equal to the original nuu value.

Parameters

old	A value that's typically the old/original state of some data. This must be equal to the old value used when creating the jsonDelta.
jsonDelta	A JSON-encoded delta created by FLCreateJSONDelta or FLEncodeJSONDelta.
outError	On failure, error information will be stored where this points, if non-null.

Returns

The corresponding nuu value, encoded as Fleece, or null if an error occurred.

FLCreateJSONDelta()

NODISCARD FLEECE_PUBLIC FLSliceResult FLCreateJSONDelta	(	FLValue FL_NULLABLE	old,
		FLValue FL_NULLABLE	nuu )

Returns JSON that encodes the changes to turn the value old into nuu.

(The format is documented in Fleece.md, but you should treat it as a black box.)

Parameters

old	A value that's typically the old/original state of some data.
nuu	A value that's typically the new/changed state of the old data.

Returns

JSON data representing the changes from old to nuu, or NULL on (extremely unlikely) failure.

FLData_ConvertJSON()

NODISCARD FLEECE_PUBLIC FLSliceResult FLData_ConvertJSON	(	FLSlice	json,
		FLError *FL_NULLABLE	outError )

Directly converts JSON data to Fleece-encoded data.

Not commonly needed. Prefer FLDoc_FromJSON instead.

FLData_Dump()

FLEECE_PUBLIC FLStringResult FLData_Dump

(

FLSlice

data

)

Produces a human-readable dump of Fleece-encoded data.

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

FLDump()

FLEECE_PUBLIC const char *FL_NULLABLE FLDump

(

FLValue

FL_NULLABLE

)

Debugging function that returns a C string of JSON.

Does not free the string's memory!

FLDumpData()

FLEECE_PUBLIC const char *FL_NULLABLE FLDumpData

(

FLSlice

data

)

Debugging function that parses Fleece data and returns a C string of JSON.

Does not free the string's memory!

FLEncodeApplyingJSONDelta()

FLEECE_PUBLIC bool FLEncodeApplyingJSONDelta	(	FLValue FL_NULLABLE	old,
		FLSlice	jsonDelta,
		FLEncoder	encoder )

Applies the (parsed) JSON data created by CreateJSONDelta to the value old, which must be equal to the old value originally passed to FLCreateJSONDelta, and writes the corresponding nuu value to the encoder.

Parameters

old	A value that's typically the old/original state of some data. This must be equal to the old value used when creating the jsonDelta.
jsonDelta	A JSON-encoded delta created by FLCreateJSONDelta or FLEncodeJSONDelta.
encoder	A Fleece encoder to write the decoded nuu value to. (JSON encoding is not supported.)

Returns

True on success, false on error; call FLEncoder_GetError for details.

FLEncodeJSONDelta()

NODISCARD FLEECE_PUBLIC bool FLEncodeJSONDelta	(	FLValue FL_NULLABLE	old,
		FLValue FL_NULLABLE	nuu,
		FLEncoder	jsonEncoder )

Writes JSON that describes the changes to turn the value old into nuu.

(The format is documented in Fleece.md, but you should treat it as a black box.)

Parameters

old	A value that's typically the old/original state of some data.
nuu	A value that's typically the new/changed state of the old data.
jsonEncoder	An encoder to write the JSON to. Must have been created using FLEncoder_NewWithOptions, with JSON or JSON5 format.

Returns

True on success, false on (extremely unlikely) failure.

FLEncoder_Amend()

FLEECE_PUBLIC void FLEncoder_Amend	(	FLEncoder	e,
		FLSlice	base,
		bool	reuseStrings,
		bool	externPointers )

Tells the encoder to logically append to the given Fleece document, rather than making a standalone document.

Any calls to FLEncoder_WriteValue() where the value points inside the base data will write a pointer back to the original value. The resulting data returned by FLEncoder_FinishDoc() will NOT be standalone; it can only be used by first appending it to the base data.

Parameters

e	The FLEncoder affected.
base	The base document to create an amendment of.
reuseStrings	If true, then writing a string that already exists in the base will just create a pointer back to the original. But the encoder has to scan the base for strings first.
externPointers	If true, pointers into the base will be marked with the extern flag. This allows them to be resolved using the FLResolver_Begin function, so that when the delta is used the base document can be anywhere in memory, not just immediately preceding the delta document.

FLEncoder_FinishItem()

NODISCARD FLEECE_PUBLIC size_t FLEncoder_FinishItem

(

FLEncoder

)

Finishes encoding the current item, and returns its offset in the output data.

FLEncoder_GetBase()

FLEECE_PUBLIC FLSlice FLEncoder_GetBase

(

FLEncoder

)

Returns the base value passed to FLEncoder_Amend.

FLEncoder_GetNextWritePos()

FLEECE_PUBLIC size_t FLEncoder_GetNextWritePos

(

FLEncoder

)

Returns the byte offset in the encoded data where the next value will be written.

(Due to internal buffering, this is not the same as FLEncoder_BytesWritten.)

FLEncoder_LastValueWritten()

FLEECE_PUBLIC intptr_t FLEncoder_LastValueWritten

(

FLEncoder

)

Returns an opaque reference to the last complete value written to the encoder, if possible.

Fails (returning kFLNoWrittenValue) if nothing has been written, or if the value is inline and can't be referenced this way – that only happens with small scalars or empty collections.

FLEncoder_Snip()

NODISCARD FLEECE_PUBLIC FLSliceResult FLEncoder_Snip

(

FLEncoder

)

Returns the data written so far as a standalone Fleece document, whose root is the last value written.

You can continue writing, and the final output returned by FLEncoder_Finish will consist of everything after this point. That second part can be used in the future by loading it as an FLDoc with the first part as its extern reference.

FLEncoder_SuppressTrailer()

FLEECE_PUBLIC void FLEncoder_SuppressTrailer

(

FLEncoder

)

Tells the encoder not to write the two-byte Fleece trailer at the end of the data.

This is only useful for certain special purposes.

FLEncoder_WriteValueAgain()

FLEECE_PUBLIC bool FLEncoder_WriteValueAgain	(	FLEncoder	,
		intptr_t	preWrittenValue )

Writes another reference (a "pointer") to an already-written value, given a reference previously returned from FLEncoder_LastValueWritten.

The effect is exactly the same as if you wrote the entire value again, except that the size of the encoded data only grows by 4 bytes. Returns false if the reference couldn't be written.

FLJSON5_ToJSON()

NODISCARD FLEECE_PUBLIC FLStringResult FLJSON5_ToJSON	(	FLString	json5,
		FLStringResult *FL_NULLABLE	outErrorMessage,
		size_t *FL_NULLABLE	outErrorPos,
		FLError *FL_NULLABLE	outError )

Converts valid JSON5 https://json5.org to JSON.

Among other things, it converts single quotes to double, adds missing quotes around dictionary keys, removes trailing commas, and removes comments.

Note

If given invalid JSON5, it will usually return an error, but may just ouput comparably invalid JSON, in which case the caller's subsequent JSON parsing will detect the error. The types of errors it overlooks tend to be subtleties of string or number encoding.

Parameters

json5	The JSON5 to parse
outErrorMessage	On failure, the error message will be stored here (if not NULL.) As this is a FLStringResult, you will be responsible for freeing it.
outErrorPos	On a parse error, the byte offset in the input where the error occurred will be stored here (if it's not NULL.)
outError	On failure, the error code will be stored here (if it's not NULL.)

Returns

The converted JSON.

FLJSONEncoder_NextDocument()

FLEECE_PUBLIC void FLJSONEncoder_NextDocument

(

FLEncoder

)

In a JSON encoder, adds a newline ('
') and prepares to start encoding another top-level object.

The encoder MUST be not be within an array or dict. Has no effect in a Fleece encoder.

FLSharedKeys_Count()

FLEECE_PUBLIC unsigned FLSharedKeys_Count

(

FLSharedKeys

)

Returns the number of keys in the mapping.

This number increases whenever the mapping is changed, and never decreases.

FLSharedKeys_Decode()

FLEECE_PUBLIC FLString FLSharedKeys_Decode	(	FLSharedKeys	,
		int	key )

Returns the key string that maps to the given integer key, else NULL.

FLSharedKeys_DisableCaching()

FLEECE_PUBLIC void FLSharedKeys_DisableCaching

(

FLSharedKeys

)

Disable caching of the SharedKeys.

FLSharedKeys_Encode()

FLEECE_PUBLIC int FLSharedKeys_Encode	(	FLSharedKeys	,
		FLString	,
		bool	add )

Maps a key string to a number in the range [0...2047], or returns -1 if it isn't mapped.

If the key doesn't already have a mapping, and the add flag is true, a new mapping is assigned and returned. However, the add flag has no effect if the key is unmappable (is longer than 16 bytes or contains non-identifier characters), or if all available integers have been assigned.

FLSharedKeys_GetStateData()

NODISCARD FLEECE_PUBLIC FLSliceResult FLSharedKeys_GetStateData

(

FLSharedKeys

)

Returns a data blob containing the current state (all the keys and their integers.)

FLSharedKeys_LoadState()

NODISCARD FLEECE_PUBLIC bool FLSharedKeys_LoadState	(	FLSharedKeys	,
		FLValue	)

Updates an FLSharedKeys object with saved state, a Fleece value previously written by FLSharedKeys_WriteState.

FLSharedKeys_LoadStateData()

FLEECE_PUBLIC bool FLSharedKeys_LoadStateData	(	FLSharedKeys	,
		FLSlice	)

Updates an FLSharedKeys with saved state data created by FLSharedKeys_GetStateData.

Returns true if new keys were added, false if not.

FLSharedKeys_New()

NODISCARD FLEECE_PUBLIC FLSharedKeys FLSharedKeys_New

(

void

)

Creates a new empty FLSharedKeys object, which must eventually be released.

FLSharedKeys_NewWithRead()

NODISCARD FLEECE_PUBLIC FLSharedKeys FLSharedKeys_NewWithRead	(	FLSharedKeysReadCallback	,
		void *FL_NULLABLE	context )

FLSharedKeys_Release()

FLEECE_PUBLIC void FLSharedKeys_Release

(

FLSharedKeys

FL_NULLABLE

)

Decrements the reference count of an FLSharedKeys, freeing it when it reaches zero.

FLSharedKeys_Retain()

NODISCARD FLEECE_PUBLIC FLSharedKeys FL_NULLABLE FLSharedKeys_Retain

(

FLSharedKeys

FL_NULLABLE

)

Increments the reference count of an FLSharedKeys.

FLSharedKeys_RevertToCount()

FLEECE_PUBLIC void FLSharedKeys_RevertToCount	(	FLSharedKeys	,
		unsigned	oldCount )

Reverts an FLSharedKeys by "forgetting" any keys added since it had the count oldCount.

FLSharedKeys_WriteState()

FLEECE_PUBLIC void FLSharedKeys_WriteState	(	FLSharedKeys	,
		FLEncoder	)

Writes the current state to a Fleece encoder as a single value, which can later be decoded and passed to FLSharedKeys_LoadState.

FLSharedKeyScope_Free()

FLEECE_PUBLIC void FLSharedKeyScope_Free

(

FLSharedKeyScope

FL_NULLABLE

)

Unregisters a scope created by FLSharedKeyScope_WithRange.

FLSharedKeyScope_WithRange()

NODISCARD FLEECE_PUBLIC FLSharedKeyScope FLSharedKeyScope_WithRange	(	FLSlice	range,
		FLSharedKeys	)

Registers a range of memory containing Fleece data that uses the given shared keys.

This allows Dict accessors to look up the values of shared keys.

FLValue_FromData()

FLEECE_PUBLIC FLValue FL_NULLABLE FLValue_FromData	(	FLSlice	data,
		FLTrust	trust )

Returns a pointer to the root value in the encoded data, or NULL if validation failed.

You should generally use an FLDoc instead; it's safer. Here's why:

On the plus side, FLValue_FromData is extremely fast: it allocates no memory, only scans enough of the data to ensure it's valid (and if trust is set to kFLTrusted, it doesn't even do that.)

But it's potentially very dangerous: the FLValue, and all values found through it, are only valid as long as the input data remains intact and unchanged. If you violate that, the values will be pointing to garbage and Bad Things will happen when you access them...