All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
QoreHashNode Class Reference

This is the hash or associative list container type in Qore, dynamically allocated only, reference counted. More...

`#include <QoreHashNode.h>`

Inheritance diagram for QoreHashNode:
[legend]
Collaboration diagram for QoreHashNode:
[legend]

## Public Member Functions

DLLEXPORT | QoreHashNode ()
| creates an empty hash
DLLLOCAL void | clearNeedsEval ()
| sets "needs_eval" to false and "value" to true
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 More...
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 More...
DLLEXPORT QoreHashNode * | copy () const
| performs a copy of the hash and returns the new hash More...
DLLEXPORT void | deleteKey (const QoreString *key, ExceptionSink *xsink)
| performs a delete operation on the value of the given key More...
DLLEXPORT void | deleteKey (const char *key, ExceptionSink *xsink)
| performs a delete operation on the value of the given key More...
DLLEXPORT bool | empty () const
| returns true if the hash has no members, false if not More...
DLLEXPORT bool | existsKey (const char *key) const
| returns true if the hash contains the given key More...
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) More...
virtual DLLEXPORT bool | getAsBoolImpl () const
| returns false unless perl-boolean-evaluation is enabled, in which case it returns false only when empty More...
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 More...
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) More...
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 More...
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 More...
DLLEXPORT const char * | getFirstKey () const
| returns the cstring value of the first key in the hash More...
DLLEXPORT int64 | getKeyAsBigInt (const char *key, bool &found) const
| returns the value of the key as an int64 More...
DLLEXPORT bool | getKeyAsBool (const char *key, bool &found) const
| returns the value of the key as a bool More...
DLLEXPORT QoreListNode * | getKeys () const
| returns a QoreListNode of QoreStringNodes representing all keys in the hash, caller owns the reference count returned More...
DLLEXPORT AbstractQoreNode * | getKeyValue (const QoreString *key, ExceptionSink *xsink)
| returns the value of the key if it exists More...
DLLEXPORT AbstractQoreNode * | getKeyValue (const QoreString &key, ExceptionSink *xsink)
| returns the value of the key if it exists More...
DLLEXPORT const AbstractQoreNode * | getKeyValue (const QoreString *key, ExceptionSink *xsink) const
| returns the value of the key if it exists More...
DLLEXPORT AbstractQoreNode * | getKeyValue (const char *key)
| returns the value of the key (assumed to be in QCS_DEFAULT) if it exists More...
DLLEXPORT const AbstractQoreNode * | getKeyValue (const char *key) const
| returns the value of the key (assumed to be in QCS_DEFAULT) if it exists More...
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 More...
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 More...
DLLEXPORT AbstractQoreNode * | getKeyValueExistence (const QoreString *key, bool &exists, ExceptionSink *xsink)
| returns the value of the key if it exists and sets "exists" accordingly More...
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 More...
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 More...
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 More...
DLLEXPORT const char * | getLastKey () const
| returns the cstring value of the last key in the hash More...
virtual DLLEXPORT const char * | getTypeName () const
| returns the type name as a c string More...
DLLEXPORT QoreHashNode * | hashRefSelf () const
| returns "this" with an incremented reference count More...
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) More...
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) More...
DLLEXPORT void | merge (const QoreHashNode *h, ExceptionSink *xsink)
| appends all key-value pairs of "h" to this hash More...
virtual DLLLOCAL AbstractQoreNode * | parseInit (LocalVar *oflag, int pflag, int &lvids, const QoreTypeInfo *&typeInfo)
| initializes during parsing
virtual DLLEXPORT AbstractQoreNode * | realCopy () const
| performs a copy of the hash and returns the new hash More...
DLLEXPORT void | removeKey (const QoreString *key, ExceptionSink *xsink)
| removes the given key from the hash and derefences its value, if any More...
DLLEXPORT void | removeKey (const char *key, ExceptionSink *xsink)
| removes the given key from the hash and derefences its value, if any More...
DLLEXPORT void | setKeyValue (const QoreString *key, AbstractQoreNode *value, ExceptionSink *xsink)
| sets the value of "key" to "value" More...
DLLEXPORT void | setKeyValue (const QoreString &key, AbstractQoreNode *value, ExceptionSink *xsink)
| sets the value of "key" to "value" More...
DLLEXPORT void | setKeyValue (const char *key, AbstractQoreNode *value, ExceptionSink *xsink)
| sets the value of "key" to "value" More...
DLLLOCAL void | setNeedsEval ()
| sets "needs_eval" to true and "value" to false
DLLEXPORT qore_size_t | size () const
| returns the number of members in the hash, executes in constant time More...
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 More...
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 More...
DLLEXPORT AbstractQoreNode * | swapKeyValue (const char *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 More...
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 More...
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 More...
Public Member Functions inherited from AbstractQoreNode
DLLEXPORT | AbstractQoreNode (qore_type_t t, bool n_value, bool n_needs_eval, bool n_there_can_be_only_one=false, bool n_custom_reference_handlers=false)
| constructor takes the type More...
DLLEXPORT | AbstractQoreNode (const AbstractQoreNode &v)
| copy constructor
DLLEXPORT int64 | bigIntEval (ExceptionSink *xsink) const
| evaluates the object and returns a 64-bit integer value More...
DLLEXPORT bool | boolEval (ExceptionSink *xsink) const
| evaluates the object and returns a boolean value More...
DLLEXPORT void | deref (ExceptionSink *xsink)
| decrements the reference count and calls derefImpl() if there_can_be_only_one is false, otherwise does nothing More...
DLLEXPORT AbstractQoreNode * | eval (ExceptionSink *xsink) const
| evaluates the object and returns a value (or 0) More...
DLLEXPORT AbstractQoreNode * | eval (bool &needs_deref, ExceptionSink *xsink) const
| optionally evaluates the argument More...
DLLEXPORT double | floatEval (ExceptionSink *xsink) const
| evaluates the object and returns a floating-point value More...
DLLEXPORT int64 | getAsBigInt () const
| returns the 64-bit integer value of the object More...
DLLEXPORT bool | getAsBool () const
| returns the boolean value of the object More...
DLLEXPORT double | getAsFloat () const
| returns the float value of the object More...
DLLEXPORT int | getAsInt () const
| returns the integer value of the object More...
virtual DLLEXPORT class DateTime * | getDateTimeRepresentation (bool &del) const
| returns the DateTime representation of this type (default implementation: returns ZeroDate, del = false) More...
virtual DLLEXPORT void | getDateTimeRepresentation (DateTime &dt) const
| assigns the date representation of a value to the DateTime reference passed, default implementation does nothing More...
virtual DLLEXPORT QoreString * | getStringRepresentation (bool &del) const
| returns the value of the type converted to a string, default implementation: returns the empty string More...
virtual DLLEXPORT void | getStringRepresentation (QoreString &str) const
| concatentates the value of the type to an existing QoreString reference, default implementation does nothing More...
DLLLOCAL qore_type_t | getType () const
| returns the data type More...
DLLLOCAL bool | hasValueApi () const
| returns the "has value api" flags - FIXME: remove with new ABI
DLLEXPORT int | integerEval (ExceptionSink *xsink) const
| evaluates the object and returns an integer value More...
DLLLOCAL bool | is_value () const
| returns true if the node represents a value More...
DLLLOCAL bool | isReferenceCounted () const
| returns true if the object is reference-counted
DLLLOCAL bool | needs_eval () const
| returns true if the object needs evaluation to return a value, false if not More...
DLLEXPORT void | ref () const
| increments the reference count
DLLEXPORT AbstractQoreNode * | refSelf () const
| returns "this" with an incremented reference count More...
Public Member Functions inherited from QoreReferenceCounter
DLLEXPORT | QoreReferenceCounter ()
| creates the reference counter object
DLLEXPORT | ~QoreReferenceCounter ()
| destroys the reference counter object
DLLLOCAL bool | is_unique () const
| returns true if the reference count is 1 More...
DLLLOCAL int | reference_count () const
| gets the reference count More...
DLLEXPORT bool | ROdereference () const
| atomically decrements the reference count More...
DLLEXPORT void | ROreference () const
| atomically increments the reference count

## Static Public Member Functions

static DLLLOCAL qore_type_t | getStaticTypeCode ()
| returns the type code (useful in templates)
static DLLLOCAL const char * | getStaticTypeName ()
| returns the type name (useful in templates) More...

## Protected Member Functions

virtual DLLEXPORT | ~QoreHashNode ()
| deletes the object, cannot be called directly (use deref(ExceptionSink*) instead) More...
virtual DLLLOCAL int64 | bigIntEvalImpl (ExceptionSink *xsink) const
| always returns 0
virtual DLLLOCAL bool | boolEvalImpl (ExceptionSink *xsink) const
| always returns false
virtual DLLEXPORT bool | derefImpl (ExceptionSink *xsink)
| dereferences all elements of the hash More...
virtual DLLEXPORT AbstractQoreNode * | evalImpl (ExceptionSink *xsink) const
| evaluates the object and returns a value (or 0) More...
virtual DLLLOCAL AbstractQoreNode * | evalImpl (bool &needs_deref, ExceptionSink *xsink) const
| optionally evaluates the argument More...
virtual DLLLOCAL double | floatEvalImpl (ExceptionSink *xsink) const
| always returns 0.0
virtual DLLLOCAL int | integerEvalImpl (ExceptionSink *xsink) const
| always returns 0
Protected Member Functions inherited from AbstractQoreNode
virtual DLLEXPORT | ~AbstractQoreNode ()
| default destructor does nothing More...

## Protected Attributes

class qore_hash_private * | priv
| private implementation of the class
Protected Attributes inherited from AbstractQoreNode
bool | custom_reference_handlers: 1
| set to one for objects that need custom reference handlers
bool | has_value_api: 1
| set to flag with new QoreValue API (derived from ParseNode) - FIXME: to be removed when new ABI is implemented
bool | needs_eval_flag: 1
| if this is true then the type can be evaluated
bool | there_can_be_only_one: 1
| if this is set to true, then reference counting is turned off for objects of this class
qore_type_t | type: 11
| the type of the object More...
bool | value: 1
| this is true for values, if false then either the type needs evaluation to produce a value or is a parse expression
Protected Attributes inherited from QoreReferenceCounter
QoreThreadLock | mRO
| pthread lock to ensure atomicity of updates for architectures where we don't have an atomic increment and decrement implementation

## Friends

class | ConstHashIterator
class | HashAssignmentHelper
class | HashIterator
class | ReverseConstHashIterator
class | ReverseHashIterator

## Detailed Description

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, JSON, YAML, etc

## Constructor & Destructor Documentation

virtual DLLEXPORT QoreHashNode::~QoreHashNode | ( |  | ) |

protected virtual

deletes the object, cannot be called directly (use deref(ExceptionSink*) instead)

See Also
  AbstractQoreNode::deref()
  QoreHashNode::derefImpl()

## Member Function Documentation

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

Note
  that if the hashes have a different number of keys then the comparison fails immediately

Returns
  true if the hashes have the same number and values of keys and all elements are equal and of the same type (no type conversions are performed)

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

Note
  that if the hashes have a different number or names of keys then the comparison fails immediately

Returns
  true if the hashes have the same number and names of keys and all elements are equal (types may be converted for the comparison)

DLLEXPORT QoreHashNode* QoreHashNode::copy | ( |  | ) | const

performs a copy of the hash and returns the new hash

Returns
  a copy of the current QoreHashNode

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.

Parameters

  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 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

Parameters

  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

Parameters

  xsink | if an error occurs, the Qore-language exception information will be added here

Returns
  true if the object can be deleted, false if not (externally-managed)

Reimplemented from AbstractQoreNode.

DLLEXPORT bool QoreHashNode::empty | ( |  | ) | const

returns true if the hash has no members, false if not

Returns
  true if the hash has no members, false if not

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.

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

See Also
  AbstractQoreNode::eval()

Implements AbstractQoreNode.

DLLEXPORT bool QoreHashNode::existsKey | ( | const char * | key | ) | const

returns true if the hash contains the given key

Note
  that if this returns true, it does not mean the key has a value; it just means that the hash contains the key; the key's value could be NOTHING

Parameters

  key | the key name to check, must be in default encoding QCS_DEFAULT

Returns
  true if the hash contains the given key

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)

