Mutable Values

Topics
	Value Slots
	An FLSlot is a temporary reference to an element of a mutable Array/Dict; its only purpose is to let you store a value into it, using the FLSlot_... functions.
	Fleece Formatted Value Builder
	These functions use the printf idiom to make it convenient to create structured Fleece values in memory with one call.

Enumerations
enum	FLCopyFlags { kFLDefaultCopy = 0 , kFLDeepCopy = 1 , kFLCopyImmutables = 2 , kFLDeepCopyImmutables = (kFLDeepCopy | kFLCopyImmutables) }
	Option flags for making mutable copies of values. More...

Mutable Arrays
NODISCARD FLEECE_PUBLIC FLMutableArray FL_NULLABLE	FLArray_MutableCopy (FLArray FL_NULLABLE, FLCopyFlags)
	Creates a new mutable Array that's a copy of the source Array.
NODISCARD FLEECE_PUBLIC FLMutableArray FL_NULLABLE	FLMutableArray_New (void)
	Creates a new empty mutable Array.
static FLMutableArray FL_NULLABLE	FLMutableArray_Retain (FLMutableArray FL_NULLABLE d)
	Increments the ref-count of a mutable Array.
static void	FLMutableArray_Release (FLMutableArray FL_NULLABLE d)
	Decrements the refcount of (and possibly frees) a mutable Array.
FLEECE_PUBLIC FLArray FL_NULLABLE	FLMutableArray_GetSource (FLMutableArray FL_NULLABLE)
	If the Array was created by FLArray_MutableCopy, returns the original source Array.
FLEECE_PUBLIC bool	FLMutableArray_IsChanged (FLMutableArray FL_NULLABLE)
	Returns true if the Array has been changed from the source it was copied from.
FLEECE_PUBLIC void	FLMutableArray_SetChanged (FLMutableArray FL_NULLABLE, bool changed)
	Sets or clears the mutable Array's "changed" flag.
FLEECE_PUBLIC void	FLMutableArray_Insert (FLMutableArray FL_NULLABLE array, uint32_t firstIndex, uint32_t count)
	Inserts a contiguous range of JSON null values into the array.
FLEECE_PUBLIC void	FLMutableArray_Remove (FLMutableArray FL_NULLABLE array, uint32_t firstIndex, uint32_t count)
	Removes contiguous items from the array.
FLEECE_PUBLIC void	FLMutableArray_Resize (FLMutableArray FL_NULLABLE array, uint32_t size)
	Changes the size of an array.
NODISCARD FLEECE_PUBLIC FLMutableArray FL_NULLABLE	FLMutableArray_GetMutableArray (FLMutableArray FL_NULLABLE, uint32_t index)
	Convenience function for getting an array-valued property in mutable form.
NODISCARD FLEECE_PUBLIC FLMutableDict FL_NULLABLE	FLMutableArray_GetMutableDict (FLMutableArray FL_NULLABLE, uint32_t index)
	Convenience function for getting an array-valued property in mutable form.
static void	FLMutableArray_SetNull (FLMutableArray, uint32_t index)
	Stores a JSON null value into an array.
static void	FLMutableArray_SetBool (FLMutableArray, uint32_t index, bool)
	Stores a boolean value into an array.
static void	FLMutableArray_SetInt (FLMutableArray, uint32_t index, int64_t)
	Stores an integer into an array.
static void	FLMutableArray_SetUInt (FLMutableArray, uint32_t index, uint64_t)
	Stores an unsigned integer into an array.
static void	FLMutableArray_SetFloat (FLMutableArray, uint32_t index, float)
	Stores a 32-bit floating-point number into an array.
static void	FLMutableArray_SetDouble (FLMutableArray, uint32_t index, double)
	Stores a 64-bit floating point number into an array.
static void	FLMutableArray_SetString (FLMutableArray, uint32_t index, FLString)
	Stores a UTF-8-encoded string into an array.
static void	FLMutableArray_SetData (FLMutableArray, uint32_t index, FLSlice)
	Stores a binary data blob into an array.
static void	FLMutableArray_SetValue (FLMutableArray, uint32_t index, FLValue)
	Stores a Fleece value into an array.
