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

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_Begin(theArray, &iter);
FLValue value;
while (NULL != (value = FLArrayIterator_GetValue(&iter))) {
// ...
}
void FLArrayIterator_Begin(FLArray, FLArrayIterator *)
Initializes a FLArrayIterator struct to iterate over an array.
bool FLArrayIterator_Next(FLArrayIterator *)
Advances the iterator to the next value, or returns false if at the end.
FLValue FLArrayIterator_GetValue(const FLArrayIterator *) FLPURE
Returns the current value being iterated over.
const struct _FLValue * FLValue
A reference to a value of any type.
Definition: Fleece.h:49
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

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
arrayThe array to operate on.
firstIndexThe zero-based index of the first value to be inserted.
countThe 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
arrayThe array to operate on.
firstIndexThe zero-based index of the first item to remove.
countThe 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