Parameters

  key | the key name to check, must be in default encoding QCS_DEFAULT

Returns
  true if the hash contains the given key and the key has a value

virtual DLLEXPORT bool QoreHashNode::getAsBoolImpl | ( |  | ) | const

virtual

returns false unless perl-boolean-evaluation is enabled, in which case it returns false only when empty

Returns
  false unless perl-boolean-evaluation is enabled, in which case it returns false only when empty

Reimplemented from 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

Parameters

  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

Returns
  -1 for exception raised, 0 = OK

Implements AbstractQoreNode.

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

Parameters

  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

See Also
  QoreNodeAsStringHelper

Implements AbstractQoreNode.

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.

Parameters

  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

Returns
  a pointer to a pointer of the value of the key, only if the key already exists, otherwise 0 is returned

Deprecated:
  use HashAssignmentHelper instead; using this function could result in a memory leak

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

Parameters

  key | the key to return the pointer to the value pointer for

Returns
  a pointer to a pointer of the value of the key (assumed to be in QCS_DEFAULT), only if the key already exists, otherwise 0 is returned

Deprecated:
  use HashAssignmentHelper instead; using this function could result in a memory leak

DLLEXPORT const char* QoreHashNode::getFirstKey | ( |  | ) | const

returns the cstring value of the first key in the hash

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