static void	FLMutableArray_SetArray (FLMutableArray, uint32_t index, FLArray)
	Stores a Fleece array into an array.
static void	FLMutableArray_SetDict (FLMutableArray, uint32_t index, FLDict)
	Stores a Fleece dictionary into an array.
static void	FLMutableArray_AppendNull (FLMutableArray)
	Appends a JSON null value to an array.
static void	FLMutableArray_AppendBool (FLMutableArray, bool)
	Appends a boolean value to an array.
static void	FLMutableArray_AppendInt (FLMutableArray, int64_t)
	Appends an integer to an array.
static void	FLMutableArray_AppendUInt (FLMutableArray, uint64_t)
	Appends an unsigned integer to an array.
static void	FLMutableArray_AppendFloat (FLMutableArray, float)
	Appends a 32-bit floating-point number to an array.
static void	FLMutableArray_AppendDouble (FLMutableArray, double)
	Appends a 64-bit floating point number to an array.
static void	FLMutableArray_AppendString (FLMutableArray, FLString)
	Appends a UTF-8-encoded string to an array.
static void	FLMutableArray_AppendData (FLMutableArray, FLSlice)
	Appends a binary data blob to an array.
static void	FLMutableArray_AppendValue (FLMutableArray, FLValue)
	Appends a Fleece value to an array.
static void	FLMutableArray_AppendArray (FLMutableArray, FLArray)
	Appends a Fleece array to an array.
static void	FLMutableArray_AppendDict (FLMutableArray, FLDict)
	Appends a Fleece dictionary to an array.

Mutable dictionaries
FLEECE_PUBLIC FLMutableDict FL_NULLABLE	FLDict_MutableCopy (FLDict FL_NULLABLE source, FLCopyFlags)
	Creates a new mutable Dict that's a copy of the source Dict.
FLEECE_PUBLIC FLMutableDict FL_NULLABLE	FLMutableDict_New (void)
	Creates a new empty mutable Dict.
static FLMutableDict FL_NULLABLE	FLMutableDict_Retain (FLMutableDict FL_NULLABLE d)
	Increments the ref-count of a mutable Dict.
static void	FLMutableDict_Release (FLMutableDict FL_NULLABLE d)
	Decrements the refcount of (and possibly frees) a mutable Dict.
FLEECE_PUBLIC FLDict FL_NULLABLE	FLMutableDict_GetSource (FLMutableDict FL_NULLABLE)
	If the Dict was created by FLDict_MutableCopy, returns the original source Dict.
FLEECE_PUBLIC bool	FLMutableDict_IsChanged (FLMutableDict FL_NULLABLE)
	Returns true if the Dict has been changed from the source it was copied from.
FLEECE_PUBLIC void	FLMutableDict_SetChanged (FLMutableDict FL_NULLABLE, bool)
	Sets or clears the mutable Dict's "changed" flag.
FLEECE_PUBLIC void	FLMutableDict_Remove (FLMutableDict FL_NULLABLE, FLString key)
	Removes the value for a key.
FLEECE_PUBLIC void	FLMutableDict_RemoveAll (FLMutableDict FL_NULLABLE)
	Removes all keys and values.
FLEECE_PUBLIC FLMutableArray FL_NULLABLE	FLMutableDict_GetMutableArray (FLMutableDict FL_NULLABLE, FLString key)
	Convenience function for getting an array-valued property in mutable form.
FLEECE_PUBLIC FLMutableDict FL_NULLABLE	FLMutableDict_GetMutableDict (FLMutableDict FL_NULLABLE, FLString key)
	Convenience function for getting a dict-valued property in mutable form.
static void	FLMutableDict_SetNull (FLMutableDict, FLString key)
	Stores a JSON null value into a mutable dictionary.
static void	FLMutableDict_SetBool (FLMutableDict, FLString key, bool)
	Stores a boolean value into a mutable dictionary.
static void	FLMutableDict_SetInt (FLMutableDict, FLString key, int64_t)
	Stores an integer into a mutable dictionary.
static void	FLMutableDict_SetUInt (FLMutableDict, FLString key, uint64_t)
	Stores an unsigned integer into a mutable dictionary.
