219 lines
8.2 KiB
C
219 lines
8.2 KiB
C
/**
|
|
* A heterogeneous array of objects. b_array only stores references
|
|
* to the objects that it contains, not the object data itself.
|
|
*
|
|
* b_array stores pointers to objects in a single contiguous array,
|
|
* but this is an implementation detail that may change in the future.
|
|
* Users of b_array should not rely on this being the case.
|
|
*/
|
|
#ifndef BLUE_DS_ARRAY_H_
|
|
#define BLUE_DS_ARRAY_H_
|
|
|
|
#include <blue/core/iterator.h>
|
|
#include <blue/core/macros.h>
|
|
#include <blue/core/misc.h>
|
|
#include <blue/core/status.h>
|
|
|
|
B_DECLS_BEGIN;
|
|
|
|
#define B_TYPE_ARRAY (b_array_get_type())
|
|
#define B_TYPE_ARRAY_ITERATOR (b_array_iterator_get_type())
|
|
|
|
struct b_array_p;
|
|
|
|
B_DECLARE_TYPE(b_array);
|
|
B_DECLARE_TYPE(b_array_iterator);
|
|
|
|
B_TYPE_CLASS_DECLARATION_BEGIN(b_array)
|
|
B_TYPE_CLASS_DECLARATION_END(b_array)
|
|
|
|
B_TYPE_CLASS_DECLARATION_BEGIN(b_array_iterator)
|
|
B_TYPE_CLASS_DECLARATION_END(b_array_iterator)
|
|
|
|
BLUE_API b_type b_array_get_type(void);
|
|
BLUE_API b_type b_array_iterator_get_type(void);
|
|
|
|
B_TYPE_DEFAULT_CONSTRUCTOR(b_array, B_TYPE_ARRAY);
|
|
|
|
/**
|
|
* Creates an b_array initialised with the contents of the provided
|
|
* b_object pointer array. The b_array will take a reference to each
|
|
* object specified in `values`, and will increment the reference count.
|
|
* The order of objects in the new b_array will be the same as the order
|
|
* of objects in `values`. Any NULL pointers in the `values` array will
|
|
* be ignored, and will not result in gaps in the created b_array.
|
|
* However, `nr_values` should be large enough to cover the final
|
|
* non-NULL pointer in `values`, including any NULL pointers in-between.
|
|
*
|
|
* @param values The list of object pointers which should make up the
|
|
* contents of the new b_array.
|
|
* @param nr_values The size of the `values` array.
|
|
* @return A pointer to the new b_array, or NULL if an error occurred.
|
|
*/
|
|
BLUE_API b_array *b_array_create_with_values(
|
|
b_object *const *values, size_t nr_values);
|
|
|
|
/**
|
|
* Remove all object references from an b_array, resetting the size of the array to zero.
|
|
* The reference counts of all objects in the array will be decremented.
|
|
*
|
|
* @param array The b_array to clear.
|
|
*/
|
|
BLUE_API void b_array_clear(b_array *array);
|
|
|
|
/**
|
|
* Inserts an object at the end of an b_array. The reference count of
|
|
* the object will be incremented.
|
|
*
|
|
* @param array The b_array to append the object to.
|
|
* @param value The object to append.
|
|
* @return B_SUCCESS if the object was appended successfully, or an
|
|
* error code if an error occurred.
|
|
*/
|
|
BLUE_API b_status b_array_append(b_array *array, b_object *value);
|
|
|
|
/**
|
|
* Inserts an object at the beginning of an b_array. The reference count
|
|
* of the object will be incremented. All other objects in the array
|
|
* will be moved to make space for the object being pre-pended.
|
|
*
|
|
* @param array The b_array to prepend the object to.
|
|
* @param value The object to prepend.
|
|
* @return B_SUCCESS if the object was prepended successfully, or an
|
|
* error code if an error occurred.
|
|
*/
|
|
BLUE_API b_status b_array_prepend(b_array *array, b_object *value);
|
|
|
|
/**
|
|
* Inserts an object into an b_array at a given index. The reference
|
|
* count of the object will be incremented. If the specified index is at
|
|
* the beginning or mid-way through the array (i.e. not at the end),
|
|
* some or all of the objects already in the array will be moved to make
|
|
* space for the object being inserted.
|
|
*
|
|
* @param array The b_array to insert the object into.
|
|
* @param value The object to insert.
|
|
* @param at The index to insert the object at. If the index is
|
|
* `B_NPOS`, the object will be inserted at the end of the b_array.
|
|
* @return B_SUCCESS if the object was inserted, or a status code
|
|
* describing any error that occurred.
|
|
*/
|
|
BLUE_API b_status b_array_insert(b_array *array, b_object *value, size_t at);
|
|
|
|
/**
|
|
* Removes the object at the specified index from an b_array. The
|
|
* reference count of the removed object will be decremented. If the
|
|
* specified index is at the beginning or mid-way through the array
|
|
* (i.e. not at the end), the remaining objects will be moved to fill
|
|
* the empty space created by the object's removal.
|
|
*
|
|
* @param array The b_array to remove the object from.
|
|
* @param at The index of the object to be removed.
|
|
* @return B_SUCCESS if the object was removed, or a status code
|
|
* describing any error that occurred.
|
|
*/
|
|
BLUE_API b_status b_array_remove(b_array *array, size_t at);
|
|
|
|
/**
|
|
* Removes the object at the beginning of an b_array. The reference count
|
|
* of the removed object will be decremented. The remaining objects will be moved
|
|
* to fill the empty space created by the object's removal.
|
|
*
|
|
* @param array The b_array to remove the object from.
|
|
* @return B_SUCCESS if the object was removed, or a status code describing any error that occurred.
|
|
*/
|
|
BLUE_API b_status b_array_remove_front(b_array *array);
|
|
|
|
/**
|
|
* Removes the object at the end of an b_array. The reference count
|
|
* of the removed object will be decremented.
|
|
*
|
|
* @param array The b_array to remove the object from.
|
|
* @return B_SUCCESS if the object was removed, or a status code describing any error that occurred.
|
|
*/
|
|
BLUE_API b_status b_array_remove_back(b_array *array);
|
|
|
|
/**
|
|
* Removes the object at the specified index of an b_array, and returns
|
|
* a pointer to it. The reference count of the removed object will NOT
|
|
* be decremented. The caller becomes the owner of the array's reference
|
|
* to the object. If the specified index is at the beginning or mid-way
|
|
* through the array (i.e. not at the end), the remaining objects will
|
|
* be moved to fill the empty space created by the object's removal.
|
|
*
|
|
* @param array The b_array to remove the object from.
|
|
* @param at The index of the object to be removed.
|
|
* @return An pointer to the removed object. This pointer is owned by
|
|
* the caller. Returns NULL if an error occurred.
|
|
*/
|
|
BLUE_API b_object *b_array_pop(b_array *array, size_t at);
|
|
|
|
/**
|
|
* Removes the object at the beginning of an b_array, and returns a
|
|
* pointer to it. The reference count of the removed object will NOT be
|
|
* decremented. The caller becomes the owner of the array's reference to
|
|
* the object. The remaining objects in the b_array will be moved to
|
|
* fill the empty space left by the removed object.
|
|
*
|
|
* @param array The b_array to remove the object from.
|
|
* @return An pointer to the removed object. This pointer is owned by
|
|
* the caller. Returns NULL if an error occurred.
|
|
*/
|
|
BLUE_API b_object *b_array_pop_front(b_array *array);
|
|
|
|
/**
|
|
* Removes the object at the end of an b_array, and returns a pointer to it. The
|
|
* reference count of the removed object will NOT be decremented. The caller
|
|
* becomes the owner of the array's reference to the object.
|
|
*
|
|
* @param array The b_array to remove the object from.
|
|
* @return An pointer to the removed object. This pointer is owned by the
|
|
* caller. Returns NULL if an error occurred.
|
|
*/
|
|
BLUE_API b_object *b_array_pop_back(b_array *array);
|
|
|
|
/**
|
|
* Returns an unowned pointer to the object at the given index of an b_array.
|
|
* The caller does not own the returned pointer, and MUST NOT release it.
|
|
*
|
|
* @param array The b_array.
|
|
* @param at The index of the object to return.
|
|
* @return A pointer to the object at the given index. This pointer is NOT owned
|
|
* by the caller. Returns NULL if an error occurred.
|
|
*/
|
|
BLUE_API b_object *b_array_at(const b_array *array, size_t at);
|
|
|
|
/**
|
|
* Returns an owned pointer to the object at the given index of an
|
|
* b_array. The caller owns the returned pointer, and must release it
|
|
* when they are finished with it.
|
|
*
|
|
* @param array The b_array.
|
|
* @param at The index of the object to return.
|
|
* @return A pointer to the object at the given index. This pointer is
|
|
* owned by the caller. Returns NULL if an error occurred.
|
|
*/
|
|
BLUE_API b_object *b_array_get(b_array *array, size_t at);
|
|
|
|
/**
|
|
* Returns the number of objects contained in an b_array.
|
|
*
|
|
* @param array The b_array.
|
|
* @return The number of objects contained in the b_array.
|
|
*/
|
|
BLUE_API size_t b_array_size(const b_array *array);
|
|
|
|
/**
|
|
* Returns the current maximum capacity of an b_array. This represents
|
|
* the number of objects that can be stored in an b_array before its
|
|
* internal buffer would need to be re-sized.
|
|
*
|
|
* @param array The b_array.
|
|
* @return The maximum capacity of the b_array.
|
|
*/
|
|
BLUE_API size_t b_array_capacity(const b_array *array);
|
|
|
|
B_DECLS_END;
|
|
|
|
#endif
|