Parameters

  key | the key to return the value for
  found | returns as true if the key exists, false if not

Returns
  the value of the key as an int64

DLLEXPORT bool QoreHashNode::getKeyAsBool | ( | const char * | key,
|  | bool & | found
| ) |  | const

returns the value of the key as a bool

Parameters

  key | the key to return the value for
  found | returns as true if the key exists, false if not

Returns
  the value of the key as a bool

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, ReverseHashIterator, ConstHashIterator, or ReverseConstHashIterator

Returns
  a QoreListNode of QoreStringNodes representing all keys in the hash, caller owns the reference count returned

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.

Parameters

  key | the key to return the value for
  xsink | if an error occurs, the Qore-language exception information will be added here

Returns
  the value of the key

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.

Parameters

  key | the key to return the value for
  xsink | if an error occurs, the Qore-language exception information will be added here

Returns
  the value of the key

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.

Parameters

  key | the key to return the value for
  xsink | if an error occurs, the Qore-language exception information will be added here

Returns
  the value of the key

DLLEXPORT AbstractQoreNode* QoreHashNode::getKeyValue | ( | const char * | key | ) |

returns the value of the key (assumed to be in QCS_DEFAULT) if it exists

Parameters

  key | the key to return the value for

Returns
  the value of the key

DLLEXPORT const AbstractQoreNode* QoreHashNode::getKeyValue | ( | const char * | key | ) | const

