Fleece Values

The core Fleece data type is FLValue: a reference to a value in Fleece-encoded data. More...

Enumerations
enum	FLValueType {   kFLUndefined = -1 , kFLNull = 0 , kFLBoolean , kFLNumber ,   kFLString , kFLData , kFLArray , kFLDict }
	Types of Fleece values. More...

Variables
FLEECE_PUBLIC const FLValue	kFLNullValue
	A constant null value (like a JSON null, not a NULL pointer!)
FLEECE_PUBLIC const FLValue	kFLUndefinedValue
	A constant undefined value.

Accessors
FLEECE_PUBLIC FLValueType	FLValue_GetType (FLValue FL_NULLABLE) FLPURE
	Returns the data type of an arbitrary value.
FLEECE_PUBLIC bool	FLValue_IsInteger (FLValue FL_NULLABLE) FLPURE
	Returns true if the value is non-NULL and represents an integer.
FLEECE_PUBLIC bool	FLValue_IsUnsigned (FLValue FL_NULLABLE) FLPURE
	Returns true if the value is non-NULL and represents an integer >= 2^63.
FLEECE_PUBLIC bool	FLValue_IsDouble (FLValue FL_NULLABLE)
	Returns true if the value is non-NULL and represents a 64-bit floating-point number.
FLEECE_PUBLIC bool	FLValue_AsBool (FLValue FL_NULLABLE) FLPURE
	Returns a value coerced to boolean.
FLEECE_PUBLIC int64_t	FLValue_AsInt (FLValue FL_NULLABLE) FLPURE
	Returns a value coerced to an integer.
FLEECE_PUBLIC uint64_t	FLValue_AsUnsigned (FLValue FL_NULLABLE) FLPURE
	Returns a value coerced to an unsigned integer.
FLEECE_PUBLIC float	FLValue_AsFloat (FLValue FL_NULLABLE) FLPURE
	Returns a value coerced to a 32-bit floating point number.
FLEECE_PUBLIC double	FLValue_AsDouble (FLValue FL_NULLABLE) FLPURE
	Returns a value coerced to a 32-bit floating point number.
FLEECE_PUBLIC FLString	FLValue_AsString (FLValue FL_NULLABLE) FLPURE
	Returns the exact contents of a string value, or null for all other types.
FLEECE_PUBLIC FLTimestamp	FLValue_AsTimestamp (FLValue FL_NULLABLE) FLPURE
	Converts a value to a timestamp, in milliseconds since Unix epoch, or INT64_MIN on failure.
FLEECE_PUBLIC FLSlice	FLValue_AsData (FLValue FL_NULLABLE) FLPURE
	Returns the exact contents of a data value, or null for all other types.
FLEECE_PUBLIC FLArray FL_NULLABLE	FLValue_AsArray (FLValue FL_NULLABLE) FLPURE
	If a FLValue represents an array, returns it cast to FLArray, else NULL.
FLEECE_PUBLIC FLDict FL_NULLABLE	FLValue_AsDict (FLValue FL_NULLABLE) FLPURE
	If a FLValue represents a dictionary, returns it as an FLDict, else NULL.
FLEECE_PUBLIC FLStringResult	FLValue_ToString (FLValue FL_NULLABLE)
	Returns a string representation of any scalar value.
FLEECE_PUBLIC bool	FLValue_IsEqual (FLValue FL_NULLABLE v1, FLValue FL_NULLABLE v2) FLPURE
	Compares two values for equality.
FLEECE_PUBLIC bool	FLValue_IsMutable (FLValue FL_NULLABLE) FLPURE
	Returns true if the value is mutable.

Reference-Counting
Retaining a value extends its lifespan (and that of any values contained in it) until at least such time that it's released. If the value comes from an FLDoc, the doc's ref-count will be incremented. If the value is mutable (heap-based), it has its own ref-count that will be incremented. Warning Values obtained from FLValue_FromData don't match either of those critera. Their lifespan is entirely determined by the caller-provided data pointer, so the retain call can't do anything about it. In this situation Fleece will throw an exception like "Can't retain immutable Value that's not part of a Doc."
FLEECE_PUBLIC FLValue FL_NULLABLE	FLValue_Retain (FLValue FL_NULLABLE)
	Increments the ref-count of a mutable value, or of an immutable value's FLDoc.
