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:

AbstractQoreNode QoreReferenceCounter

List of all members.

Public Member Functions

DLLEXPORT QoreHashNode ()
 creates an empty hash
virtual DLLEXPORT int getAsString (QoreString &str, int foff, ExceptionSink *xsink) const
 concatenate the verbose string representation of the list (including all contained values) to an existing QoreString
virtual DLLEXPORT QoreStringgetAsString (bool &del, int foff, ExceptionSink *xsink) const
 returns a QoreString giving the verbose string representation of the List (including all contained values)
virtual DLLEXPORT
AbstractQoreNode
realCopy () const
 performs a deep copy of the hash and returns the new hash
virtual DLLEXPORT bool is_equal_soft (const AbstractQoreNode *v, ExceptionSink *xsink) const
 tests for equality ("deep compare" including all contained values) with possible type conversion (soft compare)
virtual DLLEXPORT bool is_equal_hard (const AbstractQoreNode *v, ExceptionSink *xsink) const
 tests for equality ("deep compare" including all contained values) without type conversions (hard compare)
virtual DLLEXPORT const char * getTypeName () const
 returns the type name as a c string
DLLEXPORT QoreHashNodehashRefSelf () 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 AbstractQoreNodegetKeyValueExistence (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 AbstractQoreNodegetKeyValueExistence (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 AbstractQoreNodegetKeyValueExistence (const QoreString *key, bool &exists, ExceptionSink *xsink)
 returns the value of the key if it exists and sets "exists" accordingly
DLLEXPORT const AbstractQoreNodegetKeyValueExistence (const QoreString *key, bool &exists, ExceptionSink *xsink) const
 returns the value of the key if it exists and sets "exists" accordingly
DLLEXPORT AbstractQoreNodegetKeyValue (const QoreString *key, ExceptionSink *xsink)
 returns the value of the key if it exists
DLLEXPORT const AbstractQoreNodegetKeyValue (const QoreString *key, ExceptionSink *xsink) const
 returns the value of the key if it exists
DLLEXPORT AbstractQoreNodegetKeyValue (const char *key)
 returns the value of the key (assumed to be in QCS_DEFAULT) if it exists
DLLEXPORT const AbstractQoreNodegetKeyValue (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 QoreHashNodecopy () const
 performs a deep copy of the hash and returns the new hash
DLLEXPORT AbstractQoreNode ** getKeyValuePtr (const QoreString *key, ExceptionSink *xsink)
 returns a pointer to a pointer of the value of the key so the value may be set or changed externally
DLLEXPORT AbstractQoreNode ** getKeyValuePtr (const char *key)
 returns a pointer to a pointer of the value of the key (assumed to be in QCS_DEFAULT) so the value may be set or changed externally
DLLEXPORT AbstractQoreNode ** getExistingValuePtr (const QoreString *key, ExceptionSink *xsink)
 returns a pointer to a pointer of the value of the key only if the key already exists
DLLEXPORT AbstractQoreNode ** getExistingValuePtr (const char *key)
 returns a pointer to a pointer of the value of the key (assumed to be be in QCS_DEFAULT), only if the key already exists
DLLEXPORT void merge (const QoreHashNode *h, ExceptionSink *xsink)
 appends all key-value pairs of "h" to this hash
DLLEXPORT void setKeyValue (const QoreString *key, AbstractQoreNode *value, ExceptionSink *xsink)
 sets the value of "key" to "value"
DLLEXPORT void setKeyValue (const char *key, AbstractQoreNode *value, ExceptionSink *xsink)
 sets the value of "key" to "value"
DLLEXPORT AbstractQoreNodeswapKeyValue (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 AbstractQoreNodeswapKeyValue (const char *key, AbstractQoreNode *value)
 sets the value of "key" to "value" and returns the old value (0 if not present or if already 0), caller owns any reference count returned
DLLEXPORT void deleteKey (const QoreString *key, ExceptionSink *xsink)
 performs a delete operation on the value of the given key
DLLEXPORT void deleteKey (const char *key, ExceptionSink *xsink)
 performs a delete operation on the value of the given key
DLLEXPORT AbstractQoreNodetakeKeyValue (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 AbstractQoreNodetakeKeyValue (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 QoreListNodegetKeys () 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
DLLLOCAL void clearNeedsEval ()
 sets "needs_eval" to false and "value" to true
DLLLOCAL void setNeedsEval ()
 sets "needs_eval" to true and "value" to false
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

Static Public Member Functions

static DLLLOCAL const char * getStaticTypeName ()
 returns the type name

Protected Member Functions

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

Protected Attributes

struct qore_hash_private * priv
 private implementation of the class

Friends

class HashIterator
class ConstHashIterator


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 and JSON (and possibly others in the future).


Constructor & Destructor Documentation

virtual DLLEXPORT QoreHashNode::~QoreHashNode (  )  [protected, virtual]

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

See also:
AbstractQoreNode::deref()

QoreHashNode::derefImpl()


Member Function Documentation

virtual DLLEXPORT bool QoreHashNode::derefImpl ( ExceptionSink xsink  )  [protected, virtual]

dereferences all elements of the hash

The ExceptionSink argument is needed for those types that could throw an exception when they are deleted (ex: QoreObject) - which could be contained in the hash

Parameters:
xsink if an error occurs, the Qore-language exception information will be added here
Returns:
true if the object can be deleted, false if not (externally-managed)

Reimplemented from AbstractQoreNode.

virtual DLLEXPORT AbstractQoreNode* QoreHashNode::evalImpl ( ExceptionSink xsink  )  const [protected, virtual]

evaluates the object and returns a value (or 0)

return value requires a deref(xsink) if the object requires evaluation and there is an exception, 0 will be returned

Implements AbstractQoreNode.

virtual DLLLOCAL AbstractQoreNode* QoreHashNode::evalImpl ( bool &  needs_deref,
ExceptionSink xsink 
) const [protected, virtual]

optionally evaluates the argument

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

See also:
AbstractQoreNode::eval()

Implements AbstractQoreNode.

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.

virtual DLLEXPORT AbstractQoreNode* QoreHashNode::realCopy (  )  const [virtual]

performs a deep copy of the hash and returns the new hash

Returns:
a copy of the QoreHashNode

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.

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 const char* QoreHashNode::getTypeName (  )  const [virtual]

returns the type name as a c string

Returns:
the type name as a c string

Implements AbstractQoreNode.

static DLLLOCAL const char* QoreHashNode::getStaticTypeName (  )  [inline, static]

returns the type name

Returns:
the type name

DLLEXPORT QoreHashNode* QoreHashNode::hashRefSelf (  )  const

returns "this" with an incremented reference count

Returns:
"this" with an incremented reference count

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

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::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 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 QoreHashNode* QoreHashNode::copy (  )  const

performs a deep copy of the hash and returns the new hash

Returns:
a copy of the current QoreHashNode

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

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)

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

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

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

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)

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

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

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

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

DLLEXPORT QoreListNode* QoreHashNode::getKeys (  )  const

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

to iterate through a hash, use HashIterator or ConstHashIterator

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

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 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 qore_size_t QoreHashNode::size (  )  const

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

return the number of members in the hash

DLLEXPORT bool QoreHashNode::empty (  )  const

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

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

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


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

Generated on Mon Oct 26 09:09:50 2009 for Qore Programming Language by  doxygen 1.5.6