Loading...
Searching...
No Matches
Qore Data

# Qore Data

Data in Qore is handled with QoreValue, which contains a union (qore_value_u) with the following immediate values:

- `bool` b
- `int64` i
- `double` f
- AbstractQoreNode* n

All complex values in Qore are descended from AbstractQoreNode.

The following are the basic data types in Qore, implemented as C++ classes descended from AbstractQoreNode, and their type codes, accessed via AbstractQoreNode::getType():

- QoreStringNode (NT_STRING) for the string data type
- DateTimeNode (NT_DATE) for the date/time data type
- BinaryNode (NT_BINARY) for the opaque binary data type
- QoreNothingNode (NT_NOTHING) for a type signifying no value (also equivalent to `nullptr!`)
- QoreNullNode (NT_NULL) for the SQL NULL data type
- QoreHashNode (NT_HASH) for an associative array or hash data type
- QoreListNode (NT_LIST) for a list or array data type
- QoreObject (NT_OBJECT) for the data type representing the instantiation of a Qore class (QoreClass)

Additionally, the following classes are exposed in the library:

- ReferenceNode (NT_REFERENCE)
- AbstractFunctionReferenceNode (NT_FUNCREF)

See also
  node_types.h for a complete list of all type codes.

The fastest way to directly access data of a specific type is to use QoreValue::getType() and then the QoreValue::get() template as follows:

if (val.getType() == NT_DATE) {
DateTimeNode* dt = val.get<const DateTimeNode>();
// .. do something with dt
}
DateTimeNode
Qore's parse tree/value type for date-time values, reference-counted, dynamically-allocated only.
Definition: DateTimeNode.h:45
NT_DATE
const qore_type_t NT_DATE
type value for DateTimeNode
Definition: node_types.h:46

## Simple Value Types: QoreStringNode, DateTimeNode, BinaryNode

The QoreStringNode (NT_STRING), DateTimeNode (NT_DATE), and BinaryNode (NT_BINARY) classes are reference counted and can only be dynamically allocated.

They are all descendents of SimpleQoreNode, meaning that dereferencing their objects cannot cause a Qore-language exception to be thrown (hence all support the SimpleQoreNode::deref() function), therefore the SimpleRefHolder class can be used to manage temporary references to objects of these types.

For example:

{
// here getReferencedQoreStringNode() returns a QoreStringNode value with an incremented reference count
SimpleRefHolder<QoreStringNode> qstr(getReferencedQoreStringNode());
printf("the result is: %s\n", qstr->c_str());
// when qstr goes out of scope, the reference count is decremented by calling SimpleQoreNode::deref()
}
SimpleRefHolder
manages a reference count of a pointer to a class that takes a simple "deref()" call with no argument...
Definition: ReferenceHolder.h:118

## Unique Value Types: QoreNullNode, QoreNothingNode

QoreNullNode (NT_NULL) and QoreNothingNode (NT_NOTHING, but also equivalent to `nullptr`, see the note below) are special classes in that they may not be directly instantiated with the new operator. They are all represented by single non-reference-counted objects managed directly by the Qore library. Each of these classes represents a type that has only one value, therefore as a memory and performance optimization, reference counting is disabled for their objects.

For QoreNullNode there is the global Null object or the inline function null() that returns a pointer to this object. The inline function is_null() can be used to test for a Qore SQL Null value.

QoreNothingNode has the gobal Nothing object and the inline function nothing() that returns a pointer to it as well.

Note
  that in Qore a C++ null pointer (`nullptr`) is the same as `NOTHING`, therefore the inline function is_nothing() should always be used to test for `NOTHING`. Therefore the following code is incorrect:

// get_qore_value() returns "AbstractQoreNode*"
AbstractQoreNode* p = get_qore_value();
if (!p) { // incorrect! NOTHING in Qore can be represented by nullptr or a pointer to the Nothing value
}
AbstractQoreNode
The base class for all value and parse types in Qore expression trees.
Definition: AbstractQoreNode.h:57

The code should look like this instead:

// get_qore_value() returns "AbstractQoreNode*"
AbstractQoreNode* p = get_qore_value();
if (is_nothing(p)) { // correct test for nothing
}
is_nothing
static bool is_nothing(const AbstractQoreNode *n)
to check if an AbstractQoreNode object is NOTHING
Definition: QoreLib.h:316

