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...
 
NODISCARD FLEECE_PUBLIC FLEncoder FLEncoder_New (void)
 Creates a new encoder, for generating Fleece data. More...
 
NODISCARD FLEECE_PUBLIC FLEncoder FLEncoder_NewWithOptions (FLEncoderFormat format, size_t reserveSize, bool uniqueStrings)
 Creates a new encoder, allowing some options to be customized. More...
 
NODISCARD FLEECE_PUBLIC FLEncoder FLEncoder_NewWritingToFile (FILE *, bool uniqueStrings)
 Creates a new Fleece encoder that writes to a file, not to memory. More...
 
FLEECE_PUBLIC void FLEncoder_Free (FLEncoder FL_NULLABLE)
 Frees the space used by an encoder. More...
 
FLEECE_PUBLIC void FLEncoder_SetSharedKeys (FLEncoder, FLSharedKeys FL_NULLABLE)
 Tells the encoder to use a shared-keys mapping when encoding dictionary keys. More...
 
FLEECE_PUBLIC void FLEncoder_SetExtraInfo (FLEncoder, void *FL_NULLABLE info)
 Associates an arbitrary user-defined value with the encoder. More...
 
FLEECE_PUBLIC void * FLEncoder_GetExtraInfo (FLEncoder)
 Returns the user-defined value associated with the encoder; NULL by default. More...
 
FLEECE_PUBLIC void FLEncoder_Reset (FLEncoder)
 Resets the state of an encoder without freeing it. More...
 
FLEECE_PUBLIC size_t FLEncoder_BytesWritten (FLEncoder)
 Returns the number of bytes encoded so far. 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.

FLEECE_PUBLIC bool FLEncoder_WriteNull (FLEncoder)
 Writes a null value to an encoder. More...
 
FLEECE_PUBLIC bool FLEncoder_WriteUndefined (FLEncoder)
 Writes an undefined value to an encoder. More...
 
FLEECE_PUBLIC bool FLEncoder_WriteBool (FLEncoder, bool)
 Writes a boolean value (true or false) to an encoder. More...
 
FLEECE_PUBLIC bool FLEncoder_WriteInt (FLEncoder, int64_t)
 Writes an integer to an encoder. More...
 
FLEECE_PUBLIC bool FLEncoder_WriteUInt (FLEncoder, uint64_t)
 Writes an unsigned integer to an encoder. More...
 
FLEECE_PUBLIC bool FLEncoder_WriteFloat (FLEncoder, float)
 Writes a 32-bit floating point number to an encoder. More...
 
FLEECE_PUBLIC bool FLEncoder_WriteDouble (FLEncoder, double)
 Writes a 64-bit floating point number to an encoder. More...
 
FLEECE_PUBLIC bool FLEncoder_WriteString (FLEncoder, FLString)
 Writes a string to an encoder. More...
 
FLEECE_PUBLIC bool FLEncoder_WriteDateString (FLEncoder encoder, FLTimestamp ts, bool asUTC)
 Writes a timestamp to an encoder, as an ISO-8601 date string. More...
 
FLEECE_PUBLIC bool FLEncoder_WriteData (FLEncoder, FLSlice)
 Writes a binary data value (a blob) to an encoder. More...
 
FLEECE_PUBLIC bool FLEncoder_WriteValue (FLEncoder, FLValue)
 Writes a Fleece Value to an Encoder. More...
 
FLEECE_PUBLIC bool FLEncoder_BeginArray (FLEncoder, size_t reserveCount)
 Begins writing an array value to an encoder. More...
 
FLEECE_PUBLIC bool FLEncoder_EndArray (FLEncoder)
 Ends writing an array value; pops back the previous encoding state. More...
 
FLEECE_PUBLIC bool FLEncoder_BeginDict (FLEncoder, size_t reserveCount)
 Begins writing a dictionary value to an encoder. More...
 
FLEECE_PUBLIC bool FLEncoder_WriteKey (FLEncoder, FLString)
 Specifies the key for the next value to be written to the current dictionary. More...
 
FLEECE_PUBLIC bool FLEncoder_WriteKeyValue (FLEncoder, FLValue)
 Specifies the key for the next value to be written to the current dictionary. More...
 
