oggz_vector.h 5.71 KB
Newer Older
andre's avatar
andre committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35
/*
   Copyright (C) 2003 Commonwealth Scientific and Industrial Research
   Organisation (CSIRO) Australia

   Redistribution and use in source and binary forms, with or without
   modification, are permitted provided that the following conditions
   are met:

   - Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.

   - Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.

   - Neither the name of CSIRO Australia nor the names of its
   contributors may be used to endorse or promote products derived from
   this software without specific prior written permission.

   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
   ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
   PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE ORGANISATION OR
   CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
   EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
   PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
   PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
   LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
   NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
   SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/

#ifndef __OGGZ_VECTOR_H__
#define __OGGZ_VECTOR_H__

conrad's avatar
conrad committed
36
typedef void OggzVector;
andre's avatar
andre committed
37 38

typedef int (*OggzFunc) (void * data);
39
typedef int (*OggzFunc1) (void * data, void *arg);
andre's avatar
andre committed
40
typedef int (*OggzFindFunc) (void * data, long serialno);
41
typedef int (*OggzCmpFunc) (const void * a, const void * b, void * user_data);
andre's avatar
andre committed
42

43 44 45 46 47
/**
 * Create a new vector object.
 * \retval a pointer to the new vector.
 * \retval NULL on failure.
 */
andre's avatar
andre committed
48
OggzVector *
conrad's avatar
conrad committed
49
oggz_vector_new (void);
andre's avatar
andre committed
50

51 52 53
/**
 * Destroy a vector object.
 */
andre's avatar
andre committed
54
void
conrad's avatar
conrad committed
55
oggz_vector_delete (OggzVector * vector);
andre's avatar
andre committed
56 57

void *
58 59 60 61 62 63 64
oggz_vector_find_p (OggzVector * vector, const void * data);

int
oggz_vector_find_index_p (OggzVector * vector, const void * data);

void *
oggz_vector_find_with (OggzVector * vector, OggzFindFunc func, long serialno);
andre's avatar
andre committed
65

conrad's avatar
conrad committed
66 67 68 69 70 71
void *
oggz_vector_nth_p (OggzVector * vector, int n);

long
oggz_vector_nth_l (OggzVector * vector, int n);

72 73 74 75 76 77
/**
 * Call a function on each element of a vector, in order.
 * \param vector The OggzVector to iterate over
 * \param func The OggzFunc to be called on each element
 * \retval 0 on success
 */
andre's avatar
andre committed
78 79 80
int
oggz_vector_foreach (OggzVector * vector, OggzFunc func);

81 82 83 84 85 86 87 88 89 90
/**
 * Call a function with a userdata pointer on each element
 * of a vector, in order. This allows the function to access
 * shared data when operating on the element sequence.
 * \param vector The OggzVector to iterate over
 * \param func The OggzFunc1 to be called on each element
 * \param arg The userdata pointer to be passed to the function
 * along with the vector member
 * \retval 0 on success
 */
91 92 93
int
oggz_vector_foreach1 (OggzVector * vector, OggzFunc1 func, void *arg);

94 95 96 97 98
/**
 * Return the number of elements in a vector.
 * \param vector The vector to query
 * \retval The number of elements
 */
conrad's avatar
conrad committed
99 100 101
int
oggz_vector_size (OggzVector * vector);

andre's avatar
andre committed
102 103 104
/**
 * Add an element to a vector. If the vector has a comparison function,
 * the new element is inserted in sorted order, otherwise it is appended
105 106
 * to the tail. Use this function to add pointer elements to the vector.
 * Use ogg_vector_insert_l for long values.
andre's avatar
andre committed
107 108 109 110 111 112
 * \param vector An OggzVector
 * \param data The new element to add
 * \retval data If the element was successfully added
 * \retval NULL If adding the element failed due to a realloc() error
 */
void *
conrad's avatar
conrad committed
113 114
oggz_vector_insert_p (OggzVector * vector, void * data);

115 116 117 118 119 120 121 122 123 124
/**
 * Add an element to a vector. If the vector has a comparison function,
 * the new element is inserted in sorted order, otherwise it is appended
 * to the tail. Use this function to add long value elements to the
 * vector. Use ogg_vector_insert_p for pointer values.
 * \param vector An OggzVector
 * \param ldata The new element to add
 * \retval ldata If the element was successfully added
 * \retval -1L If adding the element failed
 */
conrad's avatar
conrad committed
125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142
long
oggz_vector_insert_l (OggzVector * vector, long ldata);

/**
 * Remove a (void *) element of a vector
 * \retval \a vector on success
 * \retval NULL on failure (realloc error)
 */
OggzVector *
oggz_vector_remove_p (OggzVector * vector, void * data);

/**
 * Remove a (long) element of a vector
 * \retval \a vector on success
 * \retval NULL on failure (realloc error)
 */
OggzVector *
oggz_vector_remove_l (OggzVector * vector, long ldata);
andre's avatar
andre committed
143

144 145 146 147 148 149 150 151 152 153 154 155 156 157
/**
 * Set a comparison function for a vector.
 * Vectors can be sorted, or stored in append order, depending on
 * whether they have a comparison function defined. When a comparison
 * function is first set, it will be used to sort the entire vector,
 * and subsequence insertions will maintain the sort. If no comparison
 * function is set, new elements are appended at the end of the vector.
 * Call oggz_vector_set_cmp(vector, NULL, NULL) to remove the current
 * comparison function. This does not affect the member order.
 * \param vector the vector to associate the comparison function with
 * \param compare the OggzCmpFunc to use for comparisons
 * \param user_data private data pointer for the compare function
 * \retval 0 on success
 */
andre's avatar
andre committed
158 159 160 161
int
oggz_vector_set_cmp (OggzVector * vector, OggzCmpFunc compare,
		     void * user_data);

162 163 164 165 166
/**
 * Pop a member off a vector.
 * \retval pointer to the popped member
 * \retval NULL if the vector is empty
 */
andre's avatar
andre committed
167 168 169 170
void *
oggz_vector_pop (OggzVector * vector);

#endif /* __OGGZ_VECTOR_H__ */