Couchbase Lite C
Couchbase Lite C API
Fleece Encoders

An FLEncoder generates encoded Fleece or JSON data. More...

Setup and configuration

enum  FLEncoderFormat { kFLEncodeFleece , kFLEncodeJSON , kFLEncodeJSON5 }
 Output formats a FLEncoder can generate. More...
 
FLEncoder FLEncoder_New (void)
 Creates a new encoder, for generating Fleece data. More...
 
FLEncoder FLEncoder_NewWithOptions (FLEncoderFormat format, size_t reserveSize, bool uniqueStrings)
 Creates a new encoder, allowing some options to be customized. More...
 
FLEncoder FLEncoder_NewWritingToFile (FILE *, bool uniqueStrings)
 Creates a new Fleece encoder that writes to a file, not to memory. More...
 
void FLEncoder_Free (FLEncoder)
 Frees the space used by an encoder. More...
 
void FLEncoder_SetSharedKeys (FLEncoder, FLSharedKeys)
 Tells the encoder to use a shared-keys mapping when encoding dictionary keys. More...
 
void FLEncoder_SetExtraInfo (FLEncoder, void *info)
 Associates an arbitrary user-defined value with the encoder. More...
 
void * FLEncoder_GetExtraInfo (FLEncoder)
 Returns the user-defined value associated with the encoder; NULL by default. More...
 
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...
 
FLSlice FLEncoder_GetBase (FLEncoder)
 Returns the base value passed to FLEncoder_Amend. More...
 
void FLEncoder_SuppressTrailer (FLEncoder)
 Tells the encoder not to write the two-byte Fleece trailer at the end of the data. More...
 
void FLEncoder_Reset (FLEncoder)
 Resets the state of an encoder without freeing it. More...
 
size_t FLEncoder_BytesWritten (FLEncoder)
 Returns the number of bytes encoded so far. More...
 
size_t FLEncoder_GetNextWritePos (FLEncoder)
 Returns the byte offset in the encoded data where the next value will be written. More...
 

Writing to the encoder

Note
The functions that write to the encoder do not return error codes, just a 'false' result on error. The actual error is attached to the encoder and can be accessed by calling FLEncoder_GetError or FLEncoder_End.

After an error occurs, the encoder will ignore all subsequent writes.

bool FLEncoder_WriteNull (FLEncoder)
 Writes a null value to an encoder. More...
 
bool FLEncoder_WriteUndefined (FLEncoder)
 Writes an undefined value to an encoder. More...
 
bool FLEncoder_WriteBool (FLEncoder, bool)
 Writes a boolean value (true or false) to an encoder. More...
 
bool FLEncoder_WriteInt (FLEncoder, int64_t)
 Writes an integer to an encoder. More...
 
bool FLEncoder_WriteUInt (FLEncoder, uint64_t)
 Writes an unsigned integer to an encoder. More...
 
bool FLEncoder_WriteFloat (FLEncoder, float)
 Writes a 32-bit floating point number to an encoder. More...
 
bool FLEncoder_WriteDouble (FLEncoder, double)
 Writes a 64-bit floating point number to an encoder. More...
 
bool FLEncoder_WriteString (FLEncoder, FLString)
 Writes a string to an encoder. More...
 
bool FLEncoder_WriteDateString (FLEncoder encoder, FLTimestamp ts, bool asUTC)
 Writes a timestamp to an encoder, as an ISO-8601 date string. More...
 
bool FLEncoder_WriteData (FLEncoder, FLSlice)
 Writes a binary data value (a blob) to an encoder. More...
 
bool FLEncoder_WriteRaw (FLEncoder, FLSlice)
 Writes raw data directly to the encoded output. More...
 
bool FLEncoder_BeginArray (FLEncoder, size_t reserveCount)
 Begins writing an array value to an encoder. More...
 
bool FLEncoder_EndArray (FLEncoder)
 Ends writing an array value; pops back the previous encoding state. More...
 
bool FLEncoder_BeginDict (FLEncoder, size_t reserveCount)
 Begins writing a dictionary value to an encoder. More...
 
