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.

static FLArray FL_NULLABLE	FLArray_Retain (FLArray FL_NULLABLE v)

static void	FLArray_Release (FLArray FL_NULLABLE v)

static FLDict FL_NULLABLE	FLDict_Retain (FLDict FL_NULLABLE v)

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

static void FLArray_Release ( FLArray FL_NULLABLE v )

inlinestatic

◆ FLArray_Retain()

static FLArray FL_NULLABLE FLArray_Retain ( FLArray FL_NULLABLE v )

inlinestatic

◆ FLDict_Release()

static void FLDict_Release ( FLDict FL_NULLABLE v )

inlinestatic

◆ FLDict_Retain()

static FLDict FL_NULLABLE FLDict_Retain ( FLDict FL_NULLABLE v )

inlinestatic

◆ 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.

Enumerations

Variables

Accessors

Reference-Counting

Detailed Description

Enumeration Type Documentation

◆ FLValueType

Function Documentation

◆ FLArray_Release()

◆ FLArray_Retain()

◆ FLDict_Release()

◆ FLDict_Retain()

◆ FLValue_AsArray()

◆ FLValue_AsBool()

◆ FLValue_AsData()

◆ FLValue_AsDict()

◆ FLValue_AsDouble()

◆ FLValue_AsFloat()

◆ FLValue_AsInt()

◆ FLValue_AsString()

◆ FLValue_AsTimestamp()

◆ FLValue_AsUnsigned()

◆ FLValue_GetType()

◆ FLValue_IsDouble()

◆ FLValue_IsEqual()

◆ FLValue_IsInteger()

◆ FLValue_IsMutable()

◆ FLValue_IsUnsigned()

◆ FLValue_Release()

◆ FLValue_Retain()

◆ FLValue_ToString()

Variable Documentation

◆ kFLNullValue

◆ kFLUndefinedValue