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 Methods
DLLEXPORT	QoreHashNode ()
	creates an empty hash

DLLEXPORT	QoreHashNode (const QoreTypeInfo *valueTypeInfo)
	creates an empty hash with the specific value type More...

DLLEXPORT	QoreHashNode (const TypedHashDecl hd, ExceptionSink xsink)
	creates a hash of the specific type; the hash is initialized according to the hashdecl declaration More...

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 char key, ExceptionSink xsink)
	performs a delete operation on the value of the given key More...

DLLEXPORT void	deleteKey (const QoreString 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 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...

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

DLLEXPORT const char *	getFirstKey () const
	returns the cstring value of the first key in the hash More...

DLLEXPORT const TypedHashDecl *	getHashDecl () const
	returns the hash's type declaration, if any 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 QoreStringNode pointers representing all keys in the hash, caller owns the reference count returned More...

DLLEXPORT QoreValue	getKeyValue (const char *key) const
	returns the value of the given key More...

DLLEXPORT QoreValue	getKeyValue (const char key, ExceptionSink xsink) const
	returns the value of the given key More...

DLLEXPORT QoreValue	getKeyValue (const QoreString &key, ExceptionSink *xsink) const
	returns the value of the given key More...

DLLEXPORT QoreValue	getKeyValueExistence (const char *key, bool &exists) const
	returns the value of the given key More...

DLLEXPORT QoreValue	getKeyValueExistence (const char key, bool &exists, ExceptionSink xsink) const
	returns the value of the given key More...

DLLEXPORT QoreValue	getKeyValueExistence (const QoreString &key, bool &exists) const
	returns the value of the given key More...

DLLEXPORT QoreValue	getKeyValueExistence (const QoreString &key, bool &exists, ExceptionSink *xsink) const
	returns the value of the given key More...

DLLEXPORT const char *	getLastKey () const
	returns the cstring value of the last key in the hash More...

DLLEXPORT const QoreTypeInfo *	getTypeInfo () const
	returns the type info structure for the current value; also works for hashes derived from a TypedHashDecl or with a specific value type More...

virtual DLLEXPORT const char *	getTypeName () const
	returns the type name as a c string More...

DLLEXPORT QoreListNode *	getValues () const
	returns a QoreListNode of AbstractQoreNode pointers representing all values in the hash; caller owns the reference count returned More...

DLLEXPORT const QoreTypeInfo *	getValueTypeInfo () const
	returns the value type declaration (only possible if there is no hashdecl set) 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 int	parseInit (QoreValue &val, QoreParseContext &parse_context)
	initializes during parsing

virtual DLLEXPORT AbstractQoreNode *	realCopy () const
	performs a copy of the hash and returns the new hash 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	removeKey (const QoreString key, ExceptionSink xsink)
	removes the given key from the hash and derefences its value, if any More...

DLLEXPORT int	setKeyValue (const char key, QoreValue value, ExceptionSink xsink)
	sets the value of "key" to "value" More...

DLLEXPORT int	setKeyValue (const QoreString &key, QoreValue value, ExceptionSink *xsink)
	sets the value of "key" to "value" More...

DLLLOCAL void	setNeedsEval ()
	sets "needs_eval" to true and "value" to false

DLLEXPORT size_t	size () const
	returns the number of members in the hash, executes in constant time More...

DLLEXPORT QoreValue	takeKeyValue (const char *key)
	removes the value from the hash and returns the value removed, if any

Public Member Methods inherited from AbstractQoreNode
DLLEXPORT	AbstractQoreNode (const AbstractQoreNode &v)
	copy constructor

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

virtual DLLEXPORT void	customDeref (ExceptionSink *xsink)

virtual DLLEXPORT void	customRef () const
	special processing when the object's reference count transitions from 0-1 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 QoreValue	eval (bool &needs_deref, ExceptionSink *xsink) const
	optionally evaluates the argument More...

DLLEXPORT QoreValue	eval (ExceptionSink *xsink) const
	evaluates the object and returns a value (or 0) More...

DLLEXPORT int64	getAsBigInt () const
	returns the 64-bit integer value of the object More...

virtual DLLLOCAL int64	getAsBigIntImpl () const
	default implementation, returns 0 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...

virtual DLLLOCAL double	getAsFloatImpl () const
	default implementation, returns 0.0 More...

DLLEXPORT int	getAsInt () const
	returns the integer value of the object More...

virtual DLLLOCAL int	getAsIntImpl () const
	default implementation, returns 0 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	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...

DLLLOCAL AbstractQoreNode &	operator= (const AbstractQoreNode &)
	this function is not implemented; it is here as a private function in order to prohibit it from being used

DLLEXPORT void	ref () const
	increments the reference count

DLLEXPORT AbstractQoreNode *	refSelf () const
	returns "this" with an incremented reference count More...

Public Member Methods inherited from QoreReferenceCounter
DLLEXPORT	QoreReferenceCounter ()
	creates the reference counter object

DLLEXPORT	QoreReferenceCounter (const QoreReferenceCounter &old)
	creates a new object with a reference count of 1 More...

DLLEXPORT	~QoreReferenceCounter ()
	destroys the reference counter object

DLLEXPORT bool	is_unique () const
	returns true if the reference count is 1 More...

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

Private Member Methods
virtual DLLEXPORT	~QoreHashNode ()
	deletes the object, cannot be called directly (use deref(ExceptionSink*) instead) More...

virtual DLLEXPORT bool	derefImpl (ExceptionSink *xsink)
	dereferences all elements of the hash More...

virtual DLLLOCAL QoreValue	evalImpl (bool &needs_deref, ExceptionSink *xsink) const
	optionally evaluates the argument More...

Private Member Methods inherited from AbstractQoreNode
virtual DLLEXPORT	~AbstractQoreNode ()
	default destructor does nothing More...

Private Attributes
class qore_hash_private *	priv
	private implementation of the class

Private 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

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

◆ ~QoreHashNode()

virtual DLLEXPORT QoreHashNode::~QoreHashNode ( )

privatevirtual

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

See also: AbstractQoreNode::deref(); QoreHashNode::derefImpl()

◆ QoreHashNode() [1/2]

DLLEXPORT QoreHashNode::QoreHashNode	(	const TypedHashDecl *	hd,
		ExceptionSink *	xsink
	)

creates a hash of the specific type; the hash is initialized according to the hashdecl declaration

Since: Qore 0.8.13

◆ QoreHashNode() [2/2]

DLLEXPORT QoreHashNode::QoreHashNode ( const QoreTypeInfo * valueTypeInfo )

creates an empty hash with the specific value type

Since: Qore 0.8.13

Member Function Documentation

◆ compareHard()

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)