bool FLEncoder_WriteKey (FLEncoder, FLString)
 Specifies the key for the next value to be written to the current dictionary. More...
 
bool FLEncoder_WriteKeyValue (FLEncoder, FLValue)
 Specifies the key for the next value to be written to the current dictionary. More...
 
bool FLEncoder_EndDict (FLEncoder)
 Ends writing a dictionary value; pops back the previous encoding state. More...
 
bool FLEncoder_WriteValue (FLEncoder, FLValue)
 Writes a Fleece Value to an Encoder. More...
 
intptr_t FLEncoder_LastValueWritten (FLEncoder e)
 Returns an opaque reference to the last complete value written to the encoder, if possible. More...
 
void FLEncoder_WriteValueAgain (FLEncoder e, intptr_t preWrittenValue)
 Writes another reference (a "pointer") to an already-written value, given a reference previously returned from FLEncoder_LastValueWritten. More...
 
FLSliceResult FLEncoder_Snip (FLEncoder e)
 Returns the data written so far as a standalone Fleece document, whose root is the last value written. More...
 
bool FLEncoder_ConvertJSON (FLEncoder, FLSlice json)
 Parses JSON data and writes the object(s) to the encoder. More...
 

Finishing up

size_t FLEncoder_FinishItem (FLEncoder)
 Finishes encoding the current item, and returns its offset in the output data. More...
 
FLDoc FLEncoder_FinishDoc (FLEncoder, FLError *)
 Ends encoding; if there has been no error, it returns the encoded Fleece data packaged in an FLDoc. More...
 
MUST_USE_RESULT FLSliceResult FLEncoder_Finish (FLEncoder e, FLError *outError)
 Ends encoding; if there has been no error, it returns the encoded data, else null. More...
 

Error handling

FLError FLEncoder_GetError (FLEncoder)
 Returns the error code of an encoder, or NoError (0) if there's no error. More...
 
const char * FLEncoder_GetErrorMessage (FLEncoder)
 Returns the error message of an encoder, or NULL if there's no error. More...
 

Detailed Description

An FLEncoder generates encoded Fleece or JSON data.

It's sort of a structured output stream, with nesting. There are functions for writing every type of scalar value, and for beginning and ending collections. To write a collection you begin it, write its values, then end it. (Of course a value in a collection can itself be another collection.) When writing a dictionary, you have to call writeKey before writing each value.

Enumeration Type Documentation

◆ FLEncoderFormat

Output formats a FLEncoder can generate.

Enumerator
kFLEncodeFleece 

Fleece encoding.

kFLEncodeJSON 

JSON encoding.

kFLEncodeJSON5 

JSON5, an extension of JSON with a more readable syntax

Function Documentation

◆ FLEncoder_Amend()

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

bool FLEncoder_BeginArray ( FLEncoder  ,
size_t  reserveCount 
)

Begins writing an array value to an encoder.

This pushes a new state where each subsequent value written becomes an array item, until FLEncoder_EndArray is called.

Parameters
reserveCountNumber of array elements to reserve space for. If you know the size of the array, providing it here speeds up encoding slightly. If you don't know, just use zero.

◆ FLEncoder_BeginDict()

bool FLEncoder_BeginDict ( FLEncoder  ,
size_t  reserveCount 
)

Begins writing a dictionary value to an encoder.

This pushes a new state where each subsequent key and value written are added to the dictionary, until FLEncoder_EndDict is called. Before adding each value, you must call FLEncoder_WriteKey (not FLEncoder_WriteString!), to write the dictionary key.

Parameters
reserveCountNumber of dictionary items to reserve space for. If you know the size of the dictionary, providing it here speeds up encoding slightly. If you don't know, just use zero.

◆ FLEncoder_BytesWritten()

size_t FLEncoder_BytesWritten ( FLEncoder  )

Returns the number of bytes encoded so far.

◆ FLEncoder_ConvertJSON()

bool FLEncoder_ConvertJSON ( FLEncoder  ,
FLSlice  json 
)

Parses JSON data and writes the object(s) to the encoder.

