Jamoma API  0.6.0.a19
TTDictionaryBase.h
Go to the documentation of this file.
1 /** @file
2  *
3  * @ingroup foundationLibrary
4  *
5  * @brief Foundation Dictionary Class.
6  *
7  * @details The dictionary is a data structure that combines the fast lookup of a hashtable,
8  * but may be sorted like a linked-list.
9  * The linked list contains the key-value pairs of the hash a linked-list of TTKeyValues.
10  *
11  * @author Timothy Place, Trond Lossius
12  *
13  * @copyright Copyright © 2010, Timothy Place @n
14  * This code is licensed under the terms of the "New BSD License" @n
15  * http://creativecommons.org/licenses/BSD/
16  */
17 
18 
19 #ifndef __TT_DICTIONARY_BASEH__
20 #define __TT_DICTIONARY_BASEH__
21 
22 #include "TTValue.h"
23 #include "TTList.h"
24 
25 
26 /****************************************************************************************************/
27 // Class Specification
28 
29 typedef std::pair<TTPtrSizedInt,TTValue> TTDictionaryBasePair;
30 #if defined( __ICC )
31 #include "boost/unordered_map.hpp"
32 typedef boost::unordered_map<TTPtrSizedInt, TTValue> TTDictionaryBaseMap;
33 #else
34 #include <unordered_map>
35 typedef std::unordered_map<TTPtrSizedInt, TTValue> TTDictionaryBaseMap;
36 #endif
37 typedef TTDictionaryBaseMap::iterator TTDictionaryBaseMapIter;
38 typedef TTDictionaryBaseMap::const_iterator TTDictionaryBaseMapIterK;
39 
40 
41 /** A type that contains a key and a value. */
42 //typedef pair<TTPtrSizedInt,TTValue> TTKeyVal;
43 //typedef TTKeyVal* TTKeyValPtr;
44 //typedef void (*TTHashIteratorType)(TTPtr, const TTKeyVal&);
45 
46 
47 
48 /**
49  The dictionary is a data structure that combines the fast lookup of a hashtable, but may be sorted like a linked-list.
50  This accomplished internally by maintaining the two data structures in parallel.
51 
52  Note that generally speaking you should not directly create a TTDictionaryBase!
53  Instead, TTDictionaryBase objects should only by created by the instantiating a #TTDictionary.
54 */
55 class TTFOUNDATION_EXPORT TTDictionaryBase {
56  friend class TTDictionary;
57 
58 private:
59 
60 // TTHashPtr mHashTable;
61 // TTListPtr mList;
62  TTDictionaryBaseMap mMap;
63  TTPtrSizedInt mReferenceCount;
64  TTList mObservers; ///< List of all objects watching this object for life-cycle and other changes.
65 
66 public:
68  virtual ~TTDictionaryBase();
69 
70  // The copy assignment constructor doesn't appear to be involved, at least with resizes, on the Mac...
71  // This operator is used when pushing to an append# object, however...
72  TTDictionaryBase& operator=(const TTDictionaryBase& source)
73  {
74 // if (mHashTable)
75 // delete mHashTable;
76 // mHashTable = new TTHash(*source.mHashTable);
77 
78  mMap = source.mMap;
79 
80 // if (mList)
81 // delete mList;
82 // mList = new TTList(*source.mList);
83  return *this;
84  }
85 
86 
87  /** TODO: Add documentation
88  @para schemaName TODO: Add documentation
89  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
90  */
91  TTErr setSchema(const TTSymbol schemaName);
92 
93 
94  /** TODO: Add documentation
95  @return TODO: Add documentation
96  */
97  const TTSymbol getSchema() const;
98 
99 
100  /** TODO: Add documentation
101  @param newValue TODO: Add documentation
102  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
103  */
104  TTErr setValue(const TTValue& newValue);
105 
106 
107  /** TODO: Add documentation
108  @param returnedValue TODO: Add documentation
109  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
110  */
111  TTErr getValue(TTValue& returnedValue) const;
112 
113  /** Get a dictionary's primary value
114  @param value The returned value of the dictionary.
115  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
116  */
117  template <class T>
118  TTErr getValue(T& aReturnedValue) const
119  {
120  TTValue v;
121  TTErr error = getValue(v);
122  aReturnedValue = v;
123  return error;
124  }
125 
126 
127  /** Insert an item into the hash table.
128  @param value The value to instert.
129  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
130  */
131  TTErr append(const TTSymbol key, const TTValue& value);
132 
133 
134  /** Find the value for the given key.
135  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
136  */
137  TTErr lookup(const TTSymbol key, TTValue& value) const;
138 
139 
140  /** Remove an item from the hash table.
141  @param key The key of the item to remove.
142  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
143  */
144  TTErr remove(const TTSymbol key);
145 
146 
147  /** Remove all items from the hash table.
148  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
149  */
150  TTErr clear();
151 
152 
153  /** Get an array of all of the keys for the hash table.
154  @param hashKeys Used to return an array of all of the keys for the hash table
155  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
156  */
157  TTErr getKeys(TTValue& hashKeys);
158 
159 
160  /** Return the number of keys in the hash table.
161  @return The number of keys in the hash table.
162  */
163  TTUInt32 getSize();
164 
165 
166  /** Return true if the hash has nothing stored in it.
167  @return TRUE if the hash has nothing stored in it.
168  */
169  TTBoolean isEmpty();
170 
171 
172 
173 
174  TTErr registerObserverForNotifications(const TTObjectBase& observingObject);
175  TTErr unregisterObserverForNotifications(const TTObjectBase& observingObject);
176  TTErr sendNotification(const TTSymbol name, const TTValue& arguments);
177 
178 };
179 
180 /** Pointer to a #TTDictionary.
181  @ingroup typedefs
182  */
184 
185 
186 #endif // __TT_DICTIONARY_BASEH__
bool TTBoolean
Boolean flag, same as Boolean on the Mac.
Definition: TTBase.h:167
TTDictionaryBase * TTDictionaryBasePtr
Pointer to a TTDictionary.
TTErr unregisterObserverForNotifications(const TTObjectBase &anObservingObject)
Unregister an observer for notifications.
A type that contains a key and a value.
TTErr append(const TTSymbol aKey, const TTValue aValue)
Insert an item into the hash table.
Definition: TTDictionary.h:212
TTSymbol name() const
Return the name associated with the dictionary.
Definition: TTDictionary.h:131
TTErr clear()
Remove all items from the hash table.
Definition: TTDictionary.h:240
TTErr getKeys(TTValue &aSetOfKeys)
Get an array of all of the keys for the hash table.
Definition: TTDictionary.h:250
Base class for all first-class Jamoma objects.
Definition: TTObjectBase.h:109
TTErr getValue(T &aReturnedValue) const
Get the dictionary's primary value.
Definition: TTDictionary.h:202
A type that represents the key as a C-String and the value as a pointer to the matching TTSymbol obje...
Definition: TTDictionary.h:47
TTErr registerObserverForNotifications(const TTObjectBase &anObservingObject)
Register an observer.
The TTSymbol class is used to represent a string and efficiently pass and compare that string...
Definition: TTSymbol.h:26
const TTSymbol getSchema() const
TODO: Add documentation.
Definition: TTDictionary.h:181
TTErr getValue(T &aReturnedValue) const
Get a dictionary's primary value.
TTErr setSchema(const TTSymbol aSchemaName)
TODO: Add documentation schemaName TODO: Add documentation.
Definition: TTDictionary.h:172
TTErr setValue(const TTValue aNewValue)
TODO: Add documentation.
Definition: TTDictionary.h:191
long TTPtrSizedInt
An integer that is the same size as a pointer.
Definition: TTBase.h:240
TTErr
Jamoma Error Codes Enumeration of error codes that might be returned by any of the TTBlue functions a...
Definition: TTBase.h:342
TTErr lookup(const TTSymbol aKey, TTValue &aValue) const
Find the value for the given key.
Definition: TTDictionary.h:221
std::uint32_t TTUInt32
32 bit unsigned integer
Definition: TTBase.h:178
Provides a common way of representing composite values.
[doxygenAppendixC_copyExample]
Definition: TTValue.h:34