Couchbase Lite C
Couchbase Lite C API
Enumerations | Variables
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!) More...
 
FLEECE_PUBLIC const FLValue kFLUndefinedValue
 A constant undefined value. More...
 

Accessors

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

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. More...
 
FLEECE_PUBLIC void FLValue_Release (FLValue FL_NULLABLE)
 Decrements the ref-count of a mutable value, or of an immutable value's FLDoc. More...
 
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).

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

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.