(This acts as a single write, like WriteInt; it's just that the value written is likely to be an entire dictionary of array.)

◆ FLEncoder_EndArray()

bool FLEncoder_EndArray ( FLEncoder  )

Ends writing an array value; pops back the previous encoding state.

◆ FLEncoder_EndDict()

bool FLEncoder_EndDict ( FLEncoder  )

Ends writing a dictionary value; pops back the previous encoding state.

◆ FLEncoder_Finish()

MUST_USE_RESULT FLSliceResult FLEncoder_Finish ( FLEncoder  e,
FLError outError 
)

Ends encoding; if there has been no error, it returns the encoded data, else null.

This does not free the FLEncoder; call FLEncoder_Free (or FLEncoder_Reset) next.

◆ FLEncoder_FinishDoc()

FLDoc FLEncoder_FinishDoc ( FLEncoder  ,
FLError  
)

Ends encoding; if there has been no error, it returns the encoded Fleece data packaged in an FLDoc.

(This function does not support JSON encoding.) This does not free the FLEncoder; call FLEncoder_Free (or FLEncoder_Reset) next.

◆ FLEncoder_FinishItem()

size_t FLEncoder_FinishItem ( FLEncoder  )

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

◆ FLEncoder_Free()

void FLEncoder_Free ( FLEncoder  )

Frees the space used by an encoder.

◆ FLEncoder_GetBase()

FLSlice FLEncoder_GetBase ( FLEncoder  )

Returns the base value passed to FLEncoder_Amend.

◆ FLEncoder_GetError()

FLError FLEncoder_GetError ( FLEncoder  )

Returns the error code of an encoder, or NoError (0) if there's no error.

◆ FLEncoder_GetErrorMessage()

const char * FLEncoder_GetErrorMessage ( FLEncoder  )

Returns the error message of an encoder, or NULL if there's no error.

◆ FLEncoder_GetExtraInfo()

void * FLEncoder_GetExtraInfo ( FLEncoder  )

Returns the user-defined value associated with the encoder; NULL by default.

◆ FLEncoder_GetNextWritePos()

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

intptr_t FLEncoder_LastValueWritten ( FLEncoder  e)

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

FLEncoder FLEncoder_New ( void  )

Creates a new encoder, for generating Fleece data.

Call FLEncoder_Free when done.

◆ FLEncoder_NewWithOptions()

FLEncoder FLEncoder_NewWithOptions ( FLEncoderFormat  format,
size_t  reserveSize,
bool  uniqueStrings 
)

Creates a new encoder, allowing some options to be customized.

Parameters
formatThe output format to generate (Fleece, JSON, or JSON5.)
reserveSizeThe number of bytes to preallocate for the output. (Default is 256)
uniqueStrings(Fleece only) If true, string values that appear multiple times will be written as a single shared value. This saves space but makes encoding slightly slower. You should only turn this off if you know you're going to be writing large numbers of non-repeated strings. (Default is true)

◆ FLEncoder_NewWritingToFile()

FLEncoder FLEncoder_NewWritingToFile ( FILE *  ,
bool  uniqueStrings 
)

Creates a new Fleece encoder that writes to a file, not to memory.

◆ FLEncoder_Reset()

void FLEncoder_Reset ( FLEncoder  )

Resets the state of an encoder without freeing it.

It can then be reused to encode another value.

◆ FLEncoder_SetExtraInfo()

void FLEncoder_SetExtraInfo ( FLEncoder  ,
void *  info 
)

Associates an arbitrary user-defined value with the encoder.

◆ FLEncoder_SetSharedKeys()

void FLEncoder_SetSharedKeys ( FLEncoder  ,
FLSharedKeys   
)

Tells the encoder to use a shared-keys mapping when encoding dictionary keys.

◆ FLEncoder_Snip()

FLSliceResult FLEncoder_Snip ( FLEncoder  e)

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

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

bool FLEncoder_WriteBool ( FLEncoder  ,
bool   
)

Writes a boolean value (true or false) to an encoder.

◆ FLEncoder_WriteData()

bool FLEncoder_WriteData ( FLEncoder  ,
FLSlice   
)

Writes a binary data value (a blob) to an encoder.

This can contain absolutely anything including null bytes. If the encoder is generating JSON, the blob will be written as a base64-encoded string.

◆ FLEncoder_WriteDateString()

bool FLEncoder_WriteDateString ( FLEncoder  encoder,
FLTimestamp  ts,
bool  asUTC 
)

Writes a timestamp to an encoder, as an ISO-8601 date string.

Note
Since neither Fleece nor JSON have a 'Date' type, the encoded string has no metadata that distinguishes it as a date. It's just a string.)
Parameters
encoderThe encoder to write to.
tsThe timestamp (milliseconds since Unix epoch 1-1-1970).
asUTCIf true, date is written in UTC (GMT); if false, with the local timezone.
Returns
True on success, false on error.

◆ FLEncoder_WriteDouble()

bool FLEncoder_WriteDouble ( FLEncoder  ,
double   
)

Writes a 64-bit floating point number to an encoder.

Note
As an implementation detail, the number may be encoded as a 32-bit float or even as an integer, if this can be done without losing precision. For example, 123.0 will be written as an integer, and 123.75 as a float.)