## Container Value Types: QoreHashNode, QoreListNode, QoreObject

The QoreHashNode (NT_HASH), QoreListNode (NT_LIST), and QoreObject (NT_OBJECT) classes define container types in Qore. QoreObject objects in particular could throw an exception when dereferenced (if the object goes out of scope and its destructor is run, the destructor could throw an exception). Because container types can hold any type, when they are deferenced it could cause a QoreObject to go out of scope, and therefore the possibility that a Qore-language exception could be thrown must be taken into consideration. Therefore, to dereference these objects a pointer to an ExceptionSink object must be passed to AbstractQoreNode::deref().

The ReferenceHolder class can be used to manage temporary reference counts as follows:

{
// here a QoreHashNode value is returned with an incremented reference count
// note that xsink must be "ExceptionSink *"
ReferenceHolder<QoreHashNode> qhash(getQoreHashNode(), xsink);
printf("there are %ld elements in the hash\n", qhash->size());
// when qhash goes out of scope, the reference count is decremented
}
ReferenceHolder
a templated class to manage a reference count of an object that can throw a Qore-language exception w...
Definition: ReferenceHolder.h:52

## Object Value Type: QoreObject

QoreObject objects have node type NT_OBJECT as returned by AbstractQoreNode::getType().

QoreObject is special in that the implementation for objects in Qore mirrors that of Java, in that objects are passed by reference when used as function or method arguments, unlike other types. However, like Java, the reference to the object is passed, and not the value, so, while an object passed as an argument to a function can be modified by that function (modifications are made to the original object), in order to write a swap method, for example, you would need to pass the variables by reference (or the lvalue expression by reference, as the case may be) to the swap function. Unlike Java, Qore does support passing arguments by reference.

## Handling Reference Arguments: ReferenceNode and QoreTypeSafeReferenceHelper

Handling lvalue references is more complicated, as access to global variables and object member references must be made under the appropriate thread locks. However the QoreTypeSafeReferenceHelper class makes access to lvalue references much easier and takes care of all the locking, access to the lvalue expression, as well as type enforcement. With the QoreTypeSafeReferenceHelper class you can get the type of the lvalue expression's value, get a pointer to a node with a reference count of 1 for in-place modification, or assign a new value to the lvalue.

Here is an example of the use of QoreTypeSafeReferenceHelper:

// *string chomp(reference<string> str) {}
static QoreValue f_chomp(const QoreListNode* args, q_rt_flags_t rtflags, ExceptionSink* xsink) {
const ReferenceNode* str = HARD_QORE_VALUE_REF(args, 0);
QoreTypeSafeReferenceHelper ref(str, xsink);
if (*xsink) {
return QoreValue();
}
assert(ref && ref.getType() == NT_STRING);
QoreStringNode* rv = reinterpret_cast<QoreStringNode*>(ref.getUnique(xsink));
if (*xsink) {
return QoreValue();
}
rv->chomp();
return rv->refSelf();
}
AbstractQoreNode::refSelf
DLLEXPORT AbstractQoreNode * refSelf() const
returns "this" with an incremented reference count
ExceptionSink
container for holding Qore-language exception information and also for registering a "thread_exit" ca...
Definition: ExceptionSink.h:48
QoreListNode
This is the list container type in Qore, dynamically allocated only, reference counted.
Definition: QoreListNode.h:52
QoreString::chomp
DLLEXPORT size_t chomp()
removes a single \n\r or \n from the end of the string and returns the number of characters removed
QoreStringNode
Qore's string value type, reference counted, dynamically-allocated only.
Definition: QoreStringNode.h:50
QoreTypeSafeReferenceHelper
helper class to manage variable references passed to functions and class methods, stack only,...
Definition: QoreTypeSafeReferenceHelper.h:57
ReferenceNode
parse type: reference to a lvalue expression
Definition: ReferenceNode.h:45
q_rt_flags_t
uint64_t q_rt_flags_t
runtime code execution flags
Definition: common.h:263
NT_STRING
const qore_type_t NT_STRING
type value for QoreStringNode
Definition: node_types.h:45
HARD_QORE_VALUE_REF
#define HARD_QORE_VALUE_REF(list, i)
returns a const QoreHashNode* from a hard typed hash param
Definition: params.h:131
QoreValue
The main value class in Qore, designed to be passed by value.
Definition: QoreValue.h:276