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

#include <QoreHashNode.h>

Inheritance diagram for QoreHashNode:

Collaboration diagram for QoreHashNode:

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

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

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

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation