Jamoma API  0.6.0.a19
TTList.h
1 /*
2  * TTBlue (Linked) List Class
3  * Copyright © 2008, Timothy Place
4  *
5  * License: This code is licensed under the terms of the "New BSD License"
6  * http://creativecommons.org/licenses/BSD/
7  */
8 
9 #ifndef __TT_LIST_H__
10 #define __TT_LIST_H__
11 
12 #include "TTBase.h"
13 #include "TTValue.h"
14 #include "TTMutex.h"
15 #include <list>
16 
17 class TTObjectBase;
18 typedef std::list<TTValue> TTLinkedList;
19 typedef std::list<TTValue>::iterator TTListIter;
21 
22 /****************************************************************************************************/
23 // Class Specification
24 
25 class TTFOUNDATION_EXPORT TTList {
26 private:
27  TTBoolean mThreadProtection; ///< Use thread safety mechanisms. Only disable this if you are certain that you will be calling from a single thread.
28  TTMutexPtr mMutex;
29 
30  #ifdef TT_PLATFORM_WIN
31  #pragma warning(disable:4251)
32  #endif
33  TTLinkedList theList;
34  TTListIter theIter;
35 
36  void lock();
37  void unlock();
38 
39 public:
40  TTList();
41  virtual ~TTList();
42  TTList(TTList& that);
43 
44  /** Determine the number of values in the list.
45  @return The count of the values in the list. */
46  TTUInt32 getSize() const;
47 
48  /** Determine whether the list has any items.
49  @return True if the list is empty, otherwise false. */
50  TTBoolean isEmpty();
51 
52  /** Return the first value in the list.
53  @return The first value in the list. */
54  TTValue& getHead();
55 
56  /** Return the last value in the list.
57  @return The last value in the list. */
58  TTValue& getTail();
59 
60  /** Put the iterator pointing to the beginning of the list. */
61  void begin();
62 
63  /** Is the iterator points to the end of the list ?
64  @return false if the iterator is at the end of the list */
65  bool end();
66 
67  /** Put the iterator pointing to the next position */
68  void next();
69 
70  /** Put the iterator pointing to the prev position */
71  void prev();
72 
73  /** Returns the current value in the list (where the iterator is).
74  @return The current value. */
75  TTValue& current();
76 
77  /** Return a value by it's location in the list. */
78  TTErr getIndex(TTUInt32 index, TTValue& returnedValue);
79 
80  /** Appends a value to the list.
81  @param newValue The value to add to the list. */
82  void append(const TTValue& newValue);
83 
84 
85  /** If we don't define a version of this function that takes a pointer,
86  then when a pointer is provided a new temporary TTValue is created to provide the reference
87  and then when the temporary is deleted we end up with a corrupt entry in the linked list. */
88 /* void append(const TTValuePtr newValue)
89  {
90  append(*newValue);
91  }
92 */
93  void appendUnique(const TTValue& newValue);
94 
95  /** Insert a value into the list at a given location.
96  @param index The location of the value after insertion.
97  @param newValue The value to add to the list.
98  @return kTTErrGeneric if the value can't be inserted (bad index) */
99  void insert(TTUInt32 index, const TTValue& newValue);
100 
101  /** If we don't define a version of this function that takes a pointer,
102  then when a pointer is provided a new temporary TTValue is created to provide the reference
103  and then when the temporary is deleted we end up with a corrupt entry in the linked list. */
104 /* void insert(TTUInt32 index, const TTValuePtr newValue)
105  {
106  insert(index, *newValue);
107  }
108 */
109  /** Appends a list to the list.
110  @param newList The list to add to the list. */
111  void merge(TTList& newList);
112 
113  /** Sort a list using a comparison function
114  @param comparisonFunction which return true if the first element have to be before the second */
115  void sort(TTBoolean(*comparisonFunction)(TTValue&, TTValue&) = NULL);
116 
117  /** Find a value in the list by using a passed-in matching function. */
118  TTErr find(TTFunctionMatch aMatchFunction, TTPtr aBaton, TTValue& returnedValue);
119 
120  /** Find a value in the list that is equal to a value passed-in. */
121  TTErr findEquals(const TTValue& valueToCompareAgainst, TTValue& foundValue);
122 
123  /** Remove the specified value.
124  This doesn't change the value or free it, it just removed the pointer to it from the list.
125  @param The value to remove. */
126  void remove(const TTValue& value);
127 
128  /** Remove all values from the list */
129  void clear();
130 
131  /** Remove all values from the list and free them. */
132  void free();
133 
134  /** Assign the contents of the list to a value as an array. */
135  void assignToValue(TTValue& value);
136 
137 
138  /** Traverse the entire list, sending each item of the list to a specified function. */
139  TTErr iterate(const TTObjectBasePtr target, const TTFunctionWithBatonAndValue callback);
140 
141  /** Traverse the entire list, sending each item of the list to a specified object with the specified message. */
142  TTErr iterate(const TTObjectBasePtr target, const TTSymbol messageName);
143 
144  /** Traverse the entire list, and if the item in the list is an object, then send it the specified message. */
145  TTErr iterateObjectsSendingMessage(const TTSymbol messageName);
146  TTErr iterateObjectsSendingMessage(const TTSymbol messageName, TTValue& aValue);
147 
148 
149  void setThreadProtection(TTBoolean threadProtection)
150  {
151  mThreadProtection = threadProtection;
152  }
153 };
154 
155 
156 typedef TTList* TTListPtr;
157 
158 
159 #endif // __TT_LIST_H__
160 
bool TTBoolean
Boolean flag, same as Boolean on the Mac.
Definition: TTBase.h:167
Base class for all first-class Jamoma objects.
Definition: TTObjectBase.h:109
void * TTPtr
A generic pointer.
Definition: TTBase.h:248
Jamoma's lowest-level base class and related infrastructure.
The TTSymbol class is used to represent a string and efficiently pass and compare that string...
Definition: TTSymbol.h:26
void(* TTFunctionMatch)(const TTValue &valueToCheck, TTPtr baton, TTBoolean &found)
Use for finding stuff in a list or a hash or a dictionary.
Definition: TTBase.h:262
TTErr
Jamoma Error Codes Enumeration of error codes that might be returned by any of the TTBlue functions a...
Definition: TTBase.h:342
TTErr(* TTFunctionWithBatonAndValue)(const TTValue &, const TTValue &)
A simple/generic function pointer with a baton as TTValueRef and the value to send back as a TTValueR...
Definition: TTBase.h:361
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