FLArray is a "subclass" of FLValue, representing values that are arrays. More...

Data Structures
struct	FLArrayIterator
	Opaque array iterator. More...

Functions
uint32_t	FLArray_Count (FLArray) FLPURE
	Returns the number of items in an array, or 0 if the pointer is NULL. More...

bool	FLArray_IsEmpty (FLArray) FLPURE
	Returns true if an array is empty (or NULL). More...

FLMutableArray	FLArray_AsMutable (FLArray) FLPURE
	If the array is mutable, returns it cast to FLMutableArray, else NULL. More...

FLValue	FLArray_Get (FLArray, uint32_t index) FLPURE
	Returns an value at an array index, or NULL if the index is out of range. More...

Variables
FLEECE_PUBLIC const FLArray	kFLEmptyArray

Mutable Arrays
enum	FLCopyFlags { kFLDefaultCopy = 0 , kFLDeepCopy = 1 , kFLCopyImmutables = 2 , kFLDeepCopyImmutables = (kFLDeepCopy \| kFLCopyImmutables) }

FLMutableArray	FLArray_MutableCopy (FLArray, FLCopyFlags)
	Creates a new mutable Array that's a copy of the source Array. More...

FLMutableArray	FLMutableArray_New (void)
	Creates a new empty mutable Array. More...

FLMutableArray	FLMutableArray_NewFromJSON (FLString json, FLError *outError)
	Creates a new mutable Array from JSON. More...

static FLMutableArray	FLMutableArray_Retain (FLMutableArray d)
	Increments the ref-count of a mutable Array. More...

static void	FLMutableArray_Release (FLMutableArray d)
	Decrements the refcount of (and possibly frees) a mutable Array. More...

FLArray	FLMutableArray_GetSource (FLMutableArray)
	If the Array was created by FLArray_MutableCopy, returns the original source Array. More...

bool	FLMutableArray_IsChanged (FLMutableArray)
	Returns true if the Array has been changed from the source it was copied from. More...

void	FLMutableArray_SetChanged (FLMutableArray, bool)
	Sets or clears the mutable Array's "changed" flag. More...

void	FLMutableArray_Insert (FLMutableArray array, uint32_t firstIndex, uint32_t count)
	Inserts a contiguous range of JSON `null` values into the array. More...

void	FLMutableArray_Remove (FLMutableArray array, uint32_t firstIndex, uint32_t count)
	Removes contiguous items from the array. More...

void	FLMutableArray_Resize (FLMutableArray array, uint32_t size)
	Changes the size of an array. More...

FLMutableArray	FLMutableArray_GetMutableArray (FLMutableArray, uint32_t index)
	Convenience function for getting an array-valued property in mutable form. More...

FLMutableDict	FLMutableArray_GetMutableDict (FLMutableArray, uint32_t index)
	Convenience function for getting an array-valued property in mutable form. More...

static void	FLMutableArray_SetNull (FLMutableArray, uint32_t index)
	Stores a JSON null value into an array. More...

static void	FLMutableArray_SetBool (FLMutableArray, uint32_t index, bool)
	Stores a boolean value into an array. More...

static void	FLMutableArray_SetInt (FLMutableArray, uint32_t index, int64_t)
	Stores an integer into an array. More...

static void	FLMutableArray_SetUInt (FLMutableArray, uint32_t index, uint64_t)
	Stores an unsigned integer into an array. More...

static void	FLMutableArray_SetFloat (FLMutableArray, uint32_t index, float)
	Stores a 32-bit floating-point number into an array. More...

static void	FLMutableArray_SetDouble (FLMutableArray, uint32_t index, double)
	Stores a 64-bit floating point number into an array. More...

static void	FLMutableArray_SetString (FLMutableArray, uint32_t index, FLString)
	Stores a UTF-8-encoded string into an array. More...

static void	FLMutableArray_SetData (FLMutableArray, uint32_t index, FLSlice)
	Stores a binary data blob into an array. More...

static void	FLMutableArray_SetValue (FLMutableArray, uint32_t index, FLValue)
	Stores a Fleece value into an array. More...

static void	FLMutableArray_SetArray (FLMutableArray, uint32_t index, FLArray)
	Stores a Fleece array into an array. More...

static void	FLMutableArray_SetDict (FLMutableArray, uint32_t index, FLDict)
	Stores a Fleece dictionary into an array. More...

static void	FLMutableArray_AppendNull (FLMutableArray)
	Appends a JSON null value to an array. More...

