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

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

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.

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

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

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

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

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

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

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

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.