◆ FLEncoder_WriteFloat()

bool FLEncoder_WriteFloat ( FLEncoder  ,
float   
)

Writes a 32-bit floating point number to an encoder.

Note
As an implementation detail, if the number has no fractional part and can be represented exactly as an integer, it'll be encoded as an integer to save space. This is transparent to the reader, since if it requests the value as a float it'll be returned as floating-point.

◆ FLEncoder_WriteInt()

bool FLEncoder_WriteInt ( FLEncoder  ,
int64_t   
)

Writes an integer to an encoder.

The parameter is typed as int64_t but you can pass any integral type (signed or unsigned) except for huge uint64_ts. The number will be written in a compact form that uses only as many bytes as necessary.

◆ FLEncoder_WriteKey()

bool FLEncoder_WriteKey ( FLEncoder  ,
FLString   
)

Specifies the key for the next value to be written to the current dictionary.

◆ FLEncoder_WriteKeyValue()

bool FLEncoder_WriteKeyValue ( FLEncoder  ,
FLValue   
)

Specifies the key for the next value to be written to the current dictionary.

The key is given as a Value, which must be a string or integer.

◆ FLEncoder_WriteNull()

bool FLEncoder_WriteNull ( FLEncoder  )

Writes a null value to an encoder.

(This is an explicitly-stored null, like the JSON null, not the "undefined" value represented by a NULL FLValue pointer.)

◆ FLEncoder_WriteRaw()

bool FLEncoder_WriteRaw ( FLEncoder  ,
FLSlice   
)

Writes raw data directly to the encoded output.

(This is not the same as FLEncoder_WriteData, which safely encodes a blob.)

Warning
Do not call this unless you really know what you're doing ... it's quite unsafe, and only used for certain advanced purposes.

◆ FLEncoder_WriteString()

bool FLEncoder_WriteString ( FLEncoder  ,
FLString   
)

Writes a string to an encoder.

The string must be UTF-8-encoded and must not contain any zero bytes.

Warning
Do not use this to write a dictionary key; use FLEncoder_WriteKey instead.

◆ FLEncoder_WriteUInt()

bool FLEncoder_WriteUInt ( FLEncoder  ,
uint64_t   
)

Writes an unsigned integer to an encoder.

Note
This function is only really necessary for huge 64-bit integers greater than or equal to 2^63, which can't be represented as int64_t.

◆ FLEncoder_WriteUndefined()

bool FLEncoder_WriteUndefined ( FLEncoder  )

Writes an undefined value to an encoder.

(Its value when read will not be a NULL pointer, but it can be recognized by FLValue_GetType returning kFLUndefined.)

Note
The only real use for writing undefined values is to represent "holes" in an array. An undefined dictionary value should be written simply by skipping the key and value.

◆ FLEncoder_WriteValue()

bool FLEncoder_WriteValue ( FLEncoder  ,
FLValue   
)

Writes a Fleece Value to an Encoder.

◆ FLEncoder_WriteValueAgain()

void FLEncoder_WriteValueAgain ( FLEncoder  e,
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.