Couchbase Lite C
Couchbase Lite C API
Data Structures | Functions | Variables
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. More...
 
FLEECE_PUBLIC bool FLArray_IsEmpty (FLArray FL_NULLABLE) FLPURE
 Returns true if an array is empty (or NULL). More...
 
FLEECE_PUBLIC FLMutableArray FL_NULLABLE FLArray_AsMutable (FLArray FL_NULLABLE) FLPURE
 If the array is mutable, returns it cast to FLMutableArray, else NULL. More...
 
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. More...
 

Variables

FLEECE_PUBLIC const FLArray kFLEmptyArray
 A constant empty array value. More...
 

Array iteration

Iterating an array typically looks like this:

FLArrayIterator_Begin(theArray, &iter);
FLValue value;
while (NULL != (value = FLArrayIterator_GetValue(&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 bool FLArrayIterator_Next(FLArrayIterator *)
Advances the iterator to the next value, or returns false if at the end.
const struct _FLValue * FLValue
A reference to a value of any type.
Definition: FLBase.h:35
Opaque array iterator.
Definition: FLCollections.h:73
FLEECE_PUBLIC void FLArrayIterator_Begin (FLArray FL_NULLABLE, FLArrayIterator *)
 Initializes a FLArrayIterator struct to iterate over an array. More...
 
FLEECE_PUBLIC FLValue FL_NULLABLE FLArrayIterator_GetValue (const FLArrayIterator *) FLPURE
 Returns the current value being iterated over. More...
 
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. More...
 
FLEECE_PUBLIC uint32_t FLArrayIterator_GetCount (const FLArrayIterator *) FLPURE
 Returns the number of items remaining to be iterated, including the current one. More...
 
FLEECE_PUBLIC 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.

Function Documentation

◆ FLArray_AsMutable()

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.