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 iter; FLDictIterator_Begin(theDict, &iter); FLValue value; while (NULL != (value = FLDictIterator_GetValue(&iter))) { FLString key = FLDictIterator_GetKeyString(&iter); // ... FLDictIterator_Next(&iter); }
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

string

The 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