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.
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, or returns false if at the end.

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 FLArrayIteratorNext.

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.

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, or returns false if at the end.

Variable Documentation

kFLEmptyArray

FLEECE_PUBLIC const FLArray kFLEmptyArray

extern

A constant empty array value.