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

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

Variables

FLEECE_PUBLIC const FLDict kFLEmptyDict
 

Dict iteration

Iterating a dictionary typically looks like this:

FLDictIterator_Begin(theDict, &iter);
FLValue value;
while (NULL != (value = FLDictIterator_GetValue(&iter))) {
// ...
}
void FLDictIterator_Begin(FLDict, FLDictIterator *)
Initializes a FLDictIterator struct to iterate over a dictionary.
FLString FLDictIterator_GetKeyString(const FLDictIterator *)
Returns the current key's string value.
bool FLDictIterator_Next(FLDictIterator *)
Advances the iterator to the next value, or returns false if at the end.
FLValue FLDictIterator_GetValue(const FLDictIterator *) 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 dictionary iterator.
Definition: Fleece.h:639
A simple reference to a block of memory.
Definition: FLSlice.h:46
void FLDictIterator_Begin (FLDict, FLDictIterator *)
 Initializes a FLDictIterator struct to iterate over a dictionary. More...
 
FLValue FLDictIterator_GetKey (const FLDictIterator *) FLPURE
 Returns the current key being iterated over. More...
 
FLString FLDictIterator_GetKeyString (const FLDictIterator *)
 Returns the current key's string value. More...
 
FLValue FLDictIterator_GetValue (const FLDictIterator *) FLPURE
 Returns the current value being iterated over. More...
 
uint32_t FLDictIterator_GetCount (const FLDictIterator *) FLPURE
 Returns the number of items remaining to be iterated, including the current one. More...
 
bool FLDictIterator_Next (FLDictIterator *)
 Advances the iterator to the next value, or returns false if at the end. More...
 
void FLDictIterator_End (FLDictIterator *)
 Cleans up after an iterator. More...
 

Optimized Keys

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

Mutable dictionaries

FLMutableDict FLDict_MutableCopy (FLDict source, FLCopyFlags)
 Creates a new mutable Dict that's a copy of the source Dict. More...
 
FLMutableDict FLMutableDict_New (void)
 Creates a new empty mutable Dict. More...
 
FLMutableDict FLMutableDict_NewFromJSON (FLString json, FLError *outError)
 Creates a new mutable Dict from json. More...
 
static FLMutableDict FLMutableDict_Retain (FLMutableDict d)
 Increments the ref-count of a mutable Dict. More...
 
static void FLMutableDict_Release (FLMutableDict d)
 Decrements the refcount of (and possibly frees) a mutable Dict. More...
 
FLDict FLMutableDict_GetSource (FLMutableDict)
 If the Dict was created by FLDict_MutableCopy, returns the original source Dict. More...
 
bool FLMutableDict_IsChanged (FLMutableDict)
 Returns true if the Dict has been changed from the source it was copied from. More...
 
void FLMutableDict_SetChanged (FLMutableDict, bool)
 Sets or clears the mutable Dict's "changed" flag. More...
 
void FLMutableDict_Remove (FLMutableDict, FLString key)
 Removes the value for a key. More...
 
void FLMutableDict_RemoveAll (FLMutableDict)
 Removes all keys and values. More...
 
FLMutableArray FLMutableDict_GetMutableArray (FLMutableDict, FLString key)
 Convenience function for getting an array-valued property in mutable form. More...
 
FLMutableDict FLMutableDict_GetMutableDict (FLMutableDict, FLString key)
 Convenience function for getting a dict-valued property in mutable form. More...
 
static void FLMutableDict_SetNull (FLMutableDict, FLString key)
 Stores a JSON null value into a mutable dictionary. More...
 
static void FLMutableDict_SetBool (FLMutableDict, FLString key, bool)
 Stores a boolean value into a mutable dictionary. More...
 
static void FLMutableDict_SetInt (FLMutableDict, FLString key, int64_t)
 Stores an integer into a mutable dictionary. More...
 
static void FLMutableDict_SetUInt (FLMutableDict, FLString key, uint64_t)
 Stores an unsigned integer into a mutable dictionary. More...
 
