GL Studio C++ Runtime API
list.h
Go to the documentation of this file.
1/// \file list.h
2/// \brief The List_c class. Generic linked list.
3///
4/// \par Copyright Information
5///
6/// Copyright (c) 2017 by The DiSTI Corporation.<br>
7/// 12249 Science Drive; Suite 300<br>
8/// Orlando, Florida 32826<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#ifndef INCLUDED_GLS_LIST_H
40#define INCLUDED_GLS_LIST_H
41
42/* Includes */
43#include "disti_include.h"
44#include <stdio.h>
45
46namespace disti
47{
48/** \class ListItem
49 * Implements a list item for use in a List_c
50 */
52{
53public:
54 /** Creates a ListItem given data. This method will allocate storage
55 * for the data passed in.
56 * \param data A pointer to data to copy
57 * \param len Length of data to copy
58 */
59 DISTI_EXPORT ListItem( const void* data, int len );
60
61 /** Creates a ListItem without allocating internal storage. */
62 DISTI_EXPORT ListItem();
63
64 /** Destroys a ListItem, deallocating any storage the item has allocated */
65 virtual DISTI_EXPORT ~ListItem();
66
67 /** \return The data member of this ListItem. */
68 DISTI_EXPORT void* Data();
69
70 /** \return What the data member of this ListItem is pointing to (a double indirection) */
71 DISTI_EXPORT void* DataPtr();
72
73 /** \return The ListItem after this in the list, or NULL if there is no next ListItem */
74 DISTI_EXPORT ListItem* Next();
75
76 /** \return The ListItem before this in the list, or NULL if there is no previous ListItem */
77 DISTI_EXPORT ListItem* Prev();
78
79 /** \return The priority of this ListItem */
80 DISTI_EXPORT int Priority() const { return _priority; }
81
82 /** Set the Next ListItem in the List
83 * \param pNext Pointer to the item that will become this item's next item
84 */
85 DISTI_EXPORT void Next( ListItem* pNext );
86
87 /** Set the Previous ListItem in the List
88 * \param pPrev Pointer to the item that will become this item's previous item
89 */
90 DISTI_EXPORT void Prev( ListItem* pPrev );
91
92 /** Set the data associated with this item.
93 * This merely changes the value of the Data pointer, it does not allocate or copy data
94 * \param item The new data for this item
95 */
96 DISTI_EXPORT void Data( void* item );
97
98 /** Change the priority of this list item.
99 * NOTE: Changing an item's priority does not resort the list.
100 * \param priority The new priority of the list item
101 */
102 DISTI_EXPORT void Priority( int priority );
103
104 /** Allocates the specified amount of data for the item. Does not
105 * deallocate the old data!
106 * \param size Size of the data to allocate
107 */
108 DISTI_EXPORT void AllocateItemData( int size );
109
110private:
111 ListItem* _next; ///< Pointer to next list item.
112 ListItem* _prev; ///< Pointer to previous list item.
113 int _priority; ///< Item priority, used for priority queue behavior.
114
115protected:
116 void* _data; ///< Pointer to list item data.
117};
118
119typedef void ( *ListIterator )( void* obj, void* data ); ///< Typedef for a list iterator function pointer.
120
121/**
122 List Iterator Direction
123*/
124typedef enum
125{
126 FORWARD,
127 BACKWARD
129
130/** \class List_c
131 * Implements a doubly Linked List
132 */
134{
135public:
136 DISTI_EXPORT List_c();
137 virtual DISTI_EXPORT ~List_c();
138
139 int _count; ///< Number of items in the list.
140
141 /** Returns whether or not the list is empty
142 * \return Whether or not the list is empty
143 */
144 DISTI_EXPORT int IsEmpty();
145
146 /** Empties the list (deletes all the elements) */
147 DISTI_EXPORT void Empty();
148
149 /** Get a pointer to the first ListItem in the list
150 * \return Pointer to the first ListItem in the list or NULL if the list
151 * is empty
152 */
153 DISTI_EXPORT ListItem* First();
154
155 /** Get a pointer to the first ListItem in the list
156 * \return Pointer to the first ListItem in the list or NULL if the list
157 * is empty
158 */
159 DISTI_EXPORT ListItem* Last();
160
161 /** Get a pointer to the ListItem for the Nth element
162 * \param where 0 based array index
163 * \return Pointer to the ListItem at that index or NULL if the list is empty
164 */
165 DISTI_EXPORT ListItem* Nth( int where );
166
167 /** Inserts the given data at designated index in the list. If the index is greater than the
168 * list size, the element will be inserted at the end of the list
169 * A new ListItem will be allocated, space will be allocated for the data passed in
170 * \param where The zero based index
171 * \param data Pointer to the data to insert
172 * \param size Size of the data to insert
173 * \param parentPtr Will be filled in with a pointer to the ListItem that this method allocates
174 */
175 DISTI_EXPORT void InsertAfter( int where, const void* data, int size, void** parentPtr );
176
177 /** Inserts the given data after the specified list item
178 * A new ListItem will be allocated, space will be allocated for the data passed in
179 * \param after Pointer to the list element to insert after
180 * \param data Pointer to the data to insert
181 * \param size Size of the data to insert
182 * \param parentPtr Will be filled in with a pointer to the ListItem that this method allocates
183 */
184 DISTI_EXPORT void InsertAfter( ListItem* after, const void* data, int size, void** parentPtr );
185
186 /** Inserts the given list element after the specified list element
187 * \param after Pointer to the list element to insert after
188 * \param pNewNode A previously allocated ListItem to insert
189 */
190 DISTI_EXPORT void InsertAfter( ListItem* after, ListItem* pNewNode );
191
192 /** Inserts the given list element before the specified list element
193 * \param before Pointer to the list element to insert before
194 * \param pNewNode A previously allocated ListItem to insert
195 */
196 DISTI_EXPORT void InsertBefore( ListItem* before, ListItem* pNewNode );
197
198 /** Inserts the given data at the front of the list.
199 * A new ListItem will be allocated, space will be allocated for the data passed in
200 * \param data Pointer to the data to insert
201 * \param size Size of the data to insert
202 * \param parentPtr Will be filled in with a pointer to the ListItem that this method allocates
203 */
204 DISTI_EXPORT void Push( const void* data, int size, void** parentPtr );
205
206 /** Inserts the given data at the front of the list.
207 * A new ListItem will be allocated, space will be allocated for the data passed in
208 * \param data Pointer to the data to insert
209 * \param size Size of the data to insert
210 */
211 DISTI_EXPORT void Push( const void* data, int size );
212
213 /** Inserts the given list element at the front of the list
214 * \param pNewNode A previously allocated ListItem to insert
215 */
216 DISTI_EXPORT void Push( ListItem* pNewNode );
217
218 /** Inserts the given data at the end of the list.
219 * A new ListItem will be allocated, space will be allocated for the data passed in
220 * \param data Pointer to the data to insert
221 * \param size Size of the data to insert
222 * \param parentPtr Will be filled in with a pointer to the ListItem that this method allocates
223 */
224 DISTI_EXPORT void Enqueue( const void* data, int size, void** parentPtr );
225
226 /** Inserts the given data at the end of the list.
227 * A new ListItem will be allocated, space will be allocated for the data passed in
228 * \param data Pointer to the data to insert
229 * \param size Size of the data to insert
230 */
231 DISTI_EXPORT void Enqueue( const void* data, int size );
232
233 /** Inserts the given list element at the end of the list
234 * \param pNewNode A previously allocated ListItem to insert
235 */
236 DISTI_EXPORT void Enqueue( ListItem* pNewNode );
237
238 /** Gets a pointer to the data in the first element of the list.
239 * The list element will be freed. The user should free the data
240 * returned by this call.
241 * \return Data pointed to by the first element in the list or NULL
242 * if the list is empty
243 */
244 DISTI_EXPORT void* Dequeue();
245
246 /// Gets a pointer to the data at the given "index" into the list.
247 /// \param where The index into the list.
248 /// \return A pointer to the data or NULL if the index is invalid.
249 DISTI_EXPORT void* GetElement( int where );
250
251 /** \return The number of items in this list */
252 DISTI_EXPORT int Count();
253
254 /** Deletes the specified list element. Frees the data pointed to by the element.
255 * \param element The element to delete
256 */
257 DISTI_EXPORT void Delete( ListItem* element );
258
259 /** Adds a new node (item) to the list. The item position will be determined based on its priority.
260 * \param pNewNode A previously allocated list node containing the data to add
261 * \param priority Sorting priority
262 */
263 DISTI_EXPORT void AddNodeWithPriority( ListItem* pNewNode, int priority );
264
265 /** Adds a new node (item) to the list. The item position will be determined based on its priority.
266 * This method will dynamically allocate space for the data
267 * \param data Pointer to the data to be added
268 * \param size Size of the data to be added
269 * \param priority Sorting priority
270 */
271 DISTI_EXPORT void AddNodeWithPriority( const void* data, int size, int priority );
272
273 /** Iterates through the list from head to tail, calling the supplied function on each element
274 * and passing the supplied data to that function
275 * \param func ListIterator function to call
276 * \param data Data that will be supplied to each call of the list iterator function
277 */
278 DISTI_EXPORT void ForwardIterator( ListIterator func, void* data = NULL );
279
280 /** Iterates through the list in reverse order, calling the supplied function on each element
281 * and passing the supplied data to that function
282 * \param func ListIterator function to call
283 * \param data Data that will be supplied to each call of the list iterator function
284 */
285 DISTI_EXPORT void BackwardIterator( ListIterator func, void* data = NULL );
286
287 /** Iterates through the list in the specified direction, calling the supplied function on each element
288 * and passing the supplied data to that function
289 * \param func ListIterator function to call
290 * \param data Data that will be supplied to each call of the list iterator function
291 * \param direction Which directon to iterate
292 */
293 DISTI_EXPORT void Iterator( ListIterator func, void* data, ListIteratorDirection direction );
294
295protected:
296 ListItem* _pHead; ///< Pointer to the head (first item) of the list.
297 ListItem* _pTail; ///< Pointer to the tail (last item) of the list.
298};
299
300} // namespace disti
301
302#endif
Definition: list.h:52
int Priority() const
Definition: list.h:80
ListItem * Prev()
void * DataPtr()
void * _data
Pointer to list item data.
Definition: list.h:116
void AllocateItemData(int size)
ListItem * Next()
virtual ~ListItem()
Definition: list.h:134
void InsertAfter(int where, const void *data, int size, void **parentPtr)
void InsertBefore(ListItem *before, ListItem *pNewNode)
void Delete(ListItem *element)
ListItem * First()
void AddNodeWithPriority(ListItem *pNewNode, int priority)
void Iterator(ListIterator func, void *data, ListIteratorDirection direction)
ListItem * _pTail
Pointer to the tail (last item) of the list.
Definition: list.h:297
int _count
Number of items in the list.
Definition: list.h:139
void BackwardIterator(ListIterator func, void *data=NULL)
ListItem * Last()
void ForwardIterator(ListIterator func, void *data=NULL)
void * Dequeue()
ListItem * _pHead
Pointer to the head (first item) of the list.
Definition: list.h:296
ListItem * Nth(int where)
void Push(const void *data, int size, void **parentPtr)
void Enqueue(const void *data, int size, void **parentPtr)
void * GetElement(int where)
A file for all GL Studio files to include.
Definition: bmpimage.h:46
ListIteratorDirection
Definition: list.h:125
void(* ListIterator)(void *obj, void *data)
Typedef for a list iterator function pointer.
Definition: list.h:119