1 /* 2 Copyright (C) 2003 Commonwealth Scientific and Industrial Research 3 Organisation (CSIRO) Australia 4 5 Redistribution and use in source and binary forms, with or without 6 modification, are permitted provided that the following conditions 7 are met: 8 9 - Redistributions of source code must retain the above copyright 10 notice, this list of conditions and the following disclaimer. 11 12 - Redistributions in binary form must reproduce the above copyright 13 notice, this list of conditions and the following disclaimer in the 14 documentation and/or other materials provided with the distribution. 15 16 - Neither the name of CSIRO Australia nor the names of its 17 contributors may be used to endorse or promote products derived from 18 this software without specific prior written permission. 19 20 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 21 ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 22 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 23 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE ORGANISATION OR 24 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 25 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 26 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 27 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 28 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 29 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 30 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31 */ 32 33 #ifndef __OGGZ_VECTOR_H__ 34 #define __OGGZ_VECTOR_H__ 35 36 typedef void OggzVector; 37 38 typedef int (*OggzFunc) (void * data); 39 typedef int (*OggzFunc1) (void * data, void *arg); 40 typedef int (*OggzFindFunc) (void * data, long serialno); 41 typedef int (*OggzCmpFunc) (const void * a, const void * b, void * user_data); 42 43 /** 44 * Create a new vector object. 45 * \retval a pointer to the new vector. 46 * \retval NULL on failure. 47 */ 48 OggzVector * 49 oggz_vector_new (void); 50 51 /** 52 * Destroy a vector object. 53 */ 54 void 55 oggz_vector_delete (OggzVector * vector); 56 57 void * 58 oggz_vector_find_p (OggzVector * vector, const void * data); 59 60 int 61 oggz_vector_find_index_p (OggzVector * vector, const void * data); 62 63 void * 64 oggz_vector_find_with (OggzVector * vector, OggzFindFunc func, long serialno); 65 66 void * 67 oggz_vector_nth_p (OggzVector * vector, int n); 68 69 long 70 oggz_vector_nth_l (OggzVector * vector, int n); 71 72 /** 73 * Call a function on each element of a vector, in order. 74 * \param vector The OggzVector to iterate over 75 * \param func The OggzFunc to be called on each element 76 * \retval 0 on success 77 */ 78 int 79 oggz_vector_foreach (OggzVector * vector, OggzFunc func); 80 81 /** 82 * Call a function with a userdata pointer on each element 83 * of a vector, in order. This allows the function to access 84 * shared data when operating on the element sequence. 85 * \param vector The OggzVector to iterate over 86 * \param func The OggzFunc1 to be called on each element 87 * \param arg The userdata pointer to be passed to the function 88 * along with the vector member 89 * \retval 0 on success 90 */ 91 int 92 oggz_vector_foreach1 (OggzVector * vector, OggzFunc1 func, void *arg); 93 94 /** 95 * Return the number of elements in a vector. 96 * \param vector The vector to query 97 * \retval The number of elements 98 */ 99 int 100 oggz_vector_size (OggzVector * vector); 101 102 /** 103 * Add an element to a vector. If the vector has a comparison function, 104 * the new element is inserted in sorted order, otherwise it is appended 105 * to the tail. Use this function to add pointer elements to the vector. 106 * Use ogg_vector_insert_l for long values. 107 * \param vector An OggzVector 108 * \param data The new element to add 109 * \retval data If the element was successfully added 110 * \retval NULL If adding the element failed due to a realloc() error 111 */ 112 void * 113 oggz_vector_insert_p (OggzVector * vector, void * data); 114 115 /** 116 * Add an element to a vector. If the vector has a comparison function, 117 * the new element is inserted in sorted order, otherwise it is appended 118 * to the tail. Use this function to add long value elements to the 119 * vector. Use ogg_vector_insert_p for pointer values. 120 * \param vector An OggzVector 121 * \param ldata The new element to add 122 * \retval ldata If the element was successfully added 123 * \retval -1L If adding the element failed 124 */ 125 long 126 oggz_vector_insert_l (OggzVector * vector, long ldata); 127 128 /** 129 * Remove a (void *) element of a vector 130 * \retval \a vector on success 131 * \retval NULL on failure (realloc error) 132 */ 133 OggzVector * 134 oggz_vector_remove_p (OggzVector * vector, void * data); 135 136 /** 137 * Remove a (long) element of a vector 138 * \retval \a vector on success 139 * \retval NULL on failure (realloc error) 140 */ 141 OggzVector * 142 oggz_vector_remove_l (OggzVector * vector, long ldata); 143 144 /** 145 * Set a comparison function for a vector. 146 * Vectors can be sorted, or stored in append order, depending on 147 * whether they have a comparison function defined. When a comparison 148 * function is first set, it will be used to sort the entire vector, 149 * and subsequence insertions will maintain the sort. If no comparison 150 * function is set, new elements are appended at the end of the vector. 151 * Call oggz_vector_set_cmp(vector, NULL, NULL) to remove the current 152 * comparison function. This does not affect the member order. 153 * \param vector the vector to associate the comparison function with 154 * \param compare the OggzCmpFunc to use for comparisons 155 * \param user_data private data pointer for the compare function 156 * \retval 0 on success 157 */ 158 int 159 oggz_vector_set_cmp (OggzVector * vector, OggzCmpFunc compare, 160 void * user_data); 161 162 /** 163 * Pop a member off a vector. 164 * \retval pointer to the popped member 165 * \retval NULL if the vector is empty 166 */ 167 void * 168 oggz_vector_pop (OggzVector * vector); 169 170 #endif /* __OGGZ_VECTOR_H__ */ 171