Fleece Value Accessors

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

Macros
#define	FLTimestampNone   INT64_MIN
	A value representing a missing timestamp; returned when a date cannot be parsed. More...

Typedefs
typedef int64_t	FLTimestamp
	A timestamp, expressed as milliseconds since the Unix epoch (1-1-1970 midnight UTC.) More...

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

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

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

Ref-counting (mutable values only)
FLValue	FLValue_Retain (FLValue)
	If this value is mutable (and thus heap-based) its ref-count is incremented. More...
void	FLValue_Release (FLValue)
	If this value is mutable (and thus heap-based) its ref-count is decremented, and if it reaches zero the value is freed. More...
static FLArray	FLArray_Retain (FLArray v)
static void	FLArray_Release (FLArray v)
static FLDict	FLDict_Retain (FLDict v)
static void	FLDict_Release (FLDict 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.)

It's always safe to pass a NULL value to an accessor; that goes for FLDict and FLArray as well as FLValue. The result will be a default value of that type, e.g. false or 0 or NULL, unless otherwise specified.

Macro Definition Documentation

FLTimestampNone

#define FLTimestampNone   INT64_MIN

A value representing a missing timestamp; returned when a date cannot be parsed.

Typedef Documentation

FLTimestamp

typedef int64_t FLTimestamp

A timestamp, expressed as milliseconds since the Unix epoch (1-1-1970 midnight UTC.)

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

Function Documentation

FLArray_Release()

static void FLArray_Release ( FLArray  v )

inlinestatic

FLArray_Retain()

static FLArray FLArray_Retain ( FLArray  v )

inlinestatic

FLDict_Release()

static void FLDict_Release ( FLDict  v )

inlinestatic

FLDict_Retain()

static FLDict FLDict_Retain ( FLDict  v )

inlinestatic

FLValue_AsArray()

FLArray FLValue_AsArray

(

FLValue

)

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

FLValue_AsBool()

bool FLValue_AsBool

(

FLValue

)

Returns a value coerced to boolean.

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

FLValue_AsData()

FLSlice FLValue_AsData

(

FLValue

)

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

FLValue_AsDict()

FLDict FLValue_AsDict

(

FLValue

)

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

FLValue_AsDouble()

double FLValue_AsDouble

(

FLValue

)

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

float FLValue_AsFloat

(

FLValue

)

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

int64_t FLValue_AsInt

(

FLValue

)

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

FLString FLValue_AsString

(

FLValue

)

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

FLValue_AsTimestamp()

FLTimestamp FLValue_AsTimestamp

(

FLValue

)

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

uint64_t FLValue_AsUnsigned

(

FLValue

)

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

FLValueType FLValue_GetType

(

FLValue

)

Returns the data type of an arbitrary Value.

(If the parameter is a NULL pointer, returns kFLUndefined.)

FLValue_IsDouble()

bool FLValue_IsDouble

(

FLValue

)

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

FLValue_IsEqual()

bool FLValue_IsEqual	(	FLValue	v1,
		FLValue	v2
	)

Compares two values for equality.

This is a deep recursive comparison.

FLValue_IsInteger()

bool FLValue_IsInteger

(

FLValue

)

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

FLValue_IsMutable()

bool FLValue_IsMutable

(

FLValue

)

Returns true if the value is mutable.

FLValue_IsUnsigned()

bool FLValue_IsUnsigned

(

FLValue

)

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

FLValue FLValue_NewData

(

FLSlice

)

Allocates a data/blob value on the heap.

This is rarely needed – usually you'd just add data to a mutable Array or Dict directly using one of their "...SetData or "...AppendData" methods.

FLValue_NewString()

FLValue FLValue_NewString

(

FLString

)

Allocates a string value on the heap.

This is rarely needed – usually you'd just add a string to a mutable Array or Dict directly using one of their "...SetString" or "...AppendString" methods.

FLValue_Release()

void FLValue_Release

(

FLValue

)

If this value is mutable (and thus heap-based) its ref-count is decremented, and if it reaches zero the value is freed.

If the value is not mutable, this call does nothing.

FLValue_Retain()

FLValue FLValue_Retain

(

FLValue

)

If this value is mutable (and thus heap-based) its ref-count is incremented.

Otherwise, this call does nothing.

FLValue_ToString()

FLStringResult FLValue_ToString

(

FLValue

)

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 (not a NULL pointer!)

kFLUndefinedValue

FLEECE_PUBLIC const FLValue kFLUndefinedValue

extern

A constant undefined value.