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.
FLEECE_PUBLIC bool	FLDict_IsEmpty (FLDict FL_NULLABLE) FLPURE
	Returns true if a dictionary is empty (or NULL).
FLEECE_PUBLIC FLMutableDict FL_NULLABLE	FLDict_AsMutable (FLDict FL_NULLABLE) FLPURE
	If the dictionary is mutable, returns it cast to FLMutableDict, else NULL.
FLEECE_PUBLIC FLValue FL_NULLABLE	FLDict_Get (FLDict FL_NULLABLE, FLSlice keyString) FLPURE
	Looks up a key in a dictionary, returning its value.

Variables
FLEECE_PUBLIC const FLDict	kFLEmptyDict
	A constant empty array value.

Dict iteration
Iterating a dictionary typically looks like this: FLDictIterator iter; FLDictIterator_Begin(theDict, &iter); FLValue value; while (NULL != (value = FLDictIterator_GetValue(&iter))) { FLString key = FLDictIterator_GetKeyString(&iter); // ... FLDictIterator_Next(&iter); }
FLEECE_PUBLIC void	FLDictIterator_Begin (FLDict FL_NULLABLE, FLDictIterator *)
	Initializes a FLDictIterator struct to iterate over a dictionary.
FLEECE_PUBLIC FLValue FL_NULLABLE	FLDictIterator_GetKey (const FLDictIterator *) FLPURE
	Returns the current key being iterated over.
FLEECE_PUBLIC FLString	FLDictIterator_GetKeyString (const FLDictIterator *)
	Returns the current key's string value, or NULL when there are no more keys.
FLEECE_PUBLIC FLValue FL_NULLABLE	FLDictIterator_GetValue (const FLDictIterator *) FLPURE
	Returns the current value being iterated over.
FLEECE_PUBLIC uint32_t	FLDictIterator_GetCount (const FLDictIterator *) FLPURE
	Returns the number of items remaining to be iterated, including the current one.
FLEECE_PUBLIC bool	FLDictIterator_Next (FLDictIterator *)
	Advances the iterator to the next value.
FLEECE_PUBLIC void	FLDictIterator_End (FLDictIterator *)
	Cleans up after an iterator.

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

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 as long as the item is not NULL, call FLDictIterator_Next to advance.

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, or NULL when there are no more keys.

FLDictIterator_GetKeyString()

FLEECE_PUBLIC FLString FLDictIterator_GetKeyString

(

const FLDictIterator *

)

Returns the current key's string value, or NULL when there are no more keys.

FLDictIterator_GetValue()

FLEECE_PUBLIC FLValue FL_NULLABLE FLDictIterator_GetValue

(

const FLDictIterator *

)

Returns the current value being iterated over.

Returns NULL when there are no more values.

FLDictIterator_Next()

FLEECE_PUBLIC bool FLDictIterator_Next

(

FLDictIterator *

)

Advances the iterator to the next value.

Warning

It is illegal to call this when the iterator is already at the end. In particular, calling this when the dict is empty is always illegal.

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

string

The key string (UTF-8).

Returns

An initialized FLDictKey struct.

Variable Documentation

kFLEmptyDict

FLEECE_PUBLIC const FLDict kFLEmptyDict

extern

A constant empty array value.