static void	FLMutableDict_SetFloat (FLMutableDict, FLString key, float)
	Stores a 32-bit floating-point number into a mutable dictionary.
static void	FLMutableDict_SetDouble (FLMutableDict, FLString key, double)
	Stores a 64-bit floating point number into a mutable dictionary.
static void	FLMutableDict_SetString (FLMutableDict, FLString key, FLString)
	Stores a UTF-8-encoded string into a mutable dictionary.
static void	FLMutableDict_SetData (FLMutableDict, FLString key, FLSlice)
	Stores a binary data blob into a mutable dictionary.
static void	FLMutableDict_SetValue (FLMutableDict, FLString key, FLValue)
	Stores a Fleece value into a mutable dictionary.
static void	FLMutableDict_SetArray (FLMutableDict, FLString key, FLArray)
	Stores a Fleece array into a mutable dictionary.
static void	FLMutableDict_SetDict (FLMutableDict, FLString key, FLDict)
	Stores a Fleece dictionary into a mutable dictionary.

Creating string and data values
FLEECE_PUBLIC FLValue FL_NULLABLE	FLValue_NewString (FLString)
	Allocates a string value on the heap.
FLEECE_PUBLIC FLValue FL_NULLABLE	FLValue_NewData (FLSlice)
	Allocates a data/blob value on the heap.

Detailed Description

Enumeration Type Documentation

FLCopyFlags

enum FLCopyFlags

Option flags for making mutable copies of values.

Enumerator
kFLDefaultCopy	Shallow copy. References immutables instead of copying.
kFLDeepCopy	Deep copy of mutable values.
kFLCopyImmutables	Makes mutable copies of immutables instead of just refs.
kFLDeepCopyImmutables	Both deep-copy and copy-immutables.

Function Documentation

FLArray_MutableCopy()

NODISCARD FLEECE_PUBLIC FLMutableArray FL_NULLABLE FLArray_MutableCopy	(	FLArray	FL_NULLABLE,
		FLCopyFlags	)

Creates a new mutable Array that's a copy of the source Array.

Its initial ref-count is 1, so a call to FLMutableArray_Release will free it.

Copying an immutable Array is very cheap (only one small allocation) unless the flag kFLCopyImmutables is set.

Copying a mutable Array is cheap if it's a shallow copy; but if kFLDeepCopy is set, nested mutable Arrays and Dicts are also copied, recursively; if kFLCopyImmutables is also set, immutable values are also copied, recursively.

If the source Array is NULL, then NULL is returned.

FLDict_MutableCopy()

FLEECE_PUBLIC FLMutableDict FL_NULLABLE FLDict_MutableCopy	(	FLDict FL_NULLABLE	source,
		FLCopyFlags	)

Creates a new mutable Dict that's a copy of the source Dict.

Its initial ref-count is 1, so a call to FLMutableDict_Release will free it.

Copying an immutable Dict is very cheap (only one small allocation.) The deepCopy flag is ignored.

Copying a mutable Dict is cheap if it's a shallow copy, but if deepCopy is true, nested mutable Dicts and Arrays are also copied, recursively.

If the source dict is NULL, then NULL is returned.

FLMutableArray_AppendArray()

static void FLMutableArray_AppendArray ( FLMutableArray a, FLArray val )

inlinestatic

Appends a Fleece array to an array.

FLMutableArray_AppendBool()

static void FLMutableArray_AppendBool ( FLMutableArray a, bool val )

inlinestatic

Appends a boolean value to an array.

FLMutableArray_AppendData()

static void FLMutableArray_AppendData ( FLMutableArray a, FLSlice val )

inlinestatic

Appends a binary data blob to an array.

FLMutableArray_AppendDict()

static void FLMutableArray_AppendDict ( FLMutableArray a, FLDict val )

inlinestatic

Appends a Fleece dictionary to an array.

FLMutableArray_AppendDouble()

static void FLMutableArray_AppendDouble ( FLMutableArray a, double val )

inlinestatic

Appends a 64-bit floating point number to an array.

FLMutableArray_AppendFloat()