static void FLMutableDict_SetFloat (FLMutableDict, FLString key, float)
 Stores a 32-bit floating-point number into a mutable dictionary. More...
 
static void FLMutableDict_SetDouble (FLMutableDict, FLString key, double)
 Stores a 64-bit floating point number into a mutable dictionary. More...
 
static void FLMutableDict_SetString (FLMutableDict, FLString key, FLString)
 Stores a UTF-8-encoded string into a mutable dictionary. More...
 
static void FLMutableDict_SetData (FLMutableDict, FLString key, FLSlice)
 Stores a binary data blob into a mutable dictionary. More...
 
static void FLMutableDict_SetValue (FLMutableDict, FLString key, FLValue)
 Stores a Fleece value into a mutable dictionary. More...
 
static void FLMutableDict_SetArray (FLMutableDict, FLString key, FLArray)
 Stores a Fleece array into a mutable dictionary. More...
 
static void FLMutableDict_SetDict (FLMutableDict, FLString key, FLDict)
 Stores a Fleece dictionary into a mutable dictionary. More...
 

Detailed Description

Function Documentation

◆ FLDict_AsMutable()

FLMutableDict FLDict_AsMutable ( FLDict  )

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

◆ FLDict_Count()

uint32_t FLDict_Count ( FLDict  )

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

◆ FLDict_Get()