◆ compareSoft()

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)

◆ copy()

DLLEXPORT QoreHashNode* QoreHashNode::copy ( ) const

performs a copy of the hash and returns the new hash

Returns: a copy of the current QoreHashNode

◆ deleteKey() [1/2]

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

◆ deleteKey() [2/2]

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

◆ derefImpl()

virtual DLLEXPORT bool QoreHashNode::derefImpl ( ExceptionSink * xsink )

privatevirtual

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.

◆ empty()

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

◆ evalImpl()

virtual DLLLOCAL QoreValue QoreHashNode::evalImpl	(	bool &	needs_deref,
		ExceptionSink *	xsink
	)		const

privatevirtual

optionally evaluates the argument

return value requires a deref(xsink) if needs_deref is true

See also: AbstractQoreNode::eval()

Implements AbstractQoreNode.

◆ existsKey()

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

◆ existsKeyValue()

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

◆ getAsBoolImpl()

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.

◆ getAsString() [1/2]

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.

◆ getAsString() [2/2]

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.

◆ getFirstKey()

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

◆ getHashDecl()

DLLEXPORT const TypedHashDecl* QoreHashNode::getHashDecl ( ) const

returns the hash's type declaration, if any

Since: Qore 0.8.13

◆ getKeyAsBigInt()

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

Deprecated:: use getKeyValue() instead

◆ getKeyAsBool()

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

Deprecated:: use getKeyValue() instead

◆ getKeys()

DLLEXPORT QoreListNode* QoreHashNode::getKeys ( ) const

returns a QoreListNode of QoreStringNode pointers 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 QoreStringNode pointers representing all keys in the hash, caller owns the reference count returned