static void FLMutableArray_AppendFloat ( FLMutableArray a, float val )

inlinestatic

Appends a 32-bit floating-point number to an array.

FLMutableArray_AppendInt()

static void FLMutableArray_AppendInt ( FLMutableArray a, int64_t val )

inlinestatic

Appends an integer to an array.

FLMutableArray_AppendNull()

static void FLMutableArray_AppendNull ( FLMutableArray a )

inlinestatic

Appends a JSON null value to an array.

FLMutableArray_AppendString()

static void FLMutableArray_AppendString ( FLMutableArray a, FLString val )

inlinestatic

Appends a UTF-8-encoded string to an array.

FLMutableArray_AppendUInt()

static void FLMutableArray_AppendUInt ( FLMutableArray a, uint64_t val )

inlinestatic

Appends an unsigned integer to an array.

Note

: The only time this needs to be called, instead of FLMutableArray_AppendInt, is if the value is greater than or equal to 2^63 and won't fit in an int64_t.

FLMutableArray_AppendValue()

static void FLMutableArray_AppendValue ( FLMutableArray a, FLValue val )

inlinestatic

Appends a Fleece value to an array.

FLMutableArray_GetMutableArray()

NODISCARD FLEECE_PUBLIC FLMutableArray FL_NULLABLE FLMutableArray_GetMutableArray	(	FLMutableArray	FL_NULLABLE,
		uint32_t	index )

Convenience function for getting an array-valued property in mutable form.

• If the value for the key is not an array, returns NULL.
• If the value is a mutable array, returns it.
• If the value is an immutable array, this function makes a mutable copy, assigns the copy as the property value, and returns the copy.

FLMutableArray_GetMutableDict()

NODISCARD FLEECE_PUBLIC FLMutableDict FL_NULLABLE FLMutableArray_GetMutableDict	(	FLMutableArray	FL_NULLABLE,
		uint32_t	index )

Convenience function for getting an array-valued property in mutable form.

• If the value for the key is not an array, returns NULL.
• If the value is a mutable array, returns it.
• If the value is an immutable array, this function makes a mutable copy, assigns the copy as the property value, and returns the copy.

FLMutableArray_GetSource()

FLEECE_PUBLIC FLArray FL_NULLABLE FLMutableArray_GetSource

(

FLMutableArray

FL_NULLABLE

)

If the Array was created by FLArray_MutableCopy, returns the original source Array.

FLMutableArray_Insert()

FLEECE_PUBLIC void FLMutableArray_Insert	(	FLMutableArray FL_NULLABLE	array,
		uint32_t	firstIndex,
		uint32_t	count )

Inserts a contiguous range of JSON null values into the array.

Parameters

array	The array to operate on.
firstIndex	The zero-based index of the first value to be inserted.
count	The number of items to insert.

FLMutableArray_IsChanged()

FLEECE_PUBLIC bool FLMutableArray_IsChanged

(

FLMutableArray

FL_NULLABLE

)

Returns true if the Array has been changed from the source it was copied from.

FLMutableArray_New()

NODISCARD FLEECE_PUBLIC FLMutableArray FL_NULLABLE FLMutableArray_New

(

void

)

Creates a new empty mutable Array.

Its initial ref-count is 1, so a call to FLMutableArray_Release will free it.

FLMutableArray_Release()

static void FLMutableArray_Release ( FLMutableArray FL_NULLABLE d )

inlinestatic

Decrements the refcount of (and possibly frees) a mutable Array.

FLMutableArray_Remove()

FLEECE_PUBLIC void FLMutableArray_Remove	(	FLMutableArray FL_NULLABLE	array,
		uint32_t	firstIndex,
		uint32_t	count )

Removes contiguous items from the array.

Parameters

array	The array to operate on.
firstIndex	The zero-based index of the first item to remove.
count	The number of items to remove.

FLMutableArray_Resize()

FLEECE_PUBLIC void FLMutableArray_Resize	(	FLMutableArray FL_NULLABLE	array,
		uint32_t	size )

Changes the size of an array.

If the new size is larger, the array is padded with JSON null values. If it's smaller, values are removed from the end.

FLMutableArray_Retain()