FLValue FLDict_Get ( FLDict  ,
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()

FLValue FLDict_GetWithKey ( FLDict  ,
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()

bool FLDict_IsEmpty ( FLDict  )

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

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

◆ FLDict_MutableCopy()

FLMutableDict FLDict_MutableCopy ( FLDict  source,
FLCopyFlags   
)

Creates a new mutable Dict that's a copy of the source Dict.

Its initial ref-count is 1, so a call to FLMutableDict_Release will free it.

Copying an immutable Dict is very cheap (only one small allocation.) The deepCopy flag is ignored.

Copying a mutable Dict is cheap if it's a shallow copy, but if deepCopy is true, nested mutable Dicts and Arrays are also copied, recursively.

If the source dict is NULL, then NULL is returned.

◆ FLDictIterator_Begin()

void FLDictIterator_Begin ( FLDict  ,
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()

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()

uint32_t FLDictIterator_GetCount ( const FLDictIterator )

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

◆ FLDictIterator_GetKey()

FLValue FLDictIterator_GetKey ( const FLDictIterator )

Returns the current key being iterated over.

This Value will be a string or an integer.

◆ FLDictIterator_GetKeyString()

FLString FLDictIterator_GetKeyString ( const FLDictIterator )

Returns the current key's string value.

◆ FLDictIterator_GetValue()

FLValue FLDictIterator_GetValue ( const FLDictIterator )

Returns the current value being iterated over.

◆ FLDictIterator_Next()

bool FLDictIterator_Next ( FLDictIterator )

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

◆ FLDictKey_GetString()

FLString FLDictKey_GetString ( const FLDictKey )

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

◆ FLDictKey_Init()

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.

◆ FLMutableDict_GetMutableArray()

FLMutableArray FLMutableDict_GetMutableArray ( FLMutableDict  ,
FLString  key 
)

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.

◆ FLMutableDict_GetMutableDict()

FLMutableDict FLMutableDict_GetMutableDict ( FLMutableDict  ,
FLString  key 
)

Convenience function for getting a dict-valued property in mutable form.

  • If the value for the key is not a dict, returns NULL.
  • If the value is a mutable dict, returns it.
  • If the value is an immutable dict, this function makes a mutable copy, assigns the copy as the property value, and returns the copy.

◆ FLMutableDict_GetSource()

FLDict FLMutableDict_GetSource ( FLMutableDict  )

If the Dict was created by FLDict_MutableCopy, returns the original source Dict.

◆ FLMutableDict_IsChanged()

bool FLMutableDict_IsChanged ( FLMutableDict  )

Returns true if the Dict has been changed from the source it was copied from.

◆ FLMutableDict_New()

FLMutableDict FLMutableDict_New ( void  )

Creates a new empty mutable Dict.

Its initial ref-count is 1, so a call to FLMutableDict_Release will free it.

◆ FLMutableDict_NewFromJSON()

FLMutableDict FLMutableDict_NewFromJSON ( FLString  json,
FLError outError 
)

Creates a new mutable Dict 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 FLMutableDict_Release will free it.

◆ FLMutableDict_Release()

static void FLMutableDict_Release ( FLMutableDict  d)
inlinestatic

Decrements the refcount of (and possibly frees) a mutable Dict.

◆ FLMutableDict_Remove()

void FLMutableDict_Remove ( FLMutableDict  ,
FLString  key 
)

Removes the value for a key.

◆ FLMutableDict_RemoveAll()

void FLMutableDict_RemoveAll ( FLMutableDict  )

Removes all keys and values.

◆ FLMutableDict_Retain()

static FLMutableDict FLMutableDict_Retain ( FLMutableDict  d)
inlinestatic

Increments the ref-count of a mutable Dict.

◆ FLMutableDict_SetArray()

static void FLMutableDict_SetArray ( FLMutableDict  d,
FLString  key,
FLArray  val 
)
inlinestatic

Stores a Fleece array into a mutable dictionary.

◆ FLMutableDict_SetBool()

static void FLMutableDict_SetBool ( FLMutableDict  d,
FLString  key,
bool  val 
)
inlinestatic

Stores a boolean value into a mutable dictionary.

◆ FLMutableDict_SetChanged()

void FLMutableDict_SetChanged ( FLMutableDict  ,
bool   
)

Sets or clears the mutable Dict's "changed" flag.

◆ FLMutableDict_SetData()

static void FLMutableDict_SetData ( FLMutableDict  d,
FLString  key,
FLSlice  val 
)
inlinestatic

Stores a binary data blob into a mutable dictionary.

◆ FLMutableDict_SetDict()

static void FLMutableDict_SetDict ( FLMutableDict  d,
FLString  key,
FLDict  val 
)
inlinestatic

Stores a Fleece dictionary into a mutable dictionary.

◆ FLMutableDict_SetDouble()

static void FLMutableDict_SetDouble ( FLMutableDict  d,
FLString  key,
double  val 
)
inlinestatic

Stores a 64-bit floating point number into a mutable dictionary.

◆ FLMutableDict_SetFloat()

static void FLMutableDict_SetFloat ( FLMutableDict  d,
FLString  key,
float  val 
)
inlinestatic

Stores a 32-bit floating-point number into a mutable dictionary.

◆ FLMutableDict_SetInt()

static void FLMutableDict_SetInt ( FLMutableDict  d,
FLString  key,
int64_t  val 
)
inlinestatic

Stores an integer into a mutable dictionary.

◆ FLMutableDict_SetNull()

static void FLMutableDict_SetNull ( FLMutableDict  d,
FLString  key 
)
inlinestatic

Stores a JSON null value into a mutable dictionary.

◆ FLMutableDict_SetString()

static void FLMutableDict_SetString ( FLMutableDict  d,
FLString  key,
FLString  val 
)
inlinestatic

Stores a UTF-8-encoded string into a mutable dictionary.

◆ FLMutableDict_SetUInt()

static void FLMutableDict_SetUInt ( FLMutableDict  d,
FLString  key,
uint64_t  val 
)
inlinestatic

Stores an unsigned integer into a mutable dictionary.

Note
: The only time this needs to be called, instead of FLMutableDict_SetInt, is if the value is greater than or equal to 2^63 and won't fit in an int64_t.

◆ FLMutableDict_SetValue()

static void FLMutableDict_SetValue ( FLMutableDict  d,
FLString  key,
FLValue  val 
)
inlinestatic

Stores a Fleece value into a mutable dictionary.

Variable Documentation

◆ kFLEmptyDict

FLEECE_PUBLIC const FLDict kFLEmptyDict
extern