static void	FLMutableArray_AppendBool (FLMutableArray, bool)
	Appends a boolean value to an array. More...

static void	FLMutableArray_AppendInt (FLMutableArray, int64_t)
	Appends an integer to an array. More...

static void	FLMutableArray_AppendUInt (FLMutableArray, uint64_t)
	Appends an unsigned integer to an array. More...

static void	FLMutableArray_AppendFloat (FLMutableArray, float)
	Appends a 32-bit floating-point number to an array. More...

static void	FLMutableArray_AppendDouble (FLMutableArray, double)
	Appends a 64-bit floating point number to an array. More...

static void	FLMutableArray_AppendString (FLMutableArray, FLString)
	Appends a UTF-8-encoded string to an array. More...

static void	FLMutableArray_AppendData (FLMutableArray, FLSlice)
	Appends a binary data blob to an array. More...

static void	FLMutableArray_AppendValue (FLMutableArray, FLValue)
	Appends a Fleece value to an array. More...

static void	FLMutableArray_AppendArray (FLMutableArray, FLArray)
	Appends a Fleece array to an array. More...

static void	FLMutableArray_AppendDict (FLMutableArray, FLDict)
	Appends a Fleece dictionary to an array. More...

Array iteration
Iterating an array typically looks like this: FLArrayIterator iter; FLArrayIterator_Begin(theArray, &iter); FLValue value; while (NULL != (value = FLArrayIterator_GetValue(&iter))) { // ... FLArrayIterator_Next(&iter); } FLArrayIterator_Begin void FLArrayIterator_Begin(FLArray, FLArrayIterator ) Initializes a FLArrayIterator struct to iterate over an array. FLArrayIterator_Next bool FLArrayIterator_Next(FLArrayIterator ) Advances the iterator to the next value, or returns false if at the end. FLArrayIterator_GetValue FLValue FLArrayIterator_GetValue(const FLArrayIterator ) FLPURE Returns the current value being iterated over. FLValue const struct _FLValue FLValue A reference to a value of any type. Definition: Fleece.h:49 FLArrayIterator Opaque array iterator. Definition: Fleece.h:431
void	FLArrayIterator_Begin (FLArray, FLArrayIterator *)
	Initializes a FLArrayIterator struct to iterate over an array. More...

FLValue	FLArrayIterator_GetValue (const FLArrayIterator *) FLPURE
	Returns the current value being iterated over. More...

FLValue	FLArrayIterator_GetValueAt (const FLArrayIterator *, uint32_t offset) FLPURE
	Returns a value in the array at the given offset from the current value. More...

uint32_t	FLArrayIterator_GetCount (const FLArrayIterator *) FLPURE
	Returns the number of items remaining to be iterated, including the current one. More...

bool	FLArrayIterator_Next (FLArrayIterator *)
	Advances the iterator to the next value, or returns false if at the end. More...

Detailed Description

FLArray is a "subclass" of FLValue, representing values that are arrays.

It's always OK to pass an FLArray to a function parameter expecting an FLValue, even though the compiler makes you use an explicit type-cast. It's safe to type-cast the other direction, from FLValue to FLArray, only if you already know that the value is an array, e.g. by having called FLValue_GetType on it. But it's safer to call FLValue_AsArray instead, since it will return NULL if the value isn't an array.

Enumeration Type Documentation

◆ FLCopyFlags

enum FLCopyFlags

Enumerator
kFLDefaultCopy
kFLDeepCopy
kFLCopyImmutables
kFLDeepCopyImmutables

Function Documentation

◆ FLArray_AsMutable()

FLMutableArray FLArray_AsMutable ( FLArray )

If the array is mutable, returns it cast to FLMutableArray, else NULL.

◆ FLArray_Count()

uint32_t FLArray_Count ( FLArray )

Returns the number of items in an array, or 0 if the pointer is NULL.

◆ FLArray_Get()

FLValue FLArray_Get	(	FLArray	,
		uint32_t	index
	)

Returns an value at an array index, or NULL if the index is out of range.

◆ FLArray_IsEmpty()

bool FLArray_IsEmpty ( FLArray )

Returns true if an array is empty (or NULL).

Depending on the array's representation, this can be faster than FLArray_Count(a) == 0

◆ FLArray_MutableCopy()

FLMutableArray FLArray_MutableCopy	(	FLArray	,
		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 deepCopy is true, nested mutable Arrays and Dicts are also copied, recursively; if kFLCopyImmutables is also set, immutable values are also copied.

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

◆ FLArrayIterator_Begin()

void FLArrayIterator_Begin	(	FLArray	,
		FLArrayIterator *
	)

Initializes a FLArrayIterator struct to iterate over an array.

Call FLArrayIteratorGetValue to get the first item, then FLArrayIteratorNext.

◆ FLArrayIterator_GetCount()

uint32_t FLArrayIterator_GetCount ( const FLArrayIterator * )

Returns the number of items remaining to be iterated, including the current one.

◆ FLArrayIterator_GetValue()

FLValue FLArrayIterator_GetValue ( const FLArrayIterator * )

Returns the current value being iterated over.

◆ FLArrayIterator_GetValueAt()

FLValue FLArrayIterator_GetValueAt	(	const FLArrayIterator *	,
		uint32_t	offset
	)

Returns a value in the array at the given offset from the current value.

◆ FLArrayIterator_Next()

bool FLArrayIterator_Next ( FLArrayIterator * )

Advances the iterator to the next value, or returns false if at the end.

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

FLMutableArray FLMutableArray_GetMutableArray	(	FLMutableArray	,
		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()

FLMutableDict FLMutableArray_GetMutableDict	(	FLMutableArray	,
		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()

FLArray FLMutableArray_GetSource ( FLMutableArray )

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

◆ FLMutableArray_Insert()

void FLMutableArray_Insert	(	FLMutableArray	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()

bool FLMutableArray_IsChanged ( FLMutableArray )

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

◆ FLMutableArray_New()

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

FLMutableArray FLMutableArray_NewFromJSON	(	FLString	json,
		FLError *	outError
	)

Creates a new mutable Array from JSON.

The input json must represent a JSON array or NULL will be returned. Its initial ref-count is 1, so a call to FLMutableArray_Release will free it.

◆ FLMutableArray_Release()

static void FLMutableArray_Release ( FLMutableArray d )

inlinestatic

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

◆ FLMutableArray_Remove()

void FLMutableArray_Remove	(	FLMutableArray	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()

void FLMutableArray_Resize	(	FLMutableArray	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 FLMutableArray_Retain ( FLMutableArray 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()

void FLMutableArray_SetChanged	(	FLMutableArray	,
		bool
	)

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.

Variable Documentation

◆ kFLEmptyArray

FLEECE_PUBLIC const FLArray kFLEmptyArray

extern

Data Structures

Functions

Variables

Mutable Arrays

Array iteration

Detailed Description

Enumeration Type Documentation

◆ FLCopyFlags

Function Documentation

◆ FLArray_AsMutable()

◆ FLArray_Count()

◆ FLArray_Get()

◆ FLArray_IsEmpty()

◆ FLArray_MutableCopy()

◆ FLArrayIterator_Begin()

◆ FLArrayIterator_GetCount()

◆ FLArrayIterator_GetValue()

◆ FLArrayIterator_GetValueAt()

◆ FLArrayIterator_Next()

◆ FLMutableArray_AppendArray()

◆ FLMutableArray_AppendBool()

◆ FLMutableArray_AppendData()

◆ FLMutableArray_AppendDict()

◆ FLMutableArray_AppendDouble()

◆ FLMutableArray_AppendFloat()

◆ FLMutableArray_AppendInt()

◆ FLMutableArray_AppendNull()

◆ FLMutableArray_AppendString()

◆ FLMutableArray_AppendUInt()

◆ FLMutableArray_AppendValue()

◆ FLMutableArray_GetMutableArray()

◆ FLMutableArray_GetMutableDict()

◆ FLMutableArray_GetSource()

◆ FLMutableArray_Insert()

◆ FLMutableArray_IsChanged()

◆ FLMutableArray_New()

◆ FLMutableArray_NewFromJSON()

◆ FLMutableArray_Release()

◆ FLMutableArray_Remove()

◆ FLMutableArray_Resize()

◆ FLMutableArray_Retain()

◆ FLMutableArray_SetArray()

◆ FLMutableArray_SetBool()

◆ FLMutableArray_SetChanged()

◆ FLMutableArray_SetData()

◆ FLMutableArray_SetDict()

◆ FLMutableArray_SetDouble()

◆ FLMutableArray_SetFloat()

◆ FLMutableArray_SetInt()

◆ FLMutableArray_SetNull()

◆ FLMutableArray_SetString()

◆ FLMutableArray_SetUInt()

◆ FLMutableArray_SetValue()

Variable Documentation

◆ kFLEmptyArray