Jamoma API  0.6.0.a19
TTDictionary.h
Go to the documentation of this file.
1 /** @file
2  @ingroup foundationLibrary
3 
4  @brief Foundation Dictionary Class.
5 
6  @details
7  The dictionary is a data structure that combines the fast lookup of a hashtable, but may be sorted like a linked-list.
8  Dictionaries are associated with symbols.
9 
10  @author Timothy Place, Trond Lossius
11 
12  @copyright Copyright © 2010, Timothy Place @n
13  This code is licensed under the terms of the "New BSD License" @n
14  http://creativecommons.org/licenses/BSD/
15  */
16 
17 
18 #ifndef __TT_DICTIONARY_H__
19 #define __TT_DICTIONARY_H__
20 
21 #include "TTDictionaryBase.h"
22 #include "TTSymbolCache.h"
23 
24 class TTObject;
25 
26 
27 /****************************************************************************************************/
28 // Class Specification
29 
30 /** Map names to internal dictionary instances */
31 typedef std::unordered_map<TTPtr, TTDictionaryBase*> TTDictionaryTable;
32 //typedef std::unordered_map<TTPtrSizedInt, void*> TTDictionaryTable;
33 
34 extern TTFOUNDATION_EXPORT TTDictionaryTable gTTDictionaryTable;
35 
36 /** A type that represents the key as a C-String and the value as a pointer to the matching TTSymbol object. */
37 //typedef std::pair<TTString, TTSymbolBase*> TTSymbolTablePair;
38 
39 
40 /** An iterator for the STL hash_map used by TTSymbolTable. */
41 //typedef TTSymbolTableHash::const_iterator TTSymbolTableIter;
42 
43 
44 /**
45  Create and destroy Jamoma object instances.
46  */
47 class TTFOUNDATION_EXPORT TTDictionary {
48 protected:
49 // friend class TTEnvironment;
50 
51  TTDictionaryBasePtr mDictionaryInstance;
52  TTSymbol mName;
53 
54 public:
55 
56  /** Constructor.
57  @param aDictionaryName The symbolic name associated with this dictionary.
58  If you pass an empty symbol then a random name with be generated and returned here.
59  @param aDictionaryWasCreated Upon return this will be true if a new dictionary was created
60  rather than an existing dictionary being referenced.
61  */
62  TTDictionary(TTSymbol aDictionaryName, TTBoolean& aDictionaryWasCreated)
63  {
64  create(aDictionaryName, kTTSym_none, aDictionaryWasCreated);
65  }
66 
67  TTDictionary(TTSymbol aDictionaryName)
68  {
69  TTBoolean dictionaryCreated;
70  create(aDictionaryName, kTTSym_none, dictionaryCreated);
71  }
72 
73  TTDictionary()
74  {
75  TTBoolean dictionaryCreated;
76  create(TTSymbol::random(), kTTSym_none, dictionaryCreated);
77  }
78 
79 private:
80  void create(TTSymbol aDictionaryName, TTSymbol aSchemaName, TTBoolean& aDictionaryWasCreated)
81  {
82  if (aDictionaryName == "")
83  aDictionaryName = TTSymbol::random();
84 
85  mDictionaryInstance = gTTDictionaryTable[aDictionaryName.rawpointer()];
86  if (!mDictionaryInstance) {
87  mDictionaryInstance = new TTDictionaryBase;
88  gTTDictionaryTable[aDictionaryName.rawpointer()] = mDictionaryInstance;
89  setSchema(aSchemaName);
90  aDictionaryWasCreated = true;
91  }
92  else
93  aDictionaryWasCreated = false;
94 
95  mName = aDictionaryName;
96  mDictionaryInstance->mReferenceCount++;
97  }
98 
99 public:
100  TTDictionary(TTElement* do_not_use_this_unless_your_name_is_ttelement_and_you_are_a_destructor)
101  {
102  mName = TTSymbol(do_not_use_this_unless_your_name_is_ttelement_and_you_are_a_destructor->mValue.dictionary);
103  mDictionaryInstance = gTTDictionaryTable[mName.rawpointer()];
104  // DO NOT INCREASE THE REFERENCE COUNT -- THIS IS A SPECIAL CONSTRUCTOR USED FOR TTELEMENT'S DESTRUCTOR
105  }
106 
107 
108  /** Copy Constructor */
109  TTDictionary(const TTDictionary& aSourceDictionary)
110  {
111  mName = aSourceDictionary.mName;
112  mDictionaryInstance = aSourceDictionary.mDictionaryInstance;
113  mDictionaryInstance->mReferenceCount++;
114  }
115 
116 
117  /** Destructor.
118  */
119  virtual ~TTDictionary()
120  {
121  mDictionaryInstance->mReferenceCount--;
122  if (mDictionaryInstance->mReferenceCount == 0) {
123  gTTDictionaryTable.erase(mName.rawpointer());
124  delete mDictionaryInstance;
125  mDictionaryInstance = NULL;
126  }
127  }
128 
129 
130  /** Return the name associated with the dictionary. */
131  TTSymbol name() const
132  {
133  return mName;
134  }
135 
136 
137 
138 
139  /** Register an observer.
140  The observer will be monitoring this object.
141 
142  @param anObservingObject Reference to the observing object.
143  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
144  */
145  TTErr registerObserverForNotifications(const TTObjectBase& anObservingObject);
146  TTErr registerObserverForNotifications(const TTObject& anObservingObject);
147 
148 
149  /** Unregister an observer for notifications.
150  The observer wiln no longer be monitoring.
151 
152  @param anObservingObject Reference to the observing object.
153  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
154  */
155  TTErr unregisterObserverForNotifications(const TTObjectBase& anObservingObject);
156  TTErr unregisterObserverForNotifications(const TTObject& anObservingObject);
157 
158 
159  // The copy assignment constructor doesn't appear to be involved, at least with resizes, on the Mac...
160  // This operator is used when pushing to an append# object, however...
161  TTDictionary& operator=(const TTDictionary& aSource)
162  {
163  (*mDictionaryInstance) = (*aSource.mDictionaryInstance);
164  return *this;
165  }
166 
167 
168  /** TODO: Add documentation
169  @para schemaName TODO: Add documentation
170  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
171  */
172  TTErr setSchema(const TTSymbol aSchemaName)
173  {
174  return mDictionaryInstance->setSchema(aSchemaName);
175  }
176 
177 
178  /** TODO: Add documentation
179  @return TODO: Add documentation
180  */
181  const TTSymbol getSchema() const
182  {
183  return mDictionaryInstance->getSchema();
184  }
185 
186 
187  /** TODO: Add documentation
188  @param newValue TODO: Add documentation
189  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
190  */
191  TTErr setValue(const TTValue aNewValue) {
192  return mDictionaryInstance->setValue(aNewValue);
193  }
194 
195 
196  /** Get the dictionary's primary value
197  @param name The name of the attribute to get.
198  @param value The returned value of the attribute.
199  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
200  */
201  template <class T>
202  TTErr getValue(T& aReturnedValue) const
203  {
204  return mDictionaryInstance->getValue(aReturnedValue);
205  }
206 
207 
208  /** Insert an item into the hash table.
209  @param value The value to instert.
210  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
211  */
212  TTErr append(const TTSymbol aKey, const TTValue aValue)
213  {
214  return mDictionaryInstance->append(aKey, aValue);
215  }
216 
217 
218  /** Find the value for the given key.
219  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
220  */
221  TTErr lookup(const TTSymbol aKey, TTValue& aValue) const
222  {
223  return mDictionaryInstance->lookup(aKey, aValue);
224  }
225 
226 
227  /** Remove an item from the hash table.
228  @param key The key of the item to remove.
229  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
230  */
231  TTErr remove(const TTSymbol aKey)
232  {
233  return mDictionaryInstance->remove(aKey);
234  }
235 
236 
237  /** Remove all items from the hash table.
238  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
239  */
241  {
242  return mDictionaryInstance->clear();
243  }
244 
245 
246  /** Get an array of all of the keys for the hash table.
247  @param hashKeys Used to return an array of all of the keys for the hash table
248  @return #TTErr error code if the method fails to execute, else #kTTErrNone.
249  */
250  TTErr getKeys(TTValue& aSetOfKeys)
251  {
252  return mDictionaryInstance->getKeys(aSetOfKeys);
253  }
254 
255 
256  /** Return the number of keys in the hash table.
257  @return The number of keys in the hash table.
258  */
260  {
261  return mDictionaryInstance->getSize();
262  }
263 
264 
265  /** Return true if the hash has nothing stored in it.
266  @return TRUE if the hash has nothing stored in it.
267  */
269  {
270  return mDictionaryInstance->isEmpty();
271  }
272 
273 };
274 
275 //! [doxygenAppendixC_typedefExample]
276 /** Pointer to a #TTDictionary.
277  @ingroup typedefs
278  */
280 //! [doxygenAppendixC_typedefExample]
281 
282 
283 #endif // __TT_DICTIONARY_H__
TTErr setSchema(const TTSymbol schemaName)
TODO: Add documentation schemaName TODO: Add documentation.
bool TTBoolean
Boolean flag, same as Boolean on the Mac.
Definition: TTBase.h:167
A type that contains a key and a value.
virtual ~TTDictionary()
Destructor.
Definition: TTDictionary.h:119
TTPtrSizedInt size()
Return the number of keys in the hash table.
Definition: TTDictionary.h:259
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 setValue(const TTValue &newValue)
TODO: Add documentation.
Create and use Jamoma object instances.
Definition: TTObject.h:29
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
const TTSymbol getSchema() const
TODO: Add documentation.
TTErr getValue(T &aReturnedValue) const
Get the dictionary's primary value.
Definition: TTDictionary.h:202
static TTSymbol random()
Generate a pseudo-random symbol.
Definition: TTSymbol.h:141
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 clear()
Remove all items from the hash table.
TTPtr rawpointer() const
Get the value of the raw pointer into the symbol table.
Definition: TTSymbol.h:134
TTBoolean isEmpty()
Return true if the hash has nothing stored in it.
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
TTDictionary(TTSymbol aDictionaryName, TTBoolean &aDictionaryWasCreated)
Constructor.
Definition: TTDictionary.h:62
TTDictionary(const TTDictionary &aSourceDictionary)
Copy Constructor.
Definition: TTDictionary.h:109
TTUInt32 getSize()
Return the number of keys in the hash table.
TTErr lookup(const TTSymbol key, TTValue &value) const
Find the value for the given key.
Individual items found in a TTValue.
Definition: TTElement.h:89
TTBoolean empty()
Return true if the hash has nothing stored in it.
Definition: TTDictionary.h:268
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 append(const TTSymbol key, const TTValue &value)
Insert an item into the hash table.
TTErr lookup(const TTSymbol aKey, TTValue &aValue) const
Find the value for the given key.
Definition: TTDictionary.h:221
std::unordered_map< TTPtr, TTDictionaryBase * > TTDictionaryTable
Map names to internal dictionary instances.
Definition: TTDictionary.h:24
TTErr remove(const TTSymbol key)
Remove an item from the hash table.
TTDictionary * TTDictionaryPtr
[doxygenAppendixC_typedefExample]
Definition: TTDictionary.h:279
[doxygenAppendixC_copyExample]
Definition: TTValue.h:34
Foundation Dictionary Class.
TTErr getValue(TTValue &returnedValue) const
TODO: Add documentation.
TTErr getKeys(TTValue &hashKeys)
Get an array of all of the keys for the hash table.