FLEECE_PUBLIC void	FLValue_Release (FLValue FL_NULLABLE)
	Decrements the ref-count of a mutable value, or of an immutable value's FLDoc.
FLArray FL_NULLABLE	FLArray_Retain (FLArray FL_NULLABLE v)
void	FLArray_Release (FLArray FL_NULLABLE v)
FLDict FL_NULLABLE	FLDict_Retain (FLDict FL_NULLABLE v)
void	FLDict_Release (FLDict FL_NULLABLE v)

Detailed Description

The core Fleece data type is FLValue: a reference to a value in Fleece-encoded data.

An FLValue can represent any JSON type (plus binary data).

• Scalar data types – numbers, booleans, null, strings, data – can be accessed using individual functions of the form FLValue_As...; these return the scalar value, or a default zero/false/null value if the value is not of that type.
• Collections – arrays and dictionaries – have their own "subclasses": FLArray and FLDict. These have the same pointer values as an FLValue but are not type-compatible in C. To coerce an FLValue to a collection type, call FLValue_AsArray or FLValue_AsDict. If the value is not of that type, NULL is returned. (FLArray and FLDict are documented fully in their own sections.)

Note

It's safe to pass a NULL pointer to an FLValue, FLArray or FLDict function parameter, except where specifically noted.

Conversion/accessor functions that take FLValue won't complain if the value isn't of the desired subtype; they'll just return some default like 0 or NULL. For example, FLValue_AsInt will return 0 if passed a non-integer value or NULL.

Enumeration Type Documentation

FLValueType

enum FLValueType

Types of Fleece values.

Basically JSON, with the addition of Data (raw blob).

Enumerator
kFLUndefined	Type of a NULL pointer, i.e. no such value, like JSON undefined. Also the type of kFLUndefinedValue, and of a value created by FLEncoder_WriteUndefined().
kFLNull	Equivalent to a JSON 'null'.
kFLBoolean	A true or false value.
kFLNumber	A numeric value, either integer or floating-point.
kFLString	A string.
kFLData	Binary data (no JSON equivalent)
kFLArray	An array of values.
kFLDict	A mapping of strings to values (AKA "object" in JSON.)

Function Documentation

FLArray_Release()

void FLArray_Release ( FLArray FL_NULLABLE v )

inline

FLArray_Retain()

FLArray FL_NULLABLE FLArray_Retain ( FLArray FL_NULLABLE v )

inline

FLDict_Release()

void FLDict_Release ( FLDict FL_NULLABLE v )

inline

FLDict_Retain()

FLDict FL_NULLABLE FLDict_Retain ( FLDict FL_NULLABLE v )

inline

FLValue_AsArray()

FLEECE_PUBLIC FLArray FL_NULLABLE FLValue_AsArray

(

FLValue

FL_NULLABLE

)

If a FLValue represents an array, returns it cast to FLArray, else NULL.

FLValue_AsBool()

FLEECE_PUBLIC bool FLValue_AsBool

(

FLValue

FL_NULLABLE

)

Returns a value coerced to boolean.

This will be true unless the value is NULL (undefined), null, false, or zero.

FLValue_AsData()

FLEECE_PUBLIC FLSlice FLValue_AsData

(

FLValue

FL_NULLABLE

)

Returns the exact contents of a data value, or null for all other types.

FLValue_AsDict()

FLEECE_PUBLIC FLDict FL_NULLABLE FLValue_AsDict

(

FLValue

FL_NULLABLE

)

If a FLValue represents a dictionary, returns it as an FLDict, else NULL.

FLValue_AsDouble()

FLEECE_PUBLIC double FLValue_AsDouble

(

FLValue

FL_NULLABLE

)

Returns a value coerced to a 32-bit floating point number.

True and false are returned as 1.0 and 0.0, and integers are converted to float. All other types are returned as 0.0.

Warning

Very large integers (outside approximately +/- 2^50) will lose precision due to the limitations of IEEE 32-bit float format.

FLValue_AsFloat()

FLEECE_PUBLIC float FLValue_AsFloat

(

FLValue

FL_NULLABLE

)

Returns a value coerced to a 32-bit floating point number.

True and false are returned as 1.0 and 0.0, and integers are converted to float. All other types are returned as 0.0.

