UnQLite C/C++ API Reference - On Demand Object Allocation.

Syntax

unqlite_value * unqlite_vm_new_scalar(unqlite_vm *pVm);

unqlite_value * unqlite_vm_new_array(unqlite_vm *pVm);

int unqlite_vm_release_value(unqlite_vm *pVm,unqlite_value *pValue);

unqlite_value * unqlite_context_new_scalar(unqlite_context *pCtx);

unqlite_value * unqlite_context_new_array(unqlite_context *pCtx);

void unqlite_context_release_value(unqlite_context *pCtx,unqlite_value *pValue);

Allocate UnQLite Object Values on Demand.

Description

These routine allocate unqlite_value on demand, they are used mostly by foreign functions or foreign variables which work with JSON arrays and JSON objects.

unqlite_vm_new_scalar() allocate a new scalar unqlite_value which is set to the null type by default. Use the following interfaces to populate the object with the desired value:

unqlite_value_int()

unqlite_value_int64()

unqlite_value_bool()

unqlite_value_null()

unqlite_value_double()

unqlite_value_string()

unqlite_value_string_format()

unqlite_value_resource()

unqlite_vm_new_array() allocate a new unqlite_value of type array. The JSON array can be populated later using one of these interfaces unqlite_array_add_elem() or unqlite_array_add_strkey_elem(). This interface is unified for JSON arrays as well JSON objects.

unqlite_vm_release_value() destroy a unqlite_value obtained by a prior call to unqlite_vm_new_scalar() or unqlite_vm_new_array().

unqlite_vm_new_scalar() and unqlite_vm_new_array() takes as their first argument a pointer to a unqlite_vm instance. They are used mostly for the creation of foreign variables which are registered later via unqlite_vm_config() with a configuration verb set to UNQLITE_VM_CONFIG_CREATE_VAR.

unqlite_context_new_scalar() and unqlite_context_new_array() takes as their first argument a pointer to a unqlite_context which mean that they are designed to be invoked only from a foreign function. Note that calling unqlite_context_release_value() is not necessary since the garbage collector subsystem will automatically destroy any allocated unqlite_value as soon the foreign function have finished its execution.

Tip: if you want to return the allocated unqlite_value inside your foreign function, use unqlite_result_value().

Parameters

pVm/pCtx

A pointer to a unQLite VM/Foreign Function Call Context.

Return value

unqlite_context_new_scalar(), unqlite_context_new_array(), unqlite_vm_new_scalar() and unqlite_vm_new_array() return a pointer to a freshly allocated unqlite_value on success. Otherwise NULL is returned on failure (i.e: Out of memory).

Example

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