This is the hash or associative list container type in Qore, dynamically allocated only, reference counted. More...
#include <QoreHashNode.h>
Public Member Functions | |
DLLEXPORT | QoreHashNode () |
creates an empty hash | |
virtual DLLEXPORT int | getAsString (QoreString &str, int foff, ExceptionSink *xsink) const |
concatenate the verbose string representation of the list (including all contained values) to an existing QoreString | |
virtual DLLEXPORT QoreString * | getAsString (bool &del, int foff, ExceptionSink *xsink) const |
returns a QoreString giving the verbose string representation of the List (including all contained values) | |
virtual DLLEXPORT AbstractQoreNode * | realCopy () const |
performs a deep copy of the hash and returns the new hash | |
virtual DLLEXPORT bool | is_equal_soft (const AbstractQoreNode *v, ExceptionSink *xsink) const |
tests for equality ("deep compare" including all contained values) with possible type conversion (soft compare) | |
virtual DLLEXPORT bool | is_equal_hard (const AbstractQoreNode *v, ExceptionSink *xsink) const |
tests for equality ("deep compare" including all contained values) without type conversions (hard compare) | |
virtual DLLEXPORT const char * | getTypeName () const |
returns the type name as a c string | |
DLLEXPORT QoreHashNode * | hashRefSelf () const |
returns "this" with an incremented reference count | |
DLLEXPORT const char * | getFirstKey () const |
returns the cstring value of the first key in the hash | |
DLLEXPORT const char * | getLastKey () const |
returns the cstring value of the last key in the hash | |
DLLEXPORT AbstractQoreNode * | getKeyValueExistence (const char *key, bool &exists) |
returns the value of the key (assumed to be in QCS_DEFAULT) if it exists and sets "exists" accordingly | |
DLLEXPORT const AbstractQoreNode * | getKeyValueExistence (const char *key, bool &exists) const |
returns the value of the key (assumed to be in QCS_DEFAULT) if it exists and sets "exists" accordingly | |
DLLEXPORT AbstractQoreNode * | getKeyValueExistence (const QoreString *key, bool &exists, ExceptionSink *xsink) |
returns the value of the key if it exists and sets "exists" accordingly | |
DLLEXPORT const AbstractQoreNode * | getKeyValueExistence (const QoreString *key, bool &exists, ExceptionSink *xsink) const |
returns the value of the key if it exists and sets "exists" accordingly | |
DLLEXPORT AbstractQoreNode * | getKeyValue (const QoreString *key, ExceptionSink *xsink) |
returns the value of the key if it exists | |
DLLEXPORT const AbstractQoreNode * | getKeyValue (const QoreString *key, ExceptionSink *xsink) const |
returns the value of the key if it exists | |
DLLEXPORT AbstractQoreNode * | getKeyValue (const char *key) |
returns the value of the key (assumed to be in QCS_DEFAULT) if it exists | |
DLLEXPORT const AbstractQoreNode * | getKeyValue (const char *key) const |
returns the value of the key (assumed to be in QCS_DEFAULT) if it exists | |
DLLEXPORT int64 | getKeyAsBigInt (const char *key, bool &found) const |
returns the value of the key as an int64 | |
DLLEXPORT QoreHashNode * | copy () const |
performs a deep copy of the hash and returns the new hash | |
DLLEXPORT AbstractQoreNode ** | getKeyValuePtr (const QoreString *key, ExceptionSink *xsink) |
returns a pointer to a pointer of the value of the key so the value may be set or changed externally | |
DLLEXPORT AbstractQoreNode ** | getKeyValuePtr (const char *key) |
returns a pointer to a pointer of the value of the key (assumed to be in QCS_DEFAULT) so the value may be set or changed externally | |
DLLEXPORT AbstractQoreNode ** | getExistingValuePtr (const QoreString *key, ExceptionSink *xsink) |
returns a pointer to a pointer of the value of the key only if the key already exists | |
DLLEXPORT AbstractQoreNode ** | getExistingValuePtr (const char *key) |
returns a pointer to a pointer of the value of the key (assumed to be be in QCS_DEFAULT), only if the key already exists | |
DLLEXPORT void | merge (const QoreHashNode *h, ExceptionSink *xsink) |
appends all key-value pairs of "h" to this hash | |
DLLEXPORT void | setKeyValue (const QoreString *key, AbstractQoreNode *value, ExceptionSink *xsink) |
sets the value of "key" to "value" | |
DLLEXPORT void | setKeyValue (const char *key, AbstractQoreNode *value, ExceptionSink *xsink) |
sets the value of "key" to "value" | |
DLLEXPORT AbstractQoreNode * | swapKeyValue (const QoreString *key, AbstractQoreNode *value, ExceptionSink *xsink) |
sets the value of "key" to "value" and returns the old value (0 if not present or if already 0), caller owns any reference count returned | |
DLLEXPORT AbstractQoreNode * | swapKeyValue (const char *key, AbstractQoreNode *value) |
sets the value of "key" to "value" and returns the old value (0 if not present or if already 0), caller owns any reference count returned | |
DLLEXPORT void | deleteKey (const QoreString *key, ExceptionSink *xsink) |
performs a delete operation on the value of the given key | |
DLLEXPORT void | deleteKey (const char *key, ExceptionSink *xsink) |
performs a delete operation on the value of the given key | |
DLLEXPORT AbstractQoreNode * | takeKeyValue (const QoreString *key, ExceptionSink *xsink) |
"takes" the value of the key from the hash and removes the key from the hash and returns the value, caller owns the reference count returned | |
DLLEXPORT AbstractQoreNode * | takeKeyValue (const char *key) |
"takes" the value of the key from the hash and removes the key from the hash and returns the value, caller owns the reference count returned | |
DLLEXPORT QoreListNode * | getKeys () const |
returns a QoreListNode of QoreStringNodes representing all keys in the hash, caller owns the reference count returned | |
DLLEXPORT bool | compareSoft (const QoreHashNode *h, ExceptionSink *xsink) const |
does a deep "soft" compare of all hash elements (types may be converted for the comparison) and returns true if the hashes are equal | |
DLLEXPORT bool | compareHard (const QoreHashNode *h, ExceptionSink *xsink) const |
does a deep "hard" compare of all hash elements (no type conversions are performed) and returns true if the hashes are equal | |
DLLEXPORT qore_size_t | size () const |
returns the number of members in the hash, executes in constant time | |
DLLEXPORT bool | empty () const |
returns true if the hash has no members, false if not | |
DLLEXPORT bool | existsKey (const char *key) const |
returns true if the hash contains the given key | |
DLLEXPORT bool | existsKeyValue (const char *key) const |
returns true if the hash contains the given key and the key has a value (i.e. is not NOTHING) | |
DLLEXPORT void | removeKey (const QoreString *key, ExceptionSink *xsink) |
removes the given key from the hash and derefences its value, if any | |
DLLEXPORT void | removeKey (const char *key, ExceptionSink *xsink) |
removes the given key from the hash and derefences its value, if any | |
virtual DLLLOCAL AbstractQoreNode * | parseInit (LocalVar *oflag, int pflag, int &lvids, const QoreTypeInfo *&typeInfo) |
initializes during parsing | |
DLLLOCAL void | clearNeedsEval () |
sets "needs_eval" to false and "value" to true | |
DLLLOCAL void | setNeedsEval () |
sets "needs_eval" to true and "value" to false | |
Static Public Member Functions | |
static DLLLOCAL const char * | getStaticTypeName () |
returns the type name | |
Protected Member Functions | |
virtual DLLEXPORT bool | derefImpl (ExceptionSink *xsink) |
dereferences all elements of the hash | |
virtual DLLEXPORT AbstractQoreNode * | evalImpl (ExceptionSink *xsink) const |
evaluates the object and returns a value (or 0) | |
virtual DLLLOCAL AbstractQoreNode * | evalImpl (bool &needs_deref, ExceptionSink *xsink) const |
optionally evaluates the argument | |
virtual DLLLOCAL int64 | bigIntEvalImpl (ExceptionSink *xsink) const |
always returns 0 | |
virtual DLLLOCAL int | integerEvalImpl (ExceptionSink *xsink) const |
always returns 0 | |
virtual DLLLOCAL bool | boolEvalImpl (ExceptionSink *xsink) const |
always returns false | |
virtual DLLLOCAL double | floatEvalImpl (ExceptionSink *xsink) const |
always returns 0.0 | |
virtual DLLEXPORT | ~QoreHashNode () |
deletes the object, cannot be called directly (use deref(ExceptionSink *) instead) | |
Protected Attributes | |
struct qore_hash_private * | priv |
private implementation of the class | |
Friends | |
class | HashIterator |
class | ConstHashIterator |
This is the hash or associative list container type in Qore, dynamically allocated only, reference counted.
it is both a value type and can hold parse expressions as well (in which case it needs to be evaluated) This type also maintains the insertion order as well as offering a hash-based lookup of string keys. The insertion order of keys is maintained in order to support consistent serialization and deserialization to and from XML and JSON (and possibly others in the future).
virtual DLLEXPORT QoreHashNode::~QoreHashNode | ( | ) | [protected, virtual] |
deletes the object, cannot be called directly (use deref(ExceptionSink *) instead)
DLLEXPORT bool QoreHashNode::compareHard | ( | const QoreHashNode * | h, | |
ExceptionSink * | xsink | |||
) | const |
does a deep "hard" compare of all hash elements (no type conversions are performed) and returns true if the hashes are equal
DLLEXPORT bool QoreHashNode::compareSoft | ( | const QoreHashNode * | h, | |
ExceptionSink * | xsink | |||
) | const |
does a deep "soft" compare of all hash elements (types may be converted for the comparison) and returns true if the hashes are equal
DLLEXPORT QoreHashNode* QoreHashNode::copy | ( | ) | const |
performs a deep copy of the hash and returns the new hash
DLLEXPORT void QoreHashNode::deleteKey | ( | const char * | key, | |
ExceptionSink * | xsink | |||
) |
performs a delete operation on the value of the given key
the delete operation means a simple dereference for all types except QoreObject, on this type the destructor will be run immediately
key | the key of the value to delete | |
xsink | if an error occurs, the Qore-language exception information will be added here |
DLLEXPORT void QoreHashNode::deleteKey | ( | const QoreString * | key, | |
ExceptionSink * | xsink | |||
) |
performs a delete operation on the value of the given key
The delete operation means a simple dereference for all types except QoreObject, on this type the destructor will be run immediately. A Qore-language exception could occur eitherin converting the key string's encoding to QCS_DEFAULT, or in the destructor of a deleted object.
key | the key of the value to delete | |
xsink | if an error occurs, the Qore-language exception information will be added here |
virtual DLLEXPORT bool QoreHashNode::derefImpl | ( | ExceptionSink * | xsink | ) | [protected, virtual] |
dereferences all elements of the hash
The ExceptionSink argument is needed for those types that could throw an exception when they are deleted (ex: QoreObject) - which could be contained in the hash
xsink | if an error occurs, the Qore-language exception information will be added here |
Reimplemented from AbstractQoreNode.
DLLEXPORT bool QoreHashNode::empty | ( | ) | const |
returns true if the hash has no members, false if not
virtual DLLLOCAL AbstractQoreNode* QoreHashNode::evalImpl | ( | bool & | needs_deref, | |
ExceptionSink * | xsink | |||
) | const [protected, virtual] |
optionally evaluates the argument
return value requires a deref(xsink) if needs_deref is true
Implements AbstractQoreNode.
virtual DLLEXPORT AbstractQoreNode* QoreHashNode::evalImpl | ( | ExceptionSink * | xsink | ) | const [protected, virtual] |
evaluates the object and returns a value (or 0)
return value requires a deref(xsink) if the object requires evaluation and there is an exception, 0 will be returned
Implements AbstractQoreNode.
DLLEXPORT bool QoreHashNode::existsKey | ( | const char * | key | ) | const |
returns true if the hash contains the given key
key | the key name to check, must be in default encoding QCS_DEFAULT |
DLLEXPORT bool QoreHashNode::existsKeyValue | ( | const char * | key | ) | const |
returns true if the hash contains the given key and the key has a value (i.e. is not NOTHING)
key | the key name to check, must be in default encoding QCS_DEFAULT |
virtual DLLEXPORT QoreString* QoreHashNode::getAsString | ( | bool & | del, | |
int | foff, | |||
ExceptionSink * | xsink | |||
) | const [virtual] |
returns a QoreString giving the verbose string representation of the List (including all contained values)
used for n and N printf formatting
del | if this is true when the function returns, then the returned QoreString pointer should be deleted, if false, then it must not be | |
foff | for multi-line formatting offset, -1 = no line breaks | |
xsink | if an error occurs, the Qore-language exception information will be added here NOTE: Use the QoreNodeAsStringHelper class (defined in QoreStringNode.h) instead of using this function directly |
Implements AbstractQoreNode.
virtual DLLEXPORT int QoreHashNode::getAsString | ( | QoreString & | str, | |
int | foff, | |||
ExceptionSink * | xsink | |||
) | const [virtual] |
concatenate the verbose string representation of the list (including all contained values) to an existing QoreString
used for n and N printf formatting
str | the string representation of the type will be concatenated to this QoreString reference | |
foff | for multi-line formatting offset, -1 = no line breaks | |
xsink | if an error occurs, the Qore-language exception information will be added here |
Implements AbstractQoreNode.
DLLEXPORT AbstractQoreNode** QoreHashNode::getExistingValuePtr | ( | const char * | key | ) |
returns a pointer to a pointer of the value of the key (assumed to be be in QCS_DEFAULT), only if the key already exists
key | the key to return the pointer to the value pointer for |
DLLEXPORT AbstractQoreNode** QoreHashNode::getExistingValuePtr | ( | const QoreString * | key, | |
ExceptionSink * | xsink | |||
) |
returns a pointer to a pointer of the value of the key only if the key already exists
Converts "key" to the default character encoding (QCS_DEFAULT) if necessary. An exception could be thrown if the character encoding conversion fails.
key | the key to return the pointer to the value pointer for | |
xsink | if an error occurs, the Qore-language exception information will be added here |
DLLEXPORT const char* QoreHashNode::getFirstKey | ( | ) | const |
returns the cstring value of the first key in the hash
DLLEXPORT int64 QoreHashNode::getKeyAsBigInt | ( | const char * | key, | |
bool & | found | |||
) | const |
returns the value of the key as an int64
key | the key to return the value for | |
found | returns as true if the key exists, false if not |
DLLEXPORT QoreListNode* QoreHashNode::getKeys | ( | ) | const |
returns a QoreListNode of QoreStringNodes representing all keys in the hash, caller owns the reference count returned
to iterate through a hash, use HashIterator or ConstHashIterator
DLLEXPORT const AbstractQoreNode* QoreHashNode::getKeyValue | ( | const char * | key | ) | const |
returns the value of the key (assumed to be in QCS_DEFAULT) if it exists
key | the key to return the value for |
DLLEXPORT AbstractQoreNode* QoreHashNode::getKeyValue | ( | const char * | key | ) |
returns the value of the key (assumed to be in QCS_DEFAULT) if it exists
key | the key to return the value for |
DLLEXPORT const AbstractQoreNode* QoreHashNode::getKeyValue | ( | const QoreString * | key, | |
ExceptionSink * | xsink | |||
) | const |
returns the value of the key if it exists
Converts "key" to the default character encoding (QCS_DEFAULT) if necessary. An exception could be thrown if the character encoding conversion fails.
key | the key to return the value for | |
xsink | if an error occurs, the Qore-language exception information will be added here |
DLLEXPORT AbstractQoreNode* QoreHashNode::getKeyValue | ( | const QoreString * | key, | |
ExceptionSink * | xsink | |||
) |
returns the value of the key if it exists
Converts "key" to the default character encoding (QCS_DEFAULT) if necessary. An exception could be thrown if the character encoding conversion fails.
key | the key to return the value for | |
xsink | if an error occurs, the Qore-language exception information will be added here |
DLLEXPORT const AbstractQoreNode* QoreHashNode::getKeyValueExistence | ( | const QoreString * | key, | |
bool & | exists, | |||
ExceptionSink * | xsink | |||
) | const |
returns the value of the key if it exists and sets "exists" accordingly
Converts "key" to the default character encoding (QCS_DEFAULT) if necessary. An exception could be thrown if the character encoding conversion fails.
key | the key to return the value for | |
exists | output parameter: if true the key exists, if false the key does not exists (in this case the return value will always be 0) | |
xsink | if an error occurs, the Qore-language exception information will be added here |
DLLEXPORT AbstractQoreNode* QoreHashNode::getKeyValueExistence | ( | const QoreString * | key, | |
bool & | exists, | |||
ExceptionSink * | xsink | |||
) |
returns the value of the key if it exists and sets "exists" accordingly
Converts "key" to the default character encoding (QCS_DEFAULT) if necessary. An exception could be thrown if the character encoding conversion fails.
key | the key to return the value for | |
exists | output parameter: if true the key exists, if false the key does not exists (in this case the return value will always be 0) | |
xsink | if an error occurs, the Qore-language exception information will be added here |
DLLEXPORT const AbstractQoreNode* QoreHashNode::getKeyValueExistence | ( | const char * | key, | |
bool & | exists | |||
) | const |
returns the value of the key (assumed to be in QCS_DEFAULT) if it exists and sets "exists" accordingly
key | the key to return the value for | |
exists | output parameter: if true the key exists, if false the key does not exists (in this case the return value will always be 0) |
DLLEXPORT AbstractQoreNode* QoreHashNode::getKeyValueExistence | ( | const char * | key, | |
bool & | exists | |||
) |
returns the value of the key (assumed to be in QCS_DEFAULT) if it exists and sets "exists" accordingly
key | the key to return the value for | |
exists | output parameter: if true the key exists, if false the key does not exists (in this case the return value will always be 0) |
DLLEXPORT AbstractQoreNode** QoreHashNode::getKeyValuePtr | ( | const char * | key | ) |
returns a pointer to a pointer of the value of the key (assumed to be in QCS_DEFAULT) so the value may be set or changed externally
The key hash entry is created if it does not already exist.
key | the key to return the pointer to the value pointer for |
DLLEXPORT AbstractQoreNode** QoreHashNode::getKeyValuePtr | ( | const QoreString * | key, | |
ExceptionSink * | xsink | |||
) |
returns a pointer to a pointer of the value of the key so the value may be set or changed externally
Converts "key" to the default character encoding (QCS_DEFAULT) if necessary. An exception could be thrown if the character encoding conversion fails. The key hash entry is created if it does not already exist.
key | the key to return the pointer to the value pointer for | |
xsink | if an error occurs, the Qore-language exception information will be added here |
DLLEXPORT const char* QoreHashNode::getLastKey | ( | ) | const |
returns the cstring value of the last key in the hash
static DLLLOCAL const char* QoreHashNode::getStaticTypeName | ( | ) | [inline, static] |
returns the type name
virtual DLLEXPORT const char* QoreHashNode::getTypeName | ( | ) | const [virtual] |
returns the type name as a c string
Implements AbstractQoreNode.
DLLEXPORT QoreHashNode* QoreHashNode::hashRefSelf | ( | ) | const |
returns "this" with an incremented reference count
virtual DLLEXPORT bool QoreHashNode::is_equal_hard | ( | const AbstractQoreNode * | v, | |
ExceptionSink * | xsink | |||
) | const [virtual] |
tests for equality ("deep compare" including all contained values) without type conversions (hard compare)
v | the value to compare | |
xsink | if an error occurs, the Qore-language exception information will be added here |
virtual DLLEXPORT bool QoreHashNode::is_equal_soft | ( | const AbstractQoreNode * | v, | |
ExceptionSink * | xsink | |||
) | const [virtual] |
tests for equality ("deep compare" including all contained values) with possible type conversion (soft compare)
v | the value to compare | |
xsink | if an error occurs, the Qore-language exception information will be added here |
DLLEXPORT void QoreHashNode::merge | ( | const QoreHashNode * | h, | |
ExceptionSink * | xsink | |||
) |
appends all key-value pairs of "h" to this hash
Note that all keys and values of the QoreHashNode "h" are copied to this hash, values are referenced as necessary for the assigment to "this". Qore-language exceptions could be thrown if the hash keys in "this" are overwritten with new values and the old value is an object that goes out of scope when dereferenced.
h | the QoreHashNode to use to merge all keys to "this" | |
xsink | if an error occurs, the Qore-language exception information will be added here |
virtual DLLEXPORT AbstractQoreNode* QoreHashNode::realCopy | ( | ) | const [virtual] |
performs a deep copy of the hash and returns the new hash
Implements AbstractQoreNode.
DLLEXPORT void QoreHashNode::removeKey | ( | const char * | key, | |
ExceptionSink * | xsink | |||
) |
removes the given key from the hash and derefences its value, if any
A Qore-language exception could occur when dereferencing the contained value
key | the key of the value to delete, must be in QCS_DEFAULT encoding | |
xsink | if an error occurs, the Qore-language exception information will be added here |
DLLEXPORT void QoreHashNode::removeKey | ( | const QoreString * | key, | |
ExceptionSink * | xsink | |||
) |
removes the given key from the hash and derefences its value, if any
A Qore-language exception could occur either in converting the key string's encoding to QCS_DEFAULT, or when dereferencing the contained value
key | the key of the value to delete | |
xsink | if an error occurs, the Qore-language exception information will be added here |
DLLEXPORT void QoreHashNode::setKeyValue | ( | const char * | key, | |
AbstractQoreNode * | value, | |||
ExceptionSink * | xsink | |||
) |
sets the value of "key" to "value"
A Qore-language exception could be thrown if the given key has a current value and it's a QoreObject that goes out of scope when dereferenced (the object's destructor could throw an exception).
key | the key to set the value for (assumed to be in QCS_DEFAULT encoding) | |
value | the value to assign to the key, must be already referenced for the assignment | |
xsink | if an error occurs, the Qore-language exception information will be added here |
DLLEXPORT void QoreHashNode::setKeyValue | ( | const QoreString * | key, | |
AbstractQoreNode * | value, | |||
ExceptionSink * | xsink | |||
) |
sets the value of "key" to "value"
A Qore-language exception could be thrown converting the key string's encoding to QCS_DEFAULT, or if the given key has a current value and it's a QoreObject that goes out of scope when dereferenced (the object's destructor could throw an exception)
key | the key to set the value for | |
value | the value to assign to the key, must be already referenced for the assignment | |
xsink | if an error occurs, the Qore-language exception information will be added here |
DLLEXPORT qore_size_t QoreHashNode::size | ( | ) | const |
returns the number of members in the hash, executes in constant time
DLLEXPORT AbstractQoreNode* QoreHashNode::swapKeyValue | ( | const char * | key, | |
AbstractQoreNode * | value | |||
) |
sets the value of "key" to "value" and returns the old value (0 if not present or if already 0), caller owns any reference count returned
key | the key to set the value for (assumed to be in QCS_DEFAULT encoding) | |
value | the value to assign to the key, must be already referenced for the assignment |
DLLEXPORT AbstractQoreNode* QoreHashNode::swapKeyValue | ( | const QoreString * | key, | |
AbstractQoreNode * | value, | |||
ExceptionSink * | xsink | |||
) |
sets the value of "key" to "value" and returns the old value (0 if not present or if already 0), caller owns any reference count returned
A Qore-language exception could be thrown converting the key string's encoding to QCS_DEFAULT
key | the key to set the value for | |
value | the value to assign to the key, must be already referenced for the assignment | |
xsink | if an error occurs, the Qore-language exception information will be added here |
DLLEXPORT AbstractQoreNode* QoreHashNode::takeKeyValue | ( | const char * | key | ) |
"takes" the value of the key from the hash and removes the key from the hash and returns the value, caller owns the reference count returned
key | the key of the value to return |
DLLEXPORT AbstractQoreNode* QoreHashNode::takeKeyValue | ( | const QoreString * | key, | |
ExceptionSink * | xsink | |||
) |
"takes" the value of the key from the hash and removes the key from the hash and returns the value, caller owns the reference count returned
key | the key of the value to return | |
xsink | if an error occurs converting the key string to QCS_DEFAULT encoding, the Qore-language exception information will be added here |