Warning

Large integers (outside approximately +/- 2^23) will lose precision due to the limitations of IEEE 32-bit float format.

FLValue_AsInt()

FLEECE_PUBLIC int64_t FLValue_AsInt

(

FLValue

FL_NULLABLE

)

Returns a value coerced to an integer.

True and false are returned as 1 and 0, and floating-point numbers are rounded. All other types are returned as 0.

Warning

Large 64-bit unsigned integers (2^63 and above) will come out wrong. You can check for these by calling FLValueIsUnsigned.

FLValue_AsString()

FLEECE_PUBLIC FLString FLValue_AsString

(

FLValue

FL_NULLABLE

)

Returns the exact contents of a string value, or null for all other types.

FLValue_AsTimestamp()

FLEECE_PUBLIC FLTimestamp FLValue_AsTimestamp

(

FLValue

FL_NULLABLE

)

Converts a value to a timestamp, in milliseconds since Unix epoch, or INT64_MIN on failure.

• A string is parsed as ISO-8601 (standard JSON date format).
• A number is interpreted as a timestamp and returned as-is.

FLValue_AsUnsigned()

FLEECE_PUBLIC uint64_t FLValue_AsUnsigned

(

FLValue

FL_NULLABLE

)

Returns a value coerced to an unsigned integer.

This is the same as FLValueAsInt except that it can't handle negative numbers, but does correctly return large uint64_t values of 2^63 and up.

FLValue_GetType()

FLEECE_PUBLIC FLValueType FLValue_GetType

(

FLValue

FL_NULLABLE

)

Returns the data type of an arbitrary value.

If the parameter is a NULL pointer, returns kFLUndefined.

FLValue_IsDouble()

FLEECE_PUBLIC bool FLValue_IsDouble

(

FLValue

FL_NULLABLE

)

Returns true if the value is non-NULL and represents a 64-bit floating-point number.

FLValue_IsEqual()

FLEECE_PUBLIC bool FLValue_IsEqual	(	FLValue FL_NULLABLE	v1,
		FLValue FL_NULLABLE	v2 )

Compares two values for equality.

This is a deep recursive comparison.

FLValue_IsInteger()

FLEECE_PUBLIC bool FLValue_IsInteger

(

FLValue

FL_NULLABLE

)

Returns true if the value is non-NULL and represents an integer.

FLValue_IsMutable()

FLEECE_PUBLIC bool FLValue_IsMutable

(

FLValue

FL_NULLABLE

)

Returns true if the value is mutable.

FLValue_IsUnsigned()

FLEECE_PUBLIC bool FLValue_IsUnsigned

(

FLValue

FL_NULLABLE

)

Returns true if the value is non-NULL and represents an integer >= 2^63.

Such a value can't be represented in C as an int64_t, only a uint64_t, so you should access it by calling FLValueAsUnsigned, not FLValueAsInt, which would return an incorrect (negative) value.

FLValue_Release()

FLEECE_PUBLIC void FLValue_Release

(

FLValue

FL_NULLABLE

)

Decrements the ref-count of a mutable value, or of an immutable value's FLDoc.

If the ref-count reaches zero the corresponding object is freed.

Warning

It is illegal to call this on a value obtained from FLValue_FromData.

FLValue_Retain()

FLEECE_PUBLIC FLValue FL_NULLABLE FLValue_Retain

(

FLValue

FL_NULLABLE

)

Increments the ref-count of a mutable value, or of an immutable value's FLDoc.

Warning

It is illegal to call this on a value obtained from FLValue_FromData.

FLValue_ToString()

FLEECE_PUBLIC FLStringResult FLValue_ToString

(

FLValue

FL_NULLABLE

)

Returns a string representation of any scalar value.

Data values are returned in raw form. Arrays and dictionaries don't have a representation and will return NULL.

Variable Documentation

kFLNullValue

FLEECE_PUBLIC const FLValue kFLNullValue

extern

A constant null value (like a JSON null, not a NULL pointer!)

kFLUndefinedValue

FLEECE_PUBLIC const FLValue kFLUndefinedValue

extern

A constant undefined value.

This is not a NULL pointer, but its type is kFLUndefined. It can be stored in an FLMutableArray or FLMutableDict if you really, really need to store an undefined/empty value, not just a JSON null.