1/*---------------------------------------------------------------------------*
2 *  ArrayList.h  *
3 *                                                                           *
4 *  Copyright 2007, 2008 Nuance Communciations, Inc.                               *
5 *                                                                           *
6 *  Licensed under the Apache License, Version 2.0 (the 'License');          *
7 *  you may not use this file except in compliance with the License.         *
8 *                                                                           *
9 *  You may obtain a copy of the License at                                  *
10 *      http://www.apache.org/licenses/LICENSE-2.0                           *
11 *                                                                           *
12 *  Unless required by applicable law or agreed to in writing, software      *
13 *  distributed under the License is distributed on an 'AS IS' BASIS,        *
14 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. *
15 *  See the License for the specific language governing permissions and      *
16 *  limitations under the License.                                           *
17 *                                                                           *
18 *---------------------------------------------------------------------------*/
19
20#ifndef __ARRAYLIST_H
21#define __ARRAYLIST_H
22
23
24
25#include "ESR_ReturnCode.h"
26#include "PortPrefix.h"
27#include "ptypes.h"
28#include <stdlib.h>
29
30/**
31 * @addtogroup ArrayListModule ArrayList API functions
32 * Collection of elements.
33 *
34 * @{
35 */
36
37/**
38 * Collection of elements.
39 */
40typedef struct ArrayList_t
41{
42  /**
43   * Adds element to list.
44   *
45   * @param self ArrayList handle
46   * @param element Element to be added
47   * @return ESR_INVALID_ARGUMENT if self is null; ESR_OUT_OF_MEMORY is system is out of memory
48   */
49  ESR_ReturnCode(*add)(struct ArrayList_t* self, void* element);
50
51  /**
52   * Inserts an element in the the list at the specified location.  This
53   * causes all elements above or at the specified location to be shifted by
54   * one.
55   *
56   * @param self ArrayList handle
57   * @param index  The index where to insert the element.
58   * @param element The element to insert.
59   * @return ESR_INVALID_ARGUMENT if self is null; ESR_SUCCESS if success or anaother value indicating
60  * the nature of the error. In particular, it returns ESR_ARGUMENT_OUT_OF_BOUNDS if index
61   * is less than 0 or greater than the array's size.
62   */
63  ESR_ReturnCode(*insertAt)(struct ArrayList_t* self, size_t index,
64                            void *element);
65
66  /**
67  * Removes element from list.
68  *
69  * @param self ArrayList handle
70  * @param element Element to be removed
71   * @return ESR_INVALID_ARGUMENT if self is null; ESR_OUT_OF_MEMORY is system is out of memory
72  */
73  ESR_ReturnCode(*remove)(struct ArrayList_t* self, const void* element);
74
75  /**
76  * Removes element from list at specified index.
77  *
78  * @param self ArrayList handle
79  * @param index Index of element to be removed
80  * @return ESR_INVALID_ARGUMENT if self is null; ESR_OUT_OF_MEMORY is system is out of memory;
81  * ESR_ARGUMENT_OUT_OF_BOUNDS if index is out of bounds
82  */
83  ESR_ReturnCode(*removeAtIndex)(struct ArrayList_t* self, size_t index);
84
85  /**
86  * Removes all elements from list.
87  *
88  * @param self ArrayList handle
89  * @return ESR_INVALID_ARGUMENT if self is null
90  */
91  ESR_ReturnCode(*removeAll)(struct ArrayList_t* self);
92
93  /**
94  * Indicates if element is contained within the list.
95  *
96  * @param self ArrayList handle
97  * @param element Element to check for
98  * @param exists True if element was found
99  * @return ESR_INVALID_ARGUMENT if self is null
100  */
101  ESR_ReturnCode(*contains)(struct ArrayList_t* self, const void* element, ESR_BOOL* exists);
102
103  /**
104  * Returns array size.
105  *
106  * @param self ArrayList handle
107  * @param size Returned size
108  * @return ESR_INVALID_ARGUMENT if self is null
109  */
110  ESR_ReturnCode(*getSize)(struct ArrayList_t* self, size_t* size);
111
112  /**
113  * Returns the element at the specified index.
114  *
115  * @param self ArrayList handle
116  * @param index Element index
117  * @param element Element being returned
118  * @return ESR_INVALID_ARGUMENT if self is null; ESR_ARGUMENT_OUT_OF_BOUNDS if index is out of bounds
119  */
120  ESR_ReturnCode(*get)(struct ArrayList_t* self, size_t index, void** element);
121
122  /**
123  * Sets the element at the specified index.
124  *
125  * NOTE: Does *not* deallocate the element being overwritten.
126  * @param self ArrayList handle
127  * @param index Element index
128  * @param element Element's new value
129  * @return ESR_INVALID_ARGUMENT if self is null; ESR_ARGUMENT_OUT_OF_BOUNDS if index is out of bounds
130  */
131  ESR_ReturnCode(*set)(struct ArrayList_t* self, size_t index, void* element);
132
133  /**
134   * Converts the ArrayList to a static array.
135   * The use of the ArrayList handle is undefined past this point.
136   *
137   * @param self ArrayList handle
138   * @param newArray Pointer to resulting array
139  * @return ESR_INVALID_ARGUMENT if self is null
140   */
141  ESR_ReturnCode(*toStaticArray)(struct ArrayList_t* self, void** newArray);
142
143  /**
144  * Returns a clone of the ArrayList.
145  *
146  * @param self ArrayList handle
147   * @param clone [out] Clone of the ArrayList (created externally, populated internally)
148  * @return ESR_INVALID_ARGUMENT if self is null; ESR_ARGUMENT_OUT_OF_BOUNDS if index (used internally) is out of bounds
149  * ESR_OUT_OF_MEMORY is system is out of memory
150  */
151  ESR_ReturnCode(*clone)(struct ArrayList_t* self, struct ArrayList_t* clone);
152
153  /**
154  * Destroys the ArrayList.
155  *
156  * @param self ArrayList handle
157  * @return ESR_INVALID_ARGUMENT if self is null
158  */
159  ESR_ReturnCode(*destroy)(struct ArrayList_t* self);
160}
161ArrayList;
162
163/**
164 * Creates a new ArrayList.
165 *
166 * @param self ArrayList handle
167 * @return ESR_INVALID_ARGUMENT if self or the value it points to are null; ESR_OUT_OF_MEMORY is system is out of memory
168 */
169PORTABLE_API ESR_ReturnCode ArrayListCreate(ArrayList** self);
170
171/**
172 * Creates a new ArrayList with minimum capacity.
173 *
174 * @param self ArrayList handle
175 * @param minCapacity Minimum capacity of the array.
176 * @return ESR_INVALID_ARGUMENT if self or the value it points to are null; ESR_OUT_OF_MEMORY is system is out of memory
177 */
178PORTABLE_API ESR_ReturnCode ArrayListCreateWithCapacity(ArrayList** self, size_t minCapacity);
179
180/**
181 * Adds element to list.
182 *
183 * @param self ArrayList handle
184 * @param element Element to be added
185 * @return ESR_INVALID_ARGUMENT if self is null; ESR_OUT_OF_MEMORY is system is out of memory
186 */
187PORTABLE_API ESR_ReturnCode ArrayListAdd(ArrayList* self, void* element);
188
189
190/**
191 * Inserts an element in the the list at the specified location.  This
192 * causes all elements above or at the specified location to be shifted by
193 * one.
194 *
195 * @param self ArrayList handle
196 * @param index  The index where to insert the element.
197 * @param element The element to insert.
198 *
199 * @return ESR_SUCCESS if success or anaother value indicating the nature of
200 * the error.  In particular, it returns ESR_ARGUMENT_OUT_OF_BOUNDS if index
201 * is less than 0 or greater than the array's size.
202 */
203PORTABLE_API ESR_ReturnCode ArrayListInsertAt(ArrayList* self,
204    size_t index,
205    void *element);
206
207/**
208 * Removes element from list.
209 *
210 * @param self ArrayList handle
211 * @param element Element to be removed
212 * @return ESR_INVALID_ARGUMENT if self is null; ESR_OUT_OF_MEMORY is system is out of memory
213 */
214PORTABLE_API ESR_ReturnCode ArrayListRemove(ArrayList* self, void* element);
215/**
216 * Removes element from list at specified index.
217 *
218 * @param self ArrayList handle
219 * @param index Index of element to be removed
220 * @return ESR_INVALID_ARGUMENT if self is null; ESR_OUT_OF_MEMORY is system is out of memory;
221 * ESR_ARGUMENT_OUT_OF_BOUNDS if index is out of bounds
222 */
223PORTABLE_API ESR_ReturnCode ArrayListRemoveAtIndex(ArrayList* self, size_t index);
224
225/**
226 * Removes all elements from list.
227 *
228 * @param self ArrayList handle
229 * @return ESR_INVALID_ARGUMENT if self is null
230 */
231PORTABLE_API ESR_ReturnCode ArrayListRemoveAll(ArrayList* self);
232
233/**
234 * Indicates if element is contained within the list.
235 *
236 * @param self ArrayList handle
237 * @param element Element to check for
238 * @param exists True if element was found
239 * @return ESR_INVALID_ARGUMENT if self is null
240 */
241PORTABLE_API ESR_ReturnCode ArrayListContains(ArrayList* self, void* element, ESR_BOOL* exists);
242
243/**
244 * Returns array size.
245 *
246 * @param self ArrayList handle
247 * @param size Returned size
248 * @return ESR_INVALID_ARGUMENT if self is null
249 */
250PORTABLE_API ESR_ReturnCode ArrayListGetSize(ArrayList* self, size_t* size);
251
252/**
253 * Returns the element at the specified index.
254 *
255 * @param self ArrayList handle
256 * @param index Element index
257 * @param element Element being returned
258 * @return ESR_INVALID_ARGUMENT if self is null; ESR_ARGUMENT_OUT_OF_BOUNDS if index is out of bounds
259 */
260PORTABLE_API ESR_ReturnCode ArrayListGet(ArrayList* self, size_t index, void** element);
261
262/**
263 * Sets the element at the specified index.
264 *
265 * NOTE: Does *not* deallocate the element being overwritten.
266 * @param self ArrayList handle
267 * @param index Element index
268 * @param element Element's new value
269 * @return ESR_INVALID_ARGUMENT if self is null; ESR_ARGUMENT_OUT_OF_BOUNDS if index is out of bounds
270 */
271PORTABLE_API ESR_ReturnCode ArrayListSet(ArrayList* self, size_t index, void* element);
272
273/**
274 * Returns a clone of the ArrayList.
275 *
276 * @param self ArrayList handle
277 * @param clone [out] Clone of the ArrayList (created externally, populated internally)
278 * @return ESR_INVALID_ARGUMENT if self is null; ESR_ARGUMENT_OUT_OF_BOUNDS if index (used internally) is out of bounds
279 * ESR_OUT_OF_MEMORY is system is out of memory
280 */
281PORTABLE_API ESR_ReturnCode ArrayListClone(ArrayList* self, ArrayList* clone);
282
283/**
284 * Destroys an ArrayList.
285 *
286 * @param self ArrayList handle
287 * @return ESR_INVALID_ARGUMENT if self is null
288 */
289PORTABLE_API ESR_ReturnCode ArrayListDestroy(ArrayList* self);
290
291/**
292 * @}
293 */
294
295#endif /* __ARRAYLIST_H */
296