static FLMutableArray FL_NULLABLE FLMutableArray_Retain ( FLMutableArray FL_NULLABLE d )

inlinestatic

Increments the ref-count of a mutable Array.

FLMutableArray_SetArray()

static void FLMutableArray_SetArray ( FLMutableArray a, uint32_t index, FLArray val )

inlinestatic

Stores a Fleece array into an array.

FLMutableArray_SetBool()

static void FLMutableArray_SetBool ( FLMutableArray a, uint32_t index, bool val )

inlinestatic

Stores a boolean value into an array.

FLMutableArray_SetChanged()

FLEECE_PUBLIC void FLMutableArray_SetChanged	(	FLMutableArray	FL_NULLABLE,
		bool	changed )

Sets or clears the mutable Array's "changed" flag.

FLMutableArray_SetData()

static void FLMutableArray_SetData ( FLMutableArray a, uint32_t index, FLSlice val )

inlinestatic

Stores a binary data blob into an array.

FLMutableArray_SetDict()

static void FLMutableArray_SetDict ( FLMutableArray a, uint32_t index, FLDict val )

inlinestatic

Stores a Fleece dictionary into an array.

FLMutableArray_SetDouble()

static void FLMutableArray_SetDouble ( FLMutableArray a, uint32_t index, double val )

inlinestatic

Stores a 64-bit floating point number into an array.

FLMutableArray_SetFloat()

static void FLMutableArray_SetFloat ( FLMutableArray a, uint32_t index, float val )

inlinestatic

Stores a 32-bit floating-point number into an array.

FLMutableArray_SetInt()

static void FLMutableArray_SetInt ( FLMutableArray a, uint32_t index, int64_t val )

inlinestatic

Stores an integer into an array.

FLMutableArray_SetNull()

static void FLMutableArray_SetNull ( FLMutableArray a, uint32_t index )

inlinestatic

Stores a JSON null value into an array.

FLMutableArray_SetString()

static void FLMutableArray_SetString ( FLMutableArray a, uint32_t index, FLString val )

inlinestatic

Stores a UTF-8-encoded string into an array.

FLMutableArray_SetUInt()

static void FLMutableArray_SetUInt ( FLMutableArray a, uint32_t index, uint64_t val )

inlinestatic

Stores an unsigned integer into an array.

Note

: The only time this needs to be called, instead of FLMutableArray_SetInt, is if the value is greater than or equal to 2^63 and won't fit in an int64_t.

FLMutableArray_SetValue()

static void FLMutableArray_SetValue ( FLMutableArray a, uint32_t index, FLValue val )

inlinestatic

Stores a Fleece value into an array.

FLMutableDict_GetMutableArray()

FLEECE_PUBLIC FLMutableArray FL_NULLABLE FLMutableDict_GetMutableArray	(	FLMutableDict	FL_NULLABLE,
		FLString	key )

Convenience function for getting an array-valued property in mutable form.

• If the value for the key is not an array, returns NULL.
• If the value is a mutable array, returns it.
• If the value is an immutable array, this function makes a mutable copy, assigns the copy as the property value, and returns the copy.

FLMutableDict_GetMutableDict()

FLEECE_PUBLIC FLMutableDict FL_NULLABLE FLMutableDict_GetMutableDict	(	FLMutableDict	FL_NULLABLE,
		FLString	key )

Convenience function for getting a dict-valued property in mutable form.

• If the value for the key is not a dict, returns NULL.
• If the value is a mutable dict, returns it.
• If the value is an immutable dict, this function makes a mutable copy, assigns the copy as the property value, and returns the copy.

FLMutableDict_GetSource()

FLEECE_PUBLIC FLDict FL_NULLABLE FLMutableDict_GetSource

(

FLMutableDict

FL_NULLABLE

)

If the Dict was created by FLDict_MutableCopy, returns the original source Dict.

FLMutableDict_IsChanged()

FLEECE_PUBLIC bool FLMutableDict_IsChanged

(

FLMutableDict

FL_NULLABLE

)

Returns true if the Dict has been changed from the source it was copied from.

FLMutableDict_New()

