Commit db617960 authored by Yong Bakos's avatar Yong Bakos Committed by Pekka Paalanen

util: Document wl_array

Add doxygen comments for wl_array and its methods.
Signed-off-by: default avatarYong Bakos <ybakos@humanoriented.com>
Reviewed-by: Eric Engestrom's avatarEric Engestrom <eric.engestrom@imgtec.com>
Reviewed-by: Pekka Paalanen's avatarPekka Paalanen <pekka.paalanen@collabora.co.uk>
parent f7e1dcc2
......@@ -350,29 +350,92 @@ wl_list_insert_list(struct wl_list *list, struct wl_list *other);
pos = tmp, \
tmp = wl_container_of(pos->member.prev, tmp, member))
/**
* \class wl_array
*
* Dynamic array
*
* A wl_array is a dynamic array that can only grow until released. It is
* intended for relatively small allocations whose size is variable or not known
* in advance. While construction of a wl_array does not require all elements to
* be of the same size, wl_array_for_each() does require all elements to have
* the same type and size.
*
*/
struct wl_array {
size_t size;
size_t alloc;
void *data;
};
#define wl_array_for_each(pos, array) \
for (pos = (array)->data; \
(const char *) pos < ((const char *) (array)->data + (array)->size); \
(pos)++)
/**
* Initializes the array.
*
* \param array Array to initialize
*
* \memberof wl_array
*/
void
wl_array_init(struct wl_array *array);
/**
* Releases the array data.
*
* \note Leaves the array in an invalid state.
*
* \param array Array whose data is to be released
*
* \memberof wl_array
*/
void
wl_array_release(struct wl_array *array);
/**
* Increases the size of the array by \p size bytes.
*
* \param array Array whose size is to be increased
* \param size Number of bytes to increase the size of the array by
*
* \return A pointer to the beginning of the newly appended space, or NULL when
* resizing fails.
*
* \memberof wl_array
*/
void *
wl_array_add(struct wl_array *array, size_t size);
/**
* Copies the contents of \p source to \p array.
*
* \param array Destination array to copy to
* \param source Source array to copy from
*
* \return 0 on success, or -1 on failure
*
* \memberof wl_array
*/
int
wl_array_copy(struct wl_array *array, struct wl_array *source);
/**
* Iterates over an array.
*
* This macro expresses a for-each iterator for wl_array. It assigns each
* element in the array to \p pos, which can then be referenced in a trailing
* code block. \p pos must be a pointer to the array element type, and all
* array elements must be of the same type and size.
*
* \param pos Cursor that each array element will be assigned to
* \param array Array to iterate over
*
* \relates wl_array
* \sa wl_list_for_each()
*/
#define wl_array_for_each(pos, array) \
for (pos = (array)->data; \
(const char *) pos < ((const char *) (array)->data + (array)->size); \
(pos)++)
typedef int32_t wl_fixed_t;
static inline double
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment