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.
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, or returns false if at the end.
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 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

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.