FLEECE_PUBLIC FLMutableDict FL_NULLABLE FLMutableDict_New

(

void

)

Creates a new empty mutable Dict.

Its initial ref-count is 1, so a call to FLMutableDict_Release will free it.

FLMutableDict_Release()

static void FLMutableDict_Release ( FLMutableDict FL_NULLABLE d )

inlinestatic

Decrements the refcount of (and possibly frees) a mutable Dict.

FLMutableDict_Remove()

FLEECE_PUBLIC void FLMutableDict_Remove	(	FLMutableDict	FL_NULLABLE,
		FLString	key )

Removes the value for a key.

FLMutableDict_RemoveAll()

FLEECE_PUBLIC void FLMutableDict_RemoveAll

(

FLMutableDict

FL_NULLABLE

)

Removes all keys and values.

FLMutableDict_Retain()

static FLMutableDict FL_NULLABLE FLMutableDict_Retain ( FLMutableDict FL_NULLABLE d )

inlinestatic

Increments the ref-count of a mutable Dict.

FLMutableDict_SetArray()

static void FLMutableDict_SetArray ( FLMutableDict d, FLString key, FLArray val )

inlinestatic

Stores a Fleece array into a mutable dictionary.

FLMutableDict_SetBool()

static void FLMutableDict_SetBool ( FLMutableDict d, FLString key, bool val )

inlinestatic

Stores a boolean value into a mutable dictionary.

FLMutableDict_SetChanged()

FLEECE_PUBLIC void FLMutableDict_SetChanged	(	FLMutableDict	FL_NULLABLE,
		bool	)

Sets or clears the mutable Dict's "changed" flag.

FLMutableDict_SetData()

static void FLMutableDict_SetData ( FLMutableDict d, FLString key, FLSlice val )

inlinestatic

Stores a binary data blob into a mutable dictionary.

FLMutableDict_SetDict()

static void FLMutableDict_SetDict ( FLMutableDict d, FLString key, FLDict val )

inlinestatic

Stores a Fleece dictionary into a mutable dictionary.

FLMutableDict_SetDouble()

static void FLMutableDict_SetDouble ( FLMutableDict d, FLString key, double val )

inlinestatic

Stores a 64-bit floating point number into a mutable dictionary.

FLMutableDict_SetFloat()

static void FLMutableDict_SetFloat ( FLMutableDict d, FLString key, float val )

inlinestatic

Stores a 32-bit floating-point number into a mutable dictionary.

FLMutableDict_SetInt()

static void FLMutableDict_SetInt ( FLMutableDict d, FLString key, int64_t val )

inlinestatic

Stores an integer into a mutable dictionary.

FLMutableDict_SetNull()

static void FLMutableDict_SetNull ( FLMutableDict d, FLString key )

inlinestatic

Stores a JSON null value into a mutable dictionary.

FLMutableDict_SetString()

static void FLMutableDict_SetString ( FLMutableDict d, FLString key, FLString val )

inlinestatic

Stores a UTF-8-encoded string into a mutable dictionary.

FLMutableDict_SetUInt()

static void FLMutableDict_SetUInt ( FLMutableDict d, FLString key, uint64_t val )

inlinestatic

Stores an unsigned integer into a mutable dictionary.

Note

: The only time this needs to be called, instead of FLMutableDict_SetInt, is if the value is greater than or equal to 2^63 and won't fit in an int64_t.

FLMutableDict_SetValue()

static void FLMutableDict_SetValue ( FLMutableDict d, FLString key, FLValue val )

inlinestatic

Stores a Fleece value into a mutable dictionary.

FLValue_NewData()

FLEECE_PUBLIC FLValue FL_NULLABLE FLValue_NewData

(

FLSlice

)

Allocates a data/blob value on the heap.

This is rarely needed – usually you'd just add data to a mutable Array or Dict directly using one of their "...SetData or "...AppendData" methods.

FLValue_NewString()

FLEECE_PUBLIC FLValue FL_NULLABLE FLValue_NewString

(

FLString

)

Allocates a string value on the heap.

This is rarely needed – usually you'd just add a string to a mutable Array or Dict directly using one of their "...SetString" or "...AppendString" methods.