returns the value of the key (assumed to be in QCS_DEFAULT) if it exists

Parameters

  key | the key to return the value for

Returns
  the value of the key

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

Parameters

  key | the key to return the value for
  exists | output parameter: if true the key exists, if false the key does not exist (in this case the return value will always be 0)

Returns
  the value of the key

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

Parameters

  key | the key to return the value for
  exists | output parameter: if true the key exists, if false the key does not exist (in this case the return value will always be 0)

Returns
  the value of the key

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.

Parameters

  key | the key to return the value for
  exists | output parameter: if true the key exists, if false the key does not exist (in this case the return value will always be 0)
  xsink | if an error occurs, the Qore-language exception information will be added here

Returns
  the value of the key

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.

Parameters

  key | the key to return the value for
  exists | output parameter: if true the key exists, if false the key does not exist (in this case the return value will always be 0)
  xsink | if an error occurs, the Qore-language exception information will be added here

Returns
  the value of the key

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.

Parameters

  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

Returns
  a pointer to a pointer of the value of the key

Deprecated:
  use HashAssignmentHelper instead; using this function could result in a memory leak

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.

Parameters

  key | the key to return the pointer to the value pointer for

Returns
  a pointer to a pointer of the value of the key (assumed to be in QCS_DEFAULT)

Deprecated:
  use HashAssignmentHelper instead; using this function could result in a memory leak

