GL Studio API
list.h
Go to the documentation of this file.
1 /*! \file
2  \brief The List_c class. Generic linked list.
3 
4  \par Copyright Information
5 
6  Copyright (c) 2015 by The DiSTI Corporation.<br>
7  11301 Corporate Blvd; Suite 100<br>
8  Orlando, Florida 32817<br>
9  USA<br>
10  <br>
11  All rights reserved.<br>
12 
13  This Software contains proprietary trade secrets of DiSTI and may not be
14 reproduced, in whole or part, in any form, or by any means of electronic,
15 mechanical, or otherwise, without the written permission of DiSTI. Said
16 permission may be derived through the purchase of applicable DiSTI product
17 licenses which detail the distribution rights of this content and any
18 Derivative Works based on this or other copyrighted DiSTI Software.
19 
20  NO WARRANTY. THE SOFTWARE IS PROVIDED "AS-IS," WITHOUT WARRANTY OF ANY KIND,
21 AND ANY USE OF THIS SOFTWARE PRODUCT IS AT YOUR OWN RISK. TO THE MAXIMUM EXTENT
22 PERMITTED BY APPLICABLE LAW, DISTI AND ITS SUPPLIERS DISCLAIM ALL WARRANTIES
23 AND CONDITIONS, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
24 IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY AND/OR FITNESS FOR A
25 PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT, WITH REGARD TO THE SOFTWARE.
26 
27  LIMITATION OF LIABILITY. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW,
28 IN NO EVENT SHALL DISTI OR ITS SUPPLIERS BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
29 INDIRECT, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION,
30 DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS
31 INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR
32 INABILITY TO USE THE SOFTWARE, EVEN IF DISTI HAS BEEN ADVISED OF THE POSSIBILITY
33 OF SUCH DAMAGES. DISTI'S ENTIRE LIABILITY AND YOUR EXCLUSIVE REMEDY SHALL NOT
34 EXCEED FIVE DOLLARS (US$5.00).
35 
36  The aforementioned terms and restrictions are governed by the laws of the
37 State of Florida and the United States of America.
38 
39 */
40 #ifndef INCLUDED_GLS_LIST_H
41 #define INCLUDED_GLS_LIST_H
42 
43 /* Includes */
44 #include "disti_include.h"
45 #include <stdio.h>
46 
47 namespace disti
48 {
49 
50 /** \class ListItem
51  * Implements a list item for use in a List_c
52  */
53 class ListItem
54 {
55 public:
56  /** Creates a ListItem given data. This method will allocate storage
57  * for the data passed in.
58  * \param data A pointer to data to copy
59  * \param len Length of data to copy
60  */
61  DISTI_EXPORT ListItem(const void* data,int len);
62 
63  /** Creates a ListItem without allocating internal storage. */
64  DISTI_EXPORT ListItem();
65 
66  /** Destroys a ListItem, deallocating any storage the item has allocated */
67  virtual DISTI_EXPORT ~ListItem();
68 
69  /** \return The data member of this ListItem. */
70  DISTI_EXPORT void* Data();
71 
72  /** \return What the data member of this ListItem is pointing to (a double indirection) */
73  DISTI_EXPORT void* DataPtr();
74 
75  /** \return The ListItem after this in the list, or NULL if there is no next ListItem */
76  DISTI_EXPORT ListItem* Next();
77 
78  /** \return The ListItem before this in the list, or NULL if there is no previous ListItem */
79  DISTI_EXPORT ListItem* Prev();
80 
81  /** \return The priority of this ListItem */
82  DISTI_EXPORT int Priority() const { return _priority; }
83 
84  /** Set the Next ListItem in the List
85  * \param pNext Pointer to the item that will become this item's next item
86  */
87  DISTI_EXPORT void Next(ListItem* pNext);
88 
89  /** Set the Previous ListItem in the List
90  * \param pPrev Pointer to the item that will become this item's previous item
91  */
92  DISTI_EXPORT void Prev(ListItem* pPrev);
93 
94  /** Set the data associated with this item.
95  * This merely changes the value of the Data pointer, it does not allocate or copy data
96  * \param item The new data for this item
97  */
98  DISTI_EXPORT void Data(void* item);
99 
100  /** Change the priority of this list item.
101  * NOTE: Changing an item's priority does not resort the list.
102  * \param priority The new priority of the list item
103  */
104  DISTI_EXPORT void Priority(int priority);
105 
106  /** Allocates the specified amount of data for the item. Does not
107  * deallocate the old data!
108  * \param size Size of the data to allocate
109  */
110  DISTI_EXPORT void AllocateItemData(int size);
111 
112 private:
113  ListItem* _next; /** Pointer to next list item */
114  ListItem* _prev; /** Pointer to previous list item */
115  int _priority; /** Item priority, used for priority queue behavior */
116 
117 protected:
118  void* _data; /** Pointer to list item data */
119 };
120 
121 typedef void (*ListIterator)(void* obj,void* data);
122 
123 /**
124  List Iterator Direction
125 */
126 typedef enum
127 {
128  FORWARD,
129  BACKWARD
131 
132 /** \class List_c
133  * Implements a doubly Linked List
134  */
135 class List_c
136 {
137 public:
138 
139  DISTI_EXPORT List_c();
140  virtual DISTI_EXPORT ~List_c();
141 
142  int _count; /** Number of items in the list */
143 
144  /** Returns whether or not the list is empty
145  * \return Whether or not the list is empty
146  */
147  DISTI_EXPORT int IsEmpty();
148 
149  /** Empties the list (deletes all the elements) */
150  DISTI_EXPORT void Empty();
151 
152  /** Get a pointer to the first ListItem in the list
153  * \return Pointer to the first ListItem in the list or NULL if the list
154  * is empty
155  */
156  DISTI_EXPORT ListItem* First();
157 
158  /** Get a pointer to the first ListItem in the list
159  * \return Pointer to the first ListItem in the list or NULL if the list
160  * is empty
161  */
162  DISTI_EXPORT ListItem* Last();
163 
164  /** Get a pointer to the ListItem for the Nth element
165  * \param where 0 based array index
166  * \return Pointer to the ListItem at that index or NULL if the list is empty
167  */
168  DISTI_EXPORT ListItem* Nth(int where);
169 
170  /** Inserts the given data at designated index in the list. If the index is greater than the
171  * list size, the element will be inserted at the end of the list
172  * A new ListItem will be allocated, space will be allocated for the data passed in
173  * \param where The zero based index
174  * \param data Pointer to the data to insert
175  * \param size Size of the data to insert
176  * \param parentPtr Will be filled in with a pointer to the ListItem that this method allocates
177  */
178  DISTI_EXPORT void InsertAfter(int where,const void* data,int size, void** parentPtr);
179 
180  /** Inserts the given data after the specified list item
181  * A new ListItem will be allocated, space will be allocated for the data passed in
182  * \param after Pointer to the list element to insert after
183  * \param data Pointer to the data to insert
184  * \param size Size of the data to insert
185  * \param parentPtr Will be filled in with a pointer to the ListItem that this method allocates
186  */
187  DISTI_EXPORT void InsertAfter(ListItem* after,const void* data,int size,void** parentPtr);
188 
189  /** Inserts the given list element after the specified list element
190  * \param after Pointer to the list element to insert after
191  * \param pNewNode A previously allocated ListItem to insert
192  */
193  DISTI_EXPORT void InsertAfter(ListItem* after,ListItem* pNewNode);
194 
195  /** Inserts the given list element before the specified list element
196  * \param before Pointer to the list element to insert before
197  * \param pNewNode A previously allocated ListItem to insert
198  */
199  DISTI_EXPORT void InsertBefore(ListItem* before,ListItem* pNewNode);
200 
201  /** Inserts the given data at the front of the list.
202  * A new ListItem will be allocated, space will be allocated for the data passed in
203  * \param data Pointer to the data to insert
204  * \param size Size of the data to insert
205  * \param parentPtr Will be filled in with a pointer to the ListItem that this method allocates
206  */
207  DISTI_EXPORT void Push(const void* data,int size,void** parentPtr);
208 
209  /** Inserts the given data at the front of the list.
210  * A new ListItem will be allocated, space will be allocated for the data passed in
211  * \param data Pointer to the data to insert
212  * \param size Size of the data to insert
213  */
214  DISTI_EXPORT void Push(const void* data,int size);
215 
216  /** Inserts the given list element at the front of the list
217  * \param pNewNode A previously allocated ListItem to insert
218  */
219  DISTI_EXPORT void Push(ListItem* pNewNode);
220 
221  /** Inserts the given data at the end of the list.
222  * A new ListItem will be allocated, space will be allocated for the data passed in
223  * \param data Pointer to the data to insert
224  * \param size Size of the data to insert
225  * \param parentPtr Will be filled in with a pointer to the ListItem that this method allocates
226  */
227  DISTI_EXPORT void Enqueue(const void* data, int size, void** parentPtr);
228 
229  /** Inserts the given data at the end of the list.
230  * A new ListItem will be allocated, space will be allocated for the data passed in
231  * \param data Pointer to the data to insert
232  * \param size Size of the data to insert
233  */
234  DISTI_EXPORT void Enqueue(const void* data,int size);
235 
236  /** Inserts the given list element at the end of the list
237  * \param pNewNode A previously allocated ListItem to insert
238  */
239  DISTI_EXPORT void Enqueue(ListItem* pNewNode);
240 
241  /** Gets a pointer to the data in the first element of the list.
242  * The list element will be freed. The user should free the data
243  * returned by this call.
244  * \return Data pointed to by the first element in the list or NULL
245  * if the list is empty
246  */
247  DISTI_EXPORT void* Dequeue();
248 
249  /** Gets a pointer to the data at the given "index" into the list
250  * \return A pointer to the data or NULL if the index is invalid
251  */
252  DISTI_EXPORT void* GetElement(int where);
253 
254  /** \return The number of items in this list */
255  DISTI_EXPORT int Count();
256 
257  /** Deletes the specified list element. Frees the data pointed to by the element.
258  * \param element The element to delete
259  */
260  DISTI_EXPORT void Delete(ListItem* element);
261 
262  /** Adds a new node (item) to the list. The item position will be determined based on its priority.
263  * \param pNewNode A previously allocated list node containing the data to add
264  * \param priority Sorting priority
265  */
266  DISTI_EXPORT void AddNodeWithPriority(ListItem* pNewNode,int priority);
267 
268  /** Adds a new node (item) to the list. The item position will be determined based on its priority.
269  * This method will dynamically allocate space for the data
270  * \param data Pointer to the data to be added
271  * \param size Size of the data to be added
272  * \param priority Sorting priority
273  */
274  DISTI_EXPORT void AddNodeWithPriority(const void* data,int size,int priority);
275 
276  /** Iterates through the list from head to tail, calling the supplied function on each element
277  * and passing the supplied data to that function
278  * \param func ListIterator function to call
279  * \param data Data that will be supplied to each call of the list iterator function
280  */
281  DISTI_EXPORT void ForwardIterator(ListIterator func, void* data=NULL);
282 
283  /** Iterates through the list in reverse order, calling the supplied function on each element
284  * and passing the supplied data to that function
285  * \param func ListIterator function to call
286  * \param data Data that will be supplied to each call of the list iterator function
287  */
288  DISTI_EXPORT void BackwardIterator(ListIterator func, void* data=NULL);
289 
290  /** Iterates through the list in the specified direction, calling the supplied function on each element
291  * and passing the supplied data to that function
292  * \param func ListIterator function to call
293  * \param data Data that will be supplied to each call of the list iterator function
294  * \param direction Which directon to iterate
295  */
296  DISTI_EXPORT void Iterator(ListIterator func, void* data, ListIteratorDirection direction);
297 
298 protected:
299  ListItem* _pHead; /** Pointer to the head (first item) of the list */
300  ListItem* _pTail; /** Pointer to the tail (last item) of the list */
301 };
302 
303 } // namespace disti
304 
305 #endif
void InsertBefore(ListItem *before, ListItem *pNewNode)
void Enqueue(const void *data, int size, void **parentPtr)
void ForwardIterator(ListIterator func, void *data=NULL)
void * GetElement(int where)
void AddNodeWithPriority(ListItem *pNewNode, int priority)
ListItem * Last()
void Push(const void *data, int size, void **parentPtr)
A file for all GL Studio files to include.
void Delete(ListItem *element)
void * Dequeue()
void * DataPtr()
void * _data
Definition: list.h:118
int Priority() const
Definition: list.h:82
void AllocateItemData(int size)
void InsertAfter(int where, const void *data, int size, void **parentPtr)
ListIteratorDirection
Definition: list.h:126
ListItem * Nth(int where)
Definition: list.h:53
void Iterator(ListIterator func, void *data, ListIteratorDirection direction)
ListItem * Prev()
void BackwardIterator(ListIterator func, void *data=NULL)
ListItem * Next()
ListItem * First()
virtual ~ListItem()
Definition: bmpimage.h:46
ListItem * _pTail
Definition: list.h:300
Definition: list.h:135