Couchbase Lite C
Couchbase Lite C API
Data Structures | Functions | Variables
Fleece Dictionaries

Data Structures

struct  FLDictIterator
 Opaque dictionary iterator. More...
 
struct  FLDictKey
 Opaque key for a dictionary. More...
 

Functions

FLEECE_PUBLIC uint32_t FLDict_Count (FLDict FL_NULLABLE) FLPURE
 Returns the number of items in a dictionary, or 0 if the pointer is NULL. More...
 
FLEECE_PUBLIC bool FLDict_IsEmpty (FLDict FL_NULLABLE) FLPURE
 Returns true if a dictionary is empty (or NULL). More...
 
FLEECE_PUBLIC FLMutableDict FL_NULLABLE FLDict_AsMutable (FLDict FL_NULLABLE) FLPURE
 If the dictionary is mutable, returns it cast to FLMutableDict, else NULL. More...
 
FLEECE_PUBLIC FLValue FL_NULLABLE FLDict_Get (FLDict FL_NULLABLE, FLSlice keyString) FLPURE
 Looks up a key in a dictionary, returning its value. More...
 

Variables

FLEECE_PUBLIC const FLDict kFLEmptyDict
 A constant empty array value. More...
 

Dict iteration

Iterating a dictionary typically looks like this:

FLDictIterator_Begin(theDict, &iter);
FLValue value;
while (NULL != (value = FLDictIterator_GetValue(&iter))) {
// ...
}
FLEECE_PUBLIC FLValue FL_NULLABLE FLDictIterator_GetValue(const FLDictIterator *) FLPURE
Returns the current value being iterated over.
FLEECE_PUBLIC void FLDictIterator_Begin(FLDict FL_NULLABLE, FLDictIterator *)
Initializes a FLDictIterator struct to iterate over a dictionary.
FLEECE_PUBLIC bool FLDictIterator_Next(FLDictIterator *)
Advances the iterator to the next value, or returns false if at the end.
FLEECE_PUBLIC FLString FLDictIterator_GetKeyString(const FLDictIterator *)
Returns the current key's string value.
const struct _FLValue * FLValue
A reference to a value of any type.
Definition: FLBase.h:35
Opaque dictionary iterator.
Definition: FLCollections.h:144
A simple reference to a block of memory.
Definition: FLSlice.h:45
FLEECE_PUBLIC void FLDictIterator_Begin (FLDict FL_NULLABLE, FLDictIterator *)
 Initializes a FLDictIterator struct to iterate over a dictionary. More...
 
FLEECE_PUBLIC FLValue FL_NULLABLE FLDictIterator_GetKey (const FLDictIterator *) FLPURE
 Returns the current key being iterated over. More...
 
FLEECE_PUBLIC FLString FLDictIterator_GetKeyString (const FLDictIterator *)
 Returns the current key's string value. More...
 
FLEECE_PUBLIC FLValue FL_NULLABLE FLDictIterator_GetValue (const FLDictIterator *) FLPURE
 Returns the current value being iterated over. More...
 
FLEECE_PUBLIC uint32_t FLDictIterator_GetCount (const FLDictIterator *) FLPURE
 Returns the number of items remaining to be iterated, including the current one. More...
 
FLEECE_PUBLIC bool FLDictIterator_Next (FLDictIterator *)
 Advances the iterator to the next value, or returns false if at the end. More...
 
FLEECE_PUBLIC void FLDictIterator_End (FLDictIterator *)
 Cleans up after an iterator. More...
 

Optimized Keys

FLEECE_PUBLIC FLDictKey FLDictKey_Init (FLSlice string)
 Initializes an FLDictKey struct with a key string. More...
 
FLEECE_PUBLIC FLString FLDictKey_GetString (const FLDictKey *)
 Returns the string value of the key (which it was initialized with.) More...
 
FLEECE_PUBLIC FLValue FL_NULLABLE FLDict_GetWithKey (FLDict FL_NULLABLE, FLDictKey *)
 Looks up a key in a dictionary using an FLDictKey. More...
 

Detailed Description

Function Documentation

◆ FLDict_AsMutable()

FLEECE_PUBLIC FLMutableDict FL_NULLABLE FLDict_AsMutable ( FLDict  FL_NULLABLE)

If the dictionary is mutable, returns it cast to FLMutableDict, else NULL.

◆ FLDict_Count()

FLEECE_PUBLIC uint32_t FLDict_Count ( FLDict  FL_NULLABLE)

Returns the number of items in a dictionary, or 0 if the pointer is NULL.

◆ FLDict_Get()

FLEECE_PUBLIC FLValue FL_NULLABLE FLDict_Get ( FLDict  FL_NULLABLE,
FLSlice  keyString 
)

Looks up a key in a dictionary, returning its value.

Returns NULL if the value is not found or if the dictionary is NULL.

◆ FLDict_GetWithKey()

FLEECE_PUBLIC FLValue FL_NULLABLE FLDict_GetWithKey ( FLDict  FL_NULLABLE,
FLDictKey  
)

Looks up a key in a dictionary using an FLDictKey.

If the key is found, "hint" data will be stored inside the FLDictKey that will speed up subsequent lookups.

◆ FLDict_IsEmpty()

FLEECE_PUBLIC bool FLDict_IsEmpty ( FLDict  FL_NULLABLE)

Returns true if a dictionary is empty (or NULL).

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

◆ FLDictIterator_Begin()

FLEECE_PUBLIC void FLDictIterator_Begin ( FLDict  FL_NULLABLE,
FLDictIterator  
)

Initializes a FLDictIterator struct to iterate over a dictionary.

Call FLDictIterator_GetKey and FLDictIterator_GetValue to get the first item, then FLDictIterator_Next.

◆ FLDictIterator_End()

FLEECE_PUBLIC void FLDictIterator_End ( FLDictIterator )

Cleans up after an iterator.

Only needed if (a) the dictionary is a delta, and (b) you stop iterating before the end (i.e. before FLDictIterator_Next returns false.)

◆ FLDictIterator_GetCount()

FLEECE_PUBLIC uint32_t FLDictIterator_GetCount ( const FLDictIterator )

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

◆ FLDictIterator_GetKey()

FLEECE_PUBLIC FLValue FL_NULLABLE FLDictIterator_GetKey ( const FLDictIterator )

Returns the current key being iterated over.

This Value will be a string or an integer.

◆ FLDictIterator_GetKeyString()

FLEECE_PUBLIC FLString FLDictIterator_GetKeyString ( const FLDictIterator )

Returns the current key's string value.

◆ FLDictIterator_GetValue()

FLEECE_PUBLIC FLValue FL_NULLABLE FLDictIterator_GetValue ( const FLDictIterator )

Returns the current value being iterated over.

◆ FLDictIterator_Next()

FLEECE_PUBLIC bool FLDictIterator_Next ( FLDictIterator )

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

◆ FLDictKey_GetString()

FLEECE_PUBLIC FLString FLDictKey_GetString ( const FLDictKey )

Returns the string value of the key (which it was initialized with.)

◆ FLDictKey_Init()

FLEECE_PUBLIC FLDictKey FLDictKey_Init ( FLSlice  string)

Initializes an FLDictKey struct with a key string.

Warning
The input string's memory MUST remain valid for as long as the FLDictKey is in use! (The FLDictKey stores a pointer to the string, but does not copy it.)
Parameters
stringThe key string (UTF-8).
Returns
An initialized FLDictKey struct.

Variable Documentation

◆ kFLEmptyDict

FLEECE_PUBLIC const FLDict kFLEmptyDict
extern

A constant empty array value.