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
virtual DLLEXPORT bool | getAsBoolImpl () const
| returns false unless perl-boolean-evaluation is enabled, in which case it returns false only when empty
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 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 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 bool | getKeyAsBool (const char *key, bool &found) const
| returns the value of the key as a bool
DLLEXPORT QoreHashNode * | copy () const
| performs a 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 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 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
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
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
DLLEXPORT | AbstractQoreNode (const AbstractQoreNode &v)
| copy constructor
DLLEXPORT bool | getAsBool () const
| returns the boolean value of the object
DLLEXPORT int | getAsInt () const
| returns the integer value of the object
DLLEXPORT int64 | getAsBigInt () const
| returns the 64-bit integer value of the object
DLLEXPORT double | getAsFloat () const
| returns the float value of the object
virtual DLLEXPORT QoreString * | getStringRepresentation (bool &del) const
| returns the value of the type converted to a string, default implementation: returns the empty string
virtual DLLEXPORT void | getStringRepresentation (QoreString &str) const
| concatentates the value of the type to an existing QoreString reference, default implementation does nothing
virtual DLLEXPORT class DateTime * | getDateTimeRepresentation (bool &del) const
| returns the DateTime representation of this type (default implementation: returns ZeroDate, del = false)
virtual DLLEXPORT void | getDateTimeRepresentation (DateTime &dt) const
| assigns the date representation of a value to the DateTime reference passed, default implementation does nothing
DLLLOCAL bool | needs_eval () const
| returns true if the object needs evaluation to return a value, false if not
DLLLOCAL qore_type_t | getType () const
| returns the data type
DLLEXPORT AbstractQoreNode * | eval (ExceptionSink *xsink) const
| evaluates the object and returns a value (or 0)
DLLEXPORT AbstractQoreNode * | eval (bool &needs_deref, ExceptionSink *xsink) const
| optionally evaluates the argument
DLLEXPORT int64 | bigIntEval (ExceptionSink *xsink) const
| evaluates the object and returns a 64-bit integer value
DLLEXPORT int | integerEval (ExceptionSink *xsink) const
| evaluates the object and returns an integer value
DLLEXPORT bool | boolEval (ExceptionSink *xsink) const
| evaluates the object and returns a boolean value
DLLEXPORT double | floatEval (ExceptionSink *xsink) const
| evaluates the object and returns a floating-point value
DLLLOCAL bool | is_value () const
| returns true if the node represents a value
DLLEXPORT void | deref (ExceptionSink *xsink)
| decrements the reference count and calls derefImpl() if there_can_be_only_one is false, otherwise does nothing
DLLEXPORT AbstractQoreNode * | refSelf () const
| returns "this" with an incremented reference count
DLLEXPORT void | ref () const
| increments the reference count
DLLLOCAL bool | isReferenceCounted () const
| returns true if the object is reference-counted
Public Member Functions inherited from QoreReferenceCounter
DLLEXPORT | QoreReferenceCounter ()
| creates the reference counter object
DLLEXPORT | ~QoreReferenceCounter ()
| destroys the reference counter object
DLLLOCAL int | reference_count () const
| gets the reference count
DLLLOCAL bool | is_unique () const
| returns true if the reference count is 1
DLLEXPORT void | ROreference () const
| atomically increments the reference count
DLLEXPORT bool | ROdereference () const
| atomically decrements the reference count

## Static Public Member Functions

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

## 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 Member Functions inherited from AbstractQoreNode
virtual DLLEXPORT | ~AbstractQoreNode ()
| default destructor does nothing

## Protected Attributes

class qore_hash_private * | priv
| private implementation of the class
Protected Attributes inherited from AbstractQoreNode
qore_type_t | type: 11
| the type of the object
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
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
bool | custom_reference_handlers: 1
| set to one for objects that need custom reference handlers
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 | HashIterator
class | ReverseHashIterator
class | ConstHashIterator
class | ReverseConstHashIterator
class | HashAssignmentHelper

## 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 | ( |  | ) |

protectedvirtual

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

protectedvirtual

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

protectedvirtual

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

protectedvirtual

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

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

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

inlinestatic

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 (5431)