$darkmode
Qore Programming Language - C/C++ Library 1.19.2
QoreHashNode.h
1 /* -*- mode: c++; indent-tabs-mode: nil -*- */
2 /*
3  QoreHashNode.h
4 
5  Qore Programming Language
6 
7  Copyright (C) 2003 - 2023 Qore Technologies, s.r.o.
8 
9  Permission is hereby granted, free of charge, to any person obtaining a
10  copy of this software and associated documentation files (the "Software"),
11  to deal in the Software without restriction, including without limitation
12  the rights to use, copy, modify, merge, publish, distribute, sublicense,
13  and/or sell copies of the Software, and to permit persons to whom the
14  Software is furnished to do so, subject to the following conditions:
15 
16  The above copyright notice and this permission notice shall be included in
17  all copies or substantial portions of the Software.
18 
19  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
20  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
21  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
22  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
23  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
24  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
25  DEALINGS IN THE SOFTWARE.
26 
27  Note that the Qore library is released under a choice of three open-source
28  licenses: MIT (as above), LGPL 2+, or GPL 2+; see README-LICENSE for more
29  information.
30 */
31 
32 #ifndef _QORE_QOREHASHNODE_H
33 
34 #define _QORE_QOREHASHNODE_H
35 
36 #include <qore/AbstractQoreNode.h>
37 #include <qore/common.h>
38 
39 class LocalVar;
40 class QoreString;
41 class TypedHashDecl;
42 
44 
51  friend class HashIterator;
52  friend class ReverseHashIterator;
53  friend class ConstHashIterator;
54  friend class ReverseConstHashIterator;
55  friend class HashAssignmentHelper;
56  friend class hash_assignment_priv;
57  friend class qore_object_private;
58  friend class qore_hash_private;
59 
60 public:
62  DLLEXPORT QoreHashNode();
63 
65 
67  DLLEXPORT QoreHashNode(const TypedHashDecl* hd, ExceptionSink* xsink);
68 
70 
72  DLLEXPORT QoreHashNode(const QoreTypeInfo* valueTypeInfo);
73 
75 
77  DLLEXPORT virtual bool getAsBoolImpl() const;
78 
80 
86  DLLEXPORT virtual int getAsString(QoreString& str, int foff, ExceptionSink* xsink) const;
87 
89 
96  DLLEXPORT virtual QoreString* getAsString(bool &del, int foff, ExceptionSink* xsink) const;
97 
99 
101  DLLEXPORT virtual AbstractQoreNode* realCopy() const;
102 
104 
108  DLLEXPORT virtual bool is_equal_soft(const AbstractQoreNode* v, ExceptionSink* xsink) const;
109 
111 
115  DLLEXPORT virtual bool is_equal_hard(const AbstractQoreNode* v, ExceptionSink* xsink) const;
116 
118 
120  DLLEXPORT virtual const char* getTypeName() const;
121 
123 
125  DLLEXPORT QoreHashNode* hashRefSelf() const;
126 
128 
130  DLLEXPORT const char* getFirstKey() const;
131 
133 
135  DLLEXPORT const char* getLastKey() const;
136 
138 
146  DLLEXPORT QoreValue getKeyValueExistence(const char* key, bool& exists, ExceptionSink* xsink) const;
147 
149 
156  DLLEXPORT QoreValue getKeyValueExistence(const char* key, bool& exists) const;
157 
159 
166  DLLEXPORT QoreValue getKeyValue(const char* key, ExceptionSink* xsink) const;
167 
169 
175  DLLEXPORT QoreValue getKeyValue(const char* key) const;
176 
178 
186  DLLEXPORT QoreValue getKeyValueExistence(const QoreString& key, bool& exists, ExceptionSink* xsink) const;
187 
189 
196  DLLEXPORT QoreValue getKeyValueExistence(const QoreString& key, bool& exists) const;
197 
199 
206  DLLEXPORT QoreValue getKeyValue(const QoreString& key, ExceptionSink* xsink) const;
207 
209 
215  DLLEXPORT int64 getKeyAsBigInt(const char* key, bool &found) const;
216 
218 
224  DLLEXPORT bool getKeyAsBool(const char* key, bool &found) const;
225 
227 
229  DLLEXPORT QoreHashNode* copy() const;
230 
231  DLLEXPORT QoreValue& getKeyValueReference(const char* key);
232 
234 
239  DLLEXPORT void merge(const QoreHashNode* h, ExceptionSink* xsink);
240 
242 
253  DLLEXPORT int setKeyValue(const char* key, QoreValue value, ExceptionSink* xsink);
254 
256 
267  DLLEXPORT int setKeyValue(const QoreString& key, QoreValue value, ExceptionSink* xsink);
268 
270 
275  DLLEXPORT void deleteKey(const QoreString* key, ExceptionSink* xsink);
276 
278 
282  DLLEXPORT void deleteKey(const char* key, ExceptionSink* xsink);
283 
285  DLLEXPORT QoreValue takeKeyValue(const char* key);
286 
288 
291  DLLEXPORT QoreListNode* getKeys() const;
292 
294 
299  DLLEXPORT QoreListNode* getValues() const;
300 
302 
305  DLLEXPORT bool compareSoft(const QoreHashNode* h, ExceptionSink* xsink) const;
306 
308 
311  DLLEXPORT bool compareHard(const QoreHashNode* h, ExceptionSink* xsink) const;
312 
314 
316  DLLEXPORT size_t size() const;
317 
319 
321  DLLEXPORT bool empty() const;
322 
324 
328  DLLEXPORT bool existsKey(const char* key) const;
329 
331 
334  DLLEXPORT bool existsKeyValue(const char* key) const;
335 
337 
341  DLLEXPORT void removeKey(const QoreString* key, ExceptionSink* xsink);
342 
344 
348  DLLEXPORT void removeKey(const char* key, ExceptionSink* xsink);
349 
351 
353  DLLEXPORT const TypedHashDecl* getHashDecl() const;
354 
356 
358  DLLEXPORT const QoreTypeInfo* getValueTypeInfo() const;
359 
361 
363  DLLEXPORT const QoreTypeInfo* getTypeInfo() const;
364 
366 
368  DLLLOCAL static const char* getStaticTypeName() {
369  return "hash";
370  }
371 
373  DLLLOCAL static qore_type_t getStaticTypeCode() {
374  return NT_HASH;
375  }
376 
377  static const qore_type_t TYPE = NT_HASH;
378 
380  DLLLOCAL virtual int parseInit(QoreValue& val, QoreParseContext& parse_context);
381 
382  DLLLOCAL QoreHashNode(bool ne);
383  DLLLOCAL void clear(ExceptionSink* xsink, bool reverse = false);
384 
386  DLLLOCAL void clearNeedsEval();
387 
389  DLLLOCAL void setNeedsEval();
390 
391  // returns a new hash consisting of just the members of value_list
392  DLLLOCAL QoreHashNode* getSlice(const QoreListNode* value_list, ExceptionSink* xsink) const;
393 
394 protected:
396  class qore_hash_private *priv;
397 
399 
405  DLLEXPORT virtual bool derefImpl(ExceptionSink* xsink);
406 
408 
411  DLLLOCAL virtual QoreValue evalImpl(bool &needs_deref, ExceptionSink* xsink) const;
412 
414 
417  DLLEXPORT virtual ~QoreHashNode();
418 
419 private:
420  DLLLOCAL QoreHashNode(const QoreHashNode&) = delete;
421  DLLLOCAL QoreHashNode& operator=(const QoreHashNode&) = delete;
422 };
423 
424 #include <qore/ReferenceHolder.h>
425 
427 
431 
432 class qhi_priv;
433 
435 
445  friend class HashAssignmentHelper;
446  friend class qhi_priv;
447 
448 protected:
449  QoreHashNode* h;
450  qhi_priv* priv;
451 
453  DLLLOCAL HashIterator(const HashIterator&);
454 
457 
459  DLLLOCAL void* operator new(size_t);
460 
461 public:
463  DLLEXPORT HashIterator(QoreHashNode* h);
464 
466  DLLEXPORT HashIterator(QoreHashNode& h);
467 
469  DLLEXPORT ~HashIterator();
470 
472 
475  DLLEXPORT bool next();
476 
478 
481  DLLEXPORT bool prev();
482 
484  DLLEXPORT const char* getKey() const;
485 
487  DLLEXPORT QoreString* getKeyString() const;
488 
490  DLLEXPORT QoreValue get() const;
491 
493  DLLEXPORT const QoreTypeInfo* getTypeInfo() const;
494 
496 
500  DLLEXPORT void deleteKey(ExceptionSink* xsink);
501 
503 
516  DLLEXPORT int assign(QoreValue val, ExceptionSink* xsink);
517 
520 
522  DLLEXPORT QoreValue getReferenced() const;
523 
525  DLLEXPORT QoreHashNode* getHash() const;
526 
528  DLLEXPORT bool first() const;
529 
531  DLLEXPORT bool last() const;
532 
534  DLLEXPORT bool empty() const;
535 
537  DLLEXPORT bool valid() const;
538 };
539 
541 
551 public:
554 
557 
559  DLLEXPORT ~ReverseHashIterator();
560 
562 
565  DLLEXPORT bool next();
566 
568 
571  DLLEXPORT bool prev();
572 
574  DLLEXPORT bool first() const;
575 
577  DLLEXPORT bool last() const;
578 };
579 
581 
591 protected:
592  const QoreHashNode* h;
593  qhi_priv* priv;
594 
597 
598 public:
600  DLLEXPORT ConstHashIterator(const QoreHashNode* h);
601 
603  DLLEXPORT ConstHashIterator(const QoreHashNode& h);
604 
607 
609  DLLEXPORT ~ConstHashIterator();
610 
612 
615  DLLEXPORT bool next();
616 
618 
621  DLLEXPORT bool prev();
622 
624  DLLEXPORT const char* getKey() const;
625 
627  DLLEXPORT QoreString* getKeyString() const;
628 
630  DLLEXPORT const QoreValue get() const;
631 
633  DLLEXPORT const QoreTypeInfo* getTypeInfo() const;
634 
636  DLLEXPORT QoreValue getReferenced() const;
637 
639  DLLEXPORT const QoreHashNode* getHash() const;
640 
642  DLLEXPORT bool first() const;
643 
645  DLLEXPORT bool last() const;
646 
648  DLLEXPORT bool empty() const;
649 
651  DLLEXPORT bool valid() const;
652 
654  DLLEXPORT void reset();
655 };
656 
658 
668 public:
671 
674 
677 
679 
682  DLLEXPORT bool next();
683 
685 
688  DLLEXPORT bool prev();
689 
691  DLLEXPORT bool first() const;
692 
694  DLLEXPORT bool last() const;
695 };
696 
699 friend class hash_assignment_priv;
700 public:
702 
706  DLLEXPORT HashAssignmentHelper(QoreHashNode& n_h, const char* key, bool must_already_exist = false);
707 
709 
713  DLLEXPORT HashAssignmentHelper(QoreHashNode& n_h, const std::string& key, bool must_already_exist = false);
714 
716 
723  DLLEXPORT HashAssignmentHelper(ExceptionSink* xsink, QoreHashNode& n_h, const QoreString& key, bool must_already_exist = false);
724 
726 
733  DLLEXPORT HashAssignmentHelper(ExceptionSink* xsink, QoreHashNode& n_h, const QoreString* key, bool must_already_exist = false);
734 
736 
739 
742 
744 
749  DLLEXPORT void reassign(const char* key, bool must_already_exist = false);
750 
752 
757  DLLEXPORT void reassign(const std::string& key, bool must_already_exist = false);
758 
760 
762  DLLEXPORT operator bool() const;
763 
765 
769  DLLEXPORT void assign(QoreValue v, ExceptionSink* xsink);
770 
772 
775  DLLEXPORT QoreValue swap(QoreValue v, ExceptionSink* xsink);
776 
778 
782  DLLEXPORT QoreValue get() const;
783 
785 
787  DLLEXPORT QoreValue operator*() const;
788 
790 
794  DLLEXPORT const char* getKey() const;
795 
796 protected:
798  class hash_assignment_priv *priv;
799 
800 private:
801  DLLLOCAL HashAssignmentHelper(const HashAssignmentHelper&) = delete;
802  DLLLOCAL HashAssignmentHelper& operator=(const HashAssignmentHelper&) = delete;
803  DLLLOCAL void* operator new(size_t) = delete;
804 };
805 
806 #endif // _QORE_HASH_H
The base class for all value and parse types in Qore expression trees.
Definition: AbstractQoreNode.h:57
bool value
this is true for values, if false then either the type needs evaluation to produce a value or is a pa...
Definition: AbstractQoreNode.h:330
constant iterator class for QoreHashNode, to be only created on the stack
Definition: QoreHashNode.h:590
DLLEXPORT bool valid() const
returns true if the iterator is currently pointing at a valid element
DLLEXPORT bool last() const
returns true if on the last key of the hash
DLLEXPORT const QoreHashNode * getHash() const
returns the hash
DLLEXPORT ~ConstHashIterator()
Destroys the iterator.
DLLEXPORT bool first() const
returns true if on the first key of the hash
DLLEXPORT QoreString * getKeyString() const
returns a QoreString for the current key, the caller owns QoreString returned
DLLEXPORT void reset()
resets the iterator to its initial state
DLLEXPORT const QoreValue get() const
returns the value of the current key
DLLEXPORT bool prev()
moves to the previous element, returns false when there are no more elements to iterate
DLLEXPORT const QoreTypeInfo * getTypeInfo() const
returns the type info for the current value
DLLEXPORT QoreValue getReferenced() const
returns the value of the current key with an incremented reference count
DLLLOCAL ConstHashIterator & operator=(const HashIterator &)
this function is not implemented; it is here as a protected function in order to prohibit it from bei...
DLLEXPORT const char * getKey() const
returns the current key
DLLEXPORT bool next()
moves to the next element, returns false when there are no more elements to iterate
DLLEXPORT bool empty() const
returns true if the hash is empty
DLLEXPORT ConstHashIterator(const QoreHashNode *h)
initializes the iterator with the passed hash
container for holding Qore-language exception information and also for registering a "thread_exit" ca...
Definition: ExceptionSink.h:50
use this class to make assignments to hash keys from a pointer to the key value
Definition: QoreHashNode.h:698
DLLEXPORT ~HashAssignmentHelper()
destroys the object and does post processing on the new value
DLLEXPORT QoreValue swap(QoreValue v, ExceptionSink *xsink)
swaps the current value with the new value of the hash key, assumes that the new value is already ref...
DLLEXPORT void assign(QoreValue v, ExceptionSink *xsink)
assigns a value to the hash key, dereferences any old value, assumes that the value is already refere...
DLLEXPORT const char * getKey() const
Returns the current key.
DLLEXPORT HashAssignmentHelper(QoreHashNode &n_h, const char *key, bool must_already_exist=false)
constructor taking a const char*
DLLEXPORT QoreValue operator*() const
returns the current value of the hash key; any pointer returned is still owned by the hash
class hash_assignment_priv * priv
private implementation
Definition: QoreHashNode.h:798
DLLEXPORT void reassign(const char *key, bool must_already_exist=false)
reassigns the object to the given key for a new assignment
DLLEXPORT QoreValue get() const
returns the current value of the hash key; the pointer returned is still owned by the hash
iterator class for QoreHashNode, to be only created on the stack
Definition: QoreHashNode.h:444
DLLEXPORT int assign(QoreValue val, ExceptionSink *xsink)
Assigns the given value to the key and dereferences any current value.
DLLEXPORT QoreValue getReferenced() const
returns the value of the current key with an incremented reference count
DLLEXPORT const char * getKey() const
returns the current key
DLLEXPORT bool last() const
returns true if on the last key of the hash
DLLEXPORT bool valid() const
returns true if the iterator is currently pointing at a valid element
DLLEXPORT bool empty() const
returns true if the hash is empty
DLLLOCAL HashIterator & operator=(const HashIterator &)
this function is not implemented; it is here as a private function in order to prohibit it from being...
DLLEXPORT QoreString * getKeyString() const
returns a QoreString for the current key, the caller owns QoreString returned
DLLEXPORT void deleteKey(ExceptionSink *xsink)
deletes the key from the hash and dereferences the value
DLLEXPORT QoreHashNode * getHash() const
returns the hash
DLLEXPORT QoreValue removeKeyValue()
removes the key value and returns the value returned
DLLLOCAL HashIterator(const HashIterator &)
this function is not implemented; it is here as a private function in order to prohibit it from being...
DLLEXPORT const QoreTypeInfo * getTypeInfo() const
returns the type info for the current value
DLLEXPORT bool next()
moves to the next element, returns false when there are no more elements to iterate
DLLEXPORT bool prev()
moves to the previous element, returns false when there are no more elements to iterate
DLLEXPORT bool first() const
returns true if on the first key of the hash
DLLEXPORT ~HashIterator()
Destroys the iterator.
DLLEXPORT QoreValue get() const
returns the value of the current key
This is the hash or associative list container type in Qore, dynamically allocated only,...
Definition: QoreHashNode.h:50
virtual DLLEXPORT AbstractQoreNode * realCopy() const
performs a copy of the hash and returns the new hash
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 QoreValue takeKeyValue(const char *key)
removes the value from the hash and returns the value removed, if any
DLLEXPORT int setKeyValue(const char *key, QoreValue value, ExceptionSink *xsink)
sets the value of "key" to "value"
DLLEXPORT const char * getLastKey() const
returns the cstring value of the last key in the hash
DLLEXPORT size_t size() const
returns the number of members in the hash, executes in constant time
DLLEXPORT QoreValue getKeyValue(const char *key, ExceptionSink *xsink) const
returns the value of the given key
class qore_hash_private * priv
private implementation of the class
Definition: QoreHashNode.h:396
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 retur...
DLLEXPORT QoreHashNode()
creates an empty hash
DLLEXPORT const QoreTypeInfo * getValueTypeInfo() const
returns the value type declaration (only possible if there is no hashdecl set)
DLLEXPORT bool existsKey(const char *key) const
returns true if the hash contains the given key
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 (sof...
DLLEXPORT int64 getKeyAsBigInt(const char *key, bool &found) const
returns the value of the key as an int64
virtual DLLLOCAL int parseInit(QoreValue &val, QoreParseContext &parse_context)
initializes during parsing
DLLLOCAL void setNeedsEval()
sets "needs_eval" to true and "value" to false
static DLLLOCAL const char * getStaticTypeName()
returns the type name (useful in templates)
Definition: QoreHashNode.h:368
DLLEXPORT QoreValue getKeyValueExistence(const char *key, bool &exists, ExceptionSink *xsink) const
returns the value of the given key
virtual DLLEXPORT bool derefImpl(ExceptionSink *xsink)
dereferences all elements of the hash
DLLEXPORT const TypedHashDecl * getHashDecl() const
returns the hash's type declaration, if any
DLLEXPORT void removeKey(const QoreString *key, ExceptionSink *xsink)
removes the given key from the hash and derefences its value, if any
DLLEXPORT QoreListNode * getValues() const
returns a QoreListNode of AbstractQoreNode pointers representing all values in the hash; caller owns ...
DLLEXPORT bool getKeyAsBool(const char *key, bool &found) const
returns the value of the key as a bool
DLLEXPORT QoreListNode * getKeys() const
returns a QoreListNode of QoreStringNode pointers representing all keys in the hash,...
virtual DLLEXPORT ~QoreHashNode()
deletes the object, cannot be called directly (use deref(ExceptionSink*) instead)
DLLEXPORT bool empty() const
returns true if the hash has no members, false if not
DLLEXPORT void merge(const QoreHashNode *h, ExceptionSink *xsink)
appends all key-value pairs of "h" to this hash
DLLEXPORT QoreHashNode * copy() const
performs a copy of the hash and returns the new hash
virtual DLLEXPORT bool getAsBoolImpl() const
returns false unless perl-boolean-evaluation is enabled, in which case it returns false only when emp...
static DLLLOCAL qore_type_t getStaticTypeCode()
returns the type code (useful in templates)
Definition: QoreHashNode.h:373
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 exis...
DLLEXPORT const QoreTypeInfo * getTypeInfo() const
returns the type info structure for the current value; also works for hashes derived from a TypedHash...
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 com...
DLLEXPORT QoreHashNode * hashRefSelf() const
returns "this" with an incremented reference count
DLLLOCAL void clearNeedsEval()
sets "needs_eval" to false and "value" to true
virtual DLLEXPORT const char * getTypeName() const
returns the type name as a c string
DLLEXPORT const char * getFirstKey() const
returns the cstring value of the first key in the hash
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 ...
DLLEXPORT void deleteKey(const QoreString *key, ExceptionSink *xsink)
performs a delete operation on the value of the given key
virtual DLLLOCAL QoreValue evalImpl(bool &needs_deref, ExceptionSink *xsink) const
optionally evaluates the argument
This is the list container type in Qore, dynamically allocated only, reference counted.
Definition: QoreListNode.h:52
Qore's string type supported by the QoreEncoding class.
Definition: QoreString.h:93
a templated class to manage a reference count of an object that can throw a Qore-language exception w...
Definition: ReferenceHolder.h:52
reverse constant iterator class for QoreHashNode, to be only created on the stack
Definition: QoreHashNode.h:667
DLLEXPORT ~ReverseConstHashIterator()
Destroys the iterator.
DLLEXPORT bool first() const
returns true if on the last key of the hash
DLLEXPORT ReverseConstHashIterator(const QoreHashNode *h)
initializes the iterator with the passed hash
DLLEXPORT bool last() const
returns true if on the first key of the hash
DLLEXPORT bool prev()
moves to the previous element in reverse order, returns false when there are no more elements to iter...
DLLEXPORT bool next()
moves to the next element in reverse order, returns false when there are no more elements to iterate
reverse iterator class for QoreHashNode, to be only created on the stack
Definition: QoreHashNode.h:550
DLLEXPORT bool first() const
returns true if on the last key of the hash
DLLEXPORT bool next()
moves to the next element in reverse order, returns false when there are no more elements to iterate
DLLEXPORT ReverseHashIterator(QoreHashNode *h)
initializes the iterator with the passed hash
DLLEXPORT ~ReverseHashIterator()
Destroys the iterator.
DLLEXPORT bool last() const
returns true if on the first key of the hash
DLLEXPORT bool prev()
moves to the previous element in reverse order, returns false when there are no more elements to iter...
typed hash declaration
Definition: TypedHashDecl.h:44
int16_t qore_type_t
used to identify unique Qore data and parse types (descendents of AbstractQoreNode)
Definition: common.h:70
long long int64
64bit integer type, cannot use int64_t here since it breaks the API on some 64-bit systems due to equ...
Definition: common.h:260
const qore_type_t NT_HASH
type value for QoreHashNode
Definition: node_types.h:51
The main value class in Qore, designed to be passed by value.
Definition: QoreValue.h:276