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