Fleece Arrays

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

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

Functions
FLEECE_PUBLIC uint32_t	FLArray_Count (FLArray FL_NULLABLE) FLPURE
	Returns the number of items in an array, or 0 if the pointer is NULL.
FLEECE_PUBLIC bool	FLArray_IsEmpty (FLArray FL_NULLABLE) FLPURE
	Returns true if an array is empty (or NULL).
NODISCARD FLEECE_PUBLIC FLMutableArray FL_NULLABLE	FLArray_AsMutable (FLArray FL_NULLABLE) FLPURE
	If the array is mutable, returns it cast to FLMutableArray, else NULL.
FLEECE_PUBLIC FLValue FL_NULLABLE	FLArray_Get (FLArray FL_NULLABLE, uint32_t index) FLPURE
	Returns an value at an array index, or NULL if the index is out of range.

Variables
FLEECE_PUBLIC const FLArray	kFLEmptyArray
	A constant empty array value.

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); }
FLEECE_PUBLIC void	FLArrayIterator_Begin (FLArray FL_NULLABLE, FLArrayIterator *)
	Initializes a FLArrayIterator struct to iterate over an array.
FLEECE_PUBLIC FLValue FL_NULLABLE	FLArrayIterator_GetValue (const FLArrayIterator *) FLPURE
	Returns the current value being iterated over, or NULL at the end.
FLEECE_PUBLIC FLValue FL_NULLABLE	FLArrayIterator_GetValueAt (const FLArrayIterator *, uint32_t offset) FLPURE
	Returns a value in the array at the given offset from the current value.
FLEECE_PUBLIC uint32_t	FLArrayIterator_GetCount (const FLArrayIterator *) FLPURE
	Returns the number of items remaining to be iterated, including the current one.
FLEECE_PUBLIC bool	FLArrayIterator_Next (FLArrayIterator *)
	Advances the iterator to the next value.

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.

Function Documentation

FLArray_AsMutable()

NODISCARD FLEECE_PUBLIC FLMutableArray FL_NULLABLE FLArray_AsMutable

(

FLArray

FL_NULLABLE

)

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

FLArray_Count()

FLEECE_PUBLIC uint32_t FLArray_Count

(

FLArray

FL_NULLABLE

)

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

FLArray_Get()

FLEECE_PUBLIC FLValue FL_NULLABLE FLArray_Get	(	FLArray	FL_NULLABLE,
		uint32_t	index )

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

FLArray_IsEmpty()

FLEECE_PUBLIC bool FLArray_IsEmpty

(

FLArray

FL_NULLABLE

)

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

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

FLArrayIterator_Begin()

FLEECE_PUBLIC void FLArrayIterator_Begin	(	FLArray	FL_NULLABLE,
		FLArrayIterator *	)

Initializes a FLArrayIterator struct to iterate over an array.

Call FLArrayIteratorGetValue to get the first item, then as long as the item is not NULL, call FLArrayIterator_Next to advance.

FLArrayIterator_GetCount()

FLEECE_PUBLIC uint32_t FLArrayIterator_GetCount

(

const FLArrayIterator *

)

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

FLArrayIterator_GetValue()

FLEECE_PUBLIC FLValue FL_NULLABLE FLArrayIterator_GetValue

(

const FLArrayIterator *

)

Returns the current value being iterated over, or NULL at the end.

FLArrayIterator_GetValueAt()

FLEECE_PUBLIC FLValue FL_NULLABLE FLArrayIterator_GetValueAt	(	const FLArrayIterator *	,
		uint32_t	offset )

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

FLArrayIterator_Next()

FLEECE_PUBLIC bool FLArrayIterator_Next

(

FLArrayIterator *

)

Advances the iterator to the next value.

Warning

It is illegal to call this when the iterator is already at the end. In particular, calling this when the array is empty is always illegal.

Variable Documentation

kFLEmptyArray

FLEECE_PUBLIC const FLArray kFLEmptyArray

extern

A constant empty array value.