DLLEXPORT const char* QoreHashNode::getLastKey | ( |  | ) | const

returns the cstring value of the last key in the hash

Returns
  the cstring value of the last key in the hash

static DLLLOCAL const char* QoreHashNode::getStaticTypeName | ( |  | ) |

inline static

returns the type name (useful in templates)

Returns
  the type name

virtual DLLEXPORT const char* QoreHashNode::getTypeName | ( |  | ) | const

virtual

returns the type name as a c string

Returns
  the type name as a c string

Implements AbstractQoreNode.

DLLEXPORT QoreHashNode* QoreHashNode::hashRefSelf | ( |  | ) | const

returns "this" with an incremented reference count

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)

Parameters

  v | the value to compare
  xsink | if an error occurs, the Qore-language exception information will be added here

Implements AbstractQoreNode.

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)

Parameters

  v | the value to compare
  xsink | if an error occurs, the Qore-language exception information will be added here

Implements AbstractQoreNode.

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.

Parameters

  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 copy of the hash and returns the new hash

Returns
  a copy of the QoreHashNode

Implements AbstractQoreNode.

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

Parameters

  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::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

Parameters

  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::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); if an exception is thrown due to encoding conversion issues (and therefore the assignment is not made) then the value to be assigned is dereferenced automatically

Parameters

  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

Note
  the assignment is made even if an exception occurs when dereferencing the old value

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); if an exception is thrown due to encoding conversion issues (and therefore the assignment is not made) then the value to be assigned is dereferenced automatically

Parameters

  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

Note
  the assignment is made even if an exception occurs when dereferencing the old value

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).

Parameters

  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

Note
  the assignment is made even if an exception occurs when dereferencing the old value

DLLEXPORT qore_size_t QoreHashNode::size | ( |  | ) | const

returns the number of members in the hash, executes in constant time

Returns
  the number of members in the hash

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; if an exception is thrown and the value is not assigned, then the value to be assigned is dereferenced automatically

Parameters

  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

Returns
  the old value of the key (0 if not present or if the old value was already 0), caller owns any reference count returned

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

Parameters

  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

Returns
  the old value of the key (0 if not present or if the old value was already 0), caller owns any reference count returned

Deprecated:
  this api could cause a crash if types are implemented for hash keys and the value to be assigned cannot be assigned; this API will be removed in a future version of the Qore library

DLLEXPORT AbstractQoreNode* QoreHashNode::swapKeyValue | ( | const char * | 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; if an exception is thrown and the value is not assigned, then the value to be assigned is dereferenced automatically

Parameters

  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 (currently no exceptions can be raised with this version of qore)

Returns
  the old value of the key (0 if not present or if the old value was already 0), caller owns any reference count returned

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

Parameters

  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

Returns
  the value of the key, caller owns the reference count returned

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

Parameters

  key | the key of the value to return

Returns
  the value of the key, caller owns the reference count returned

The documentation for this class was generated from the following file:

- include/qore/QoreHashNode.h (6de6cc3b438610bf03b2bec44a3d7c61f90e3165)