|
Couchbase Lite C
Couchbase Lite C API
|
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... | |
| typedef struct _FLSharedKeyScope* FLSharedKeyScope |
| typedef bool(* FLSharedKeysReadCallback) (void *FL_NULLABLE context, FLSharedKeys) |
| 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.
| 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. |
nuu value, encoded as Fleece, or null if an error occurred. | 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.)
| 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. |
old to nuu, or NULL on (extremely unlikely) failure. | 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.
| 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.
| 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!
| 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!
| 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.
| 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.) |
FLEncoder_GetError for details. | 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.)
| 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. |
| 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.
| 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. |
| FLEECE_PUBLIC size_t FLEncoder_FinishItem | ( | FLEncoder | ) |
Finishes encoding the current item, and returns its offset in the output data.
| FLEECE_PUBLIC FLSlice FLEncoder_GetBase | ( | FLEncoder | ) |
Returns the base value passed to FLEncoder_Amend.
| 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.)
| 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.
| 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.
| 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.
| 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.
| 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.
| 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.) |
| 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.
| 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.
| FLEECE_PUBLIC FLString FLSharedKeys_Decode | ( | FLSharedKeys | , |
| int | key | ||
| ) |
Returns the key string that maps to the given integer key, else NULL.
| 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.
| FLEECE_PUBLIC FLSliceResult FLSharedKeys_GetStateData | ( | FLSharedKeys | ) |
Returns a data blob containing the current state (all the keys and their integers.)
| FLEECE_PUBLIC bool FLSharedKeys_LoadState | ( | FLSharedKeys | , |
| FLValue | |||
| ) |
Updates an FLSharedKeys object with saved state, a Fleece value previously written by FLSharedKeys_WriteState.
| FLEECE_PUBLIC bool FLSharedKeys_LoadStateData | ( | FLSharedKeys | , |
| FLSlice | |||
| ) |
Updates an FLSharedKeys with saved state data created by FLSharedKeys_GetStateData.
| FLEECE_PUBLIC FLSharedKeys FLSharedKeys_New | ( | void | ) |
Creates a new empty FLSharedKeys object, which must eventually be released.
| FLEECE_PUBLIC FLSharedKeys FLSharedKeys_NewWithRead | ( | FLSharedKeysReadCallback | , |
| void *FL_NULLABLE | context | ||
| ) |
| FLEECE_PUBLIC void FLSharedKeys_Release | ( | FLSharedKeys | FL_NULLABLE | ) |
Decrements the reference count of an FLSharedKeys, freeing it when it reaches zero.
| FLEECE_PUBLIC FLSharedKeys FL_NULLABLE FLSharedKeys_Retain | ( | FLSharedKeys | FL_NULLABLE | ) |
Increments the reference count of an FLSharedKeys.
| 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_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.
| FLEECE_PUBLIC void FLSharedKeyScope_Free | ( | FLSharedKeyScope | FL_NULLABLE | ) |
Unregisters a scope created by 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.
| 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...
1.9.2