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...
FLEECE_PUBLIC FLEncoder	FLEncoder_New (void)
	Creates a new encoder, for generating Fleece data. More...
FLEECE_PUBLIC FLEncoder	FLEncoder_NewWithOptions (FLEncoderFormat format, size_t reserveSize, bool uniqueStrings)
	Creates a new encoder, allowing some options to be customized. More...
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
MUST_USE_RESULT 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...
MUST_USE_RESULT 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

enum 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

reserveCount

Number 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

reserveCount

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

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

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

FLEECE_PUBLIC FLEncoder FLEncoder_New

(

void

)

Creates a new encoder, for generating Fleece data.

Call FLEncoder_Free when done.

FLEncoder_NewWithOptions()

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

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

Parameters

format	The output format to generate (Fleece, JSON, or JSON5.)
reserveSize	The 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()

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

encoder	The encoder to write to.
ts	The timestamp (milliseconds since Unix epoch 1-1-1970).
asUTC	If 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.