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 */ 40 typedef 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 } 161 ArrayList; 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 */ 169 PORTABLE_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 */ 178 PORTABLE_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 */ 187 PORTABLE_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 */ 203 PORTABLE_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 */ 214 PORTABLE_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 */ 223 PORTABLE_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 */ 231 PORTABLE_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 */ 241 PORTABLE_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 */ 250 PORTABLE_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 */ 260 PORTABLE_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 */ 271 PORTABLE_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 */ 281 PORTABLE_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 */ 289 PORTABLE_API ESR_ReturnCode ArrayListDestroy(ArrayList* self); 290 291 /** 292 * @} 293 */ 294 295 #endif /* __ARRAYLIST_H */ 296