FLEECE_PUBLIC bool FLEncoder_EndDict (FLEncoder)
 Ends writing a dictionary value; pops back the previous encoding state. More...
 
FLEECE_PUBLIC bool FLEncoder_WriteRaw (FLEncoder, FLSlice)
 Writes raw data directly to the encoded output. More...
 

Finishing up

NODISCARD FLEECE_PUBLIC FLDoc FL_NULLABLE FLEncoder_FinishDoc (FLEncoder, FLError *FL_NULLABLE outError)
 Ends encoding; if there has been no error, it returns the encoded Fleece data packaged in an FLDoc. More...
 
NODISCARD FLEECE_PUBLIC FLSliceResult FLEncoder_Finish (FLEncoder, FLError *FL_NULLABLE outError)
 Ends encoding; if there has been no error, it returns the encoded data, else null. More...
 

Error handling

FLEECE_PUBLIC FLError FLEncoder_GetError (FLEncoder)
 Returns the error code of an encoder, or NoError (0) if there's no error. More...
 
FLEECE_PUBLIC const char *FL_NULLABLE 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_BeginArray()

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

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

FLEECE_PUBLIC size_t FLEncoder_BytesWritten ( FLEncoder  )

Returns the number of bytes encoded so far.

◆ FLEncoder_EndArray()

FLEECE_PUBLIC bool FLEncoder_EndArray ( FLEncoder  )

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

◆ FLEncoder_EndDict()

FLEECE_PUBLIC bool FLEncoder_EndDict ( FLEncoder  )

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

◆ FLEncoder_Finish()

NODISCARD FLEECE_PUBLIC FLSliceResult FLEncoder_Finish ( FLEncoder  ,
FLError *FL_NULLABLE  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()

NODISCARD FLEECE_PUBLIC FLDoc FL_NULLABLE FLEncoder_FinishDoc ( FLEncoder  ,
FLError *FL_NULLABLE  outError 
)

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

FLEECE_PUBLIC void FLEncoder_Free ( FLEncoder  FL_NULLABLE)

Frees the space used by an encoder.

◆ FLEncoder_GetError()

FLEECE_PUBLIC FLError FLEncoder_GetError ( FLEncoder  )

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

◆ FLEncoder_GetErrorMessage()

FLEECE_PUBLIC const char *FL_NULLABLE FLEncoder_GetErrorMessage ( FLEncoder  )

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

◆ FLEncoder_GetExtraInfo()

FLEECE_PUBLIC void * FLEncoder_GetExtraInfo ( FLEncoder  )

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

◆ FLEncoder_New()

NODISCARD FLEECE_PUBLIC FLEncoder FLEncoder_New ( void  )

Creates a new encoder, for generating Fleece data.

Call FLEncoder_Free when done.

◆ FLEncoder_NewWithOptions()

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

NODISCARD FLEECE_PUBLIC FLEncoder FLEncoder_NewWritingToFile ( FILE *  ,
bool  uniqueStrings 
)

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

◆ FLEncoder_Reset()

FLEECE_PUBLIC void FLEncoder_Reset ( FLEncoder  )

Resets the state of an encoder without freeing it.

It can then be reused to encode another value.

◆ FLEncoder_SetExtraInfo()

FLEECE_PUBLIC void FLEncoder_SetExtraInfo ( FLEncoder  ,
void *FL_NULLABLE  info 
)

Associates an arbitrary user-defined value with the encoder.

◆ FLEncoder_SetSharedKeys()

FLEECE_PUBLIC void FLEncoder_SetSharedKeys ( FLEncoder  ,
FLSharedKeys  FL_NULLABLE 
)

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

◆ FLEncoder_WriteBool()

FLEECE_PUBLIC bool FLEncoder_WriteBool ( FLEncoder  ,
bool   
)

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

◆ FLEncoder_WriteData()

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

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

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

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

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

FLEECE_PUBLIC bool FLEncoder_WriteKey ( FLEncoder  ,
FLString   
)

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

◆ FLEncoder_WriteKeyValue()

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

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

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

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

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

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

FLEECE_PUBLIC bool FLEncoder_WriteValue ( FLEncoder  ,
FLValue   
)

Writes a Fleece Value to an Encoder.