Couchbase Lite C
Couchbase Lite C API
Macros | Typedefs | Enumerations | Functions | Variables
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).

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

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.