UnQLite C/C++ API Reference - Populating Dynamically Typed Objects.

Syntax

int unqlite_value_int(unqlite_value *pVal,int iValue);

int unqlite_value_int64(unqlite_value *pVal,unqlite_int64 iValue);

int unqlite_value_bool(unqlite_value *pVal,int iBool);

int unqlite_value_null(unqlite_value *pVal);

int unqlite_value_double(unqlite_value *pVal,double Value);

int unqlite_value_string(unqlite_value *pVal,const char *zString,int nLen);

int unqlite_value_string_format(unqlite_value *pVal,const char *zFormat,...);

int unqlite_value_reset_string_cursor(unqlite_value *pVal);

int unqlite_value_resource(unqlite_value *pVal,void *pUserData);

Populate a UnQLite object value.

Description

These routines are used to populate a freshly created UnQLite object value obtained by a prior successful call to unqlite_vm_new_scalar(), unqlite_context_new_scalar() or from a callback responsible of expanding constant value.

The unqlite_value_int() interface sets the unqlite_value to the integer type where the value is specified by its 2nd argument.

The unqlite_value_int64() interface sets the unqlite_value to the 64-bit integer type where the value is specified by its 2nd argument.

The unqlite_value_double() interface sets the unqlite_value to the double type where the value is specified by its 2nd argument.

The unqlite_value_bool() interface sets the unqlite_value to the boolean type where the value (Only zero is assumed to be FALSE) is specified by its 2nd argument.

The unqlite_value_null() interface sets the unqlite_value to the NULL type.

The unqlite_value_resource() interface sets the unqlite_value to the resource type where the value is specified by its 2nd argument which is an arbitrary user pointer that can be extracted later using unqlite_value_to_resource().

The unqlite_value_string() interface sets the unqlite_value to the string type where the string content is specified by the 2nd argument.

Note that unqlite_value_string() accepts a third argument which is the length of the string to append. If the nLen argument is less than zero, then zString is read up to the first zero terminator. If nLen is non-negative, then it is the maximum number of bytes read from zString.

unqlite_value_string_format() is a work-alike of the "printf()" family of functions from the standard C library which is used to append a formatted string.

The unqlite_value_string() and unqlite_value_string_format() interfaces write their result to an internal buffer which grow automatically by successive calls to one of them (An append operation). That is, previously written data is not erased by the new call. If such behavior is wanted, call unqlite_value_reset_string_cursor() to reset the internal buffer.

Example

unqlite_value_string(pValue,"Welcome, current time is: ",-1);

unqlite_value_string_format(pValue,"%02d:%02d:%02d",14,12,59);

The final result if extracted by unqlite_value_to_string() would look like this:

“Welcome, current time is: 14:12:59”

These routines are very useful when implementing foreign functions which need to populate JSON arrays or objects values.

If these routines are called from within the different thread than the one containing the application-defined function that received the unqlite_value pointer, the results are undefined.

Parameters

pVal

A pointer to a unqlite_value to be populated.

Return value

UNQLITE_OK is returned on success. Any other return value indicates failure.

Example

Compile this C file for a smart introduction to these interfaces.