Couchbase Lite C
Couchbase Lite C API
Rarely-needed or advanced functions

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
 
FLEECE_PUBLIC FLSharedKeys FLSharedKeys_New (void)
 Creates a new empty FLSharedKeys object, which must eventually be released. More...
 
FLEECE_PUBLIC FLSharedKeys FLSharedKeys_NewWithRead (FLSharedKeysReadCallback, void *FL_NULLABLE context)
 
FLEECE_PUBLIC FLSliceResult FLSharedKeys_GetStateData (FLSharedKeys)
 Returns a data blob containing the current state (all the keys and their integers.) More...
 
FLEECE_PUBLIC bool FLSharedKeys_LoadStateData (FLSharedKeys, FLSlice)
 Updates an FLSharedKeys with saved state data created by FLSharedKeys_GetStateData. More...
 
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. More...
 
FLEECE_PUBLIC bool FLSharedKeys_LoadState (FLSharedKeys, FLValue)
 Updates an FLSharedKeys object with saved state, a Fleece value previously written by FLSharedKeys_WriteState. More...
 
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. More...
 
FLEECE_PUBLIC FLString FLSharedKeys_Decode (FLSharedKeys, int key)
 Returns the key string that maps to the given integer key, else NULL. More...
 
FLEECE_PUBLIC unsigned FLSharedKeys_Count (FLSharedKeys)
 Returns the number of keys in the mapping. More...
 
FLEECE_PUBLIC void FLSharedKeys_RevertToCount (FLSharedKeys, unsigned oldCount)
 Reverts an FLSharedKeys by "forgetting" any keys added since it had the count oldCount. More...
 
FLEECE_PUBLIC FLSharedKeys FL_NULLABLE FLSharedKeys_Retain (FLSharedKeys FL_NULLABLE)
 Increments the reference count of an FLSharedKeys. More...
 
FLEECE_PUBLIC void FLSharedKeys_Release (FLSharedKeys FL_NULLABLE)
 Decrements the reference count of an FLSharedKeys, freeing it when it reaches zero. More...
 
FLEECE_PUBLIC FLSharedKeyScope FLSharedKeyScope_WithRange (FLSlice range, FLSharedKeys)
 Registers a range of memory containing Fleece data that uses the given shared keys. More...
 
FLEECE_PUBLIC void FLSharedKeyScope_Free (FLSharedKeyScope FL_NULLABLE)
 Unregisters a scope created by FLSharedKeyScope_WithRange. More...
 

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.

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. More...
 
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. More...
 
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. More...
 
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. More...
 

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. More...
 

JSON

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. More...
 
FLEECE_PUBLIC FLSliceResult FLData_ConvertJSON (FLSlice json, FLError *FL_NULLABLE outError)
 Directly converts JSON data to Fleece-encoded data. More...
 

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. More...
 
FLEECE_PUBLIC FLSlice FLEncoder_GetBase (FLEncoder)
 Returns the base value passed to FLEncoder_Amend. More...
 
FLEECE_PUBLIC void FLEncoder_SuppressTrailer (FLEncoder)
 Tells the encoder not to write the two-byte Fleece trailer at the end of the data. More...
 
FLEECE_PUBLIC size_t FLEncoder_GetNextWritePos (FLEncoder)
 Returns the byte offset in the encoded data where the next value will be written. More...
 
FLEECE_PUBLIC intptr_t FLEncoder_LastValueWritten (FLEncoder)
 Returns an opaque reference to the last complete value written to the encoder, if possible. More...
 
FLEECE_PUBLIC void FLEncoder_WriteValueAgain (FLEncoder, intptr_t preWrittenValue)
 Writes another reference (a "pointer") to an already-written value, given a reference previously returned from FLEncoder_LastValueWritten. More...
 
FLEECE_PUBLIC FLSliceResult FLEncoder_Snip (FLEncoder)
 Returns the data written so far as a standalone Fleece document, whose root is the last value written. More...
 
FLEECE_PUBLIC size_t FLEncoder_FinishItem (FLEncoder)
 Finishes encoding the current item, and returns its offset in the output data. More...
 
FLEECE_PUBLIC void FLJSONEncoder_NextDocument (FLEncoder)
 In a JSON encoder, adds a newline ('
') and prepares to start encoding another top-level object. More...
 

Debugging Functions

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

Detailed Description

Typedef Documentation

◆ FLSharedKeyScope

typedef struct _FLSharedKeyScope* FLSharedKeyScope

◆ FLSharedKeysReadCallback

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

Function Documentation

◆ FLApplyJSONDelta()

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
oldA value that's typically the old/original state of some data. This must be equal to the old value used when creating the jsonDelta.
jsonDeltaA JSON-encoded delta created by FLCreateJSONDelta or FLEncodeJSONDelta.
outErrorOn 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()

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
oldA value that's typically the old/original state of some data.
nuuA 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()

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
oldA value that's typically the old/original state of some data. This must be equal to the old value used when creating the jsonDelta.
jsonDeltaA JSON-encoded delta created by FLCreateJSONDelta or FLEncodeJSONDelta.
encoderA 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()

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
oldA value that's typically the old/original state of some data.
nuuA value that's typically the new/changed state of the old data.
jsonEncoderAn 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
eThe FLEncoder affected.
baseThe base document to create an amendment of.
reuseStringsIf 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.
externPointersIf 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()

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

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 void 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.

◆ FLJSON5_ToJSON()

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
json5The JSON5 to parse
outErrorMessageOn failure, the error message will be stored here (if not NULL.) As this is a FLStringResult, you will be responsible for freeing it.
outErrorPosOn a parse error, the byte offset in the input where the error occurred will be stored here (if it's not NULL.)
outErrorOn 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_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()

FLEECE_PUBLIC FLSliceResult FLSharedKeys_GetStateData ( FLSharedKeys  )

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

◆ FLSharedKeys_LoadState()

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.

◆ FLSharedKeys_New()

FLEECE_PUBLIC FLSharedKeys FLSharedKeys_New ( void  )

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

◆ FLSharedKeys_NewWithRead()

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

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

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...