223 lines
8.3 KiB
C
223 lines
8.3 KiB
C
/**
|
|
* A heterogeneous array of objects. fx_array only stores references
|
|
* to the objects that it contains, not the object data itself.
|
|
*
|
|
* fx_array stores pointers to objects in a single contiguous array,
|
|
* but this is an implementation detail that may change in the future.
|
|
* Users of fx_array should not rely on this being the case.
|
|
*/
|
|
#ifndef FX_DS_ARRAY_H_
|
|
#define FX_DS_ARRAY_H_
|
|
|
|
#include <fx/iterator.h>
|
|
#include <fx/macros.h>
|
|
#include <fx/misc.h>
|
|
#include <fx/status.h>
|
|
|
|
FX_DECLS_BEGIN;
|
|
|
|
#define FX_TYPE_ARRAY (fx_array_get_type())
|
|
#define FX_TYPE_ARRAY_ITERATOR (fx_array_iterator_get_type())
|
|
|
|
struct fx_array_p;
|
|
|
|
FX_DECLARE_TYPE(fx_array);
|
|
FX_DECLARE_TYPE(fx_array_iterator);
|
|
|
|
FX_TYPE_CLASS_DECLARATION_BEGIN(fx_array)
|
|
FX_TYPE_CLASS_DECLARATION_END(fx_array)
|
|
|
|
FX_TYPE_CLASS_DECLARATION_BEGIN(fx_array_iterator)
|
|
FX_TYPE_CLASS_DECLARATION_END(fx_array_iterator)
|
|
|
|
FX_API fx_type fx_array_get_type(void);
|
|
FX_API fx_type fx_array_iterator_get_type(void);
|
|
|
|
FX_TYPE_DEFAULT_CONSTRUCTOR(fx_array, FX_TYPE_ARRAY);
|
|
|
|
/**
|
|
* Creates an fx_array initialised with the contents of the provided
|
|
* fx_object pointer array. The fx_array will take a reference to each
|
|
* object specified in `values`, and will increment the reference count.
|
|
* The order of objects in the new fx_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 fx_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 fx_array.
|
|
* @param nr_values The size of the `values` array.
|
|
* @return A pointer to the new fx_array, or NULL if an error occurred.
|
|
*/
|
|
FX_API fx_array *fx_array_create_with_values(
|
|
fx_object *const *values,
|
|
size_t nr_values);
|
|
|
|
/**
|
|
* Remove all object references from an fx_array, resetting the size of the
|
|
* array to zero. The reference counts of all objects in the array will be
|
|
* decremented.
|
|
*
|
|
* @param array The fx_array to clear.
|
|
*/
|
|
FX_API void fx_array_clear(fx_array *array);
|
|
|
|
/**
|
|
* Inserts an object at the end of an fx_array. The reference count of
|
|
* the object will be incremented.
|
|
*
|
|
* @param array The fx_array to append the object to.
|
|
* @param value The object to append.
|
|
* @return FX_SUCCESS if the object was appended successfully, or an
|
|
* error code if an error occurred.
|
|
*/
|
|
FX_API fx_status fx_array_append(fx_array *array, fx_object *value);
|
|
|
|
/**
|
|
* Inserts an object at the beginning of an fx_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 fx_array to prepend the object to.
|
|
* @param value The object to prepend.
|
|
* @return FX_SUCCESS if the object was prepended successfully, or an
|
|
* error code if an error occurred.
|
|
*/
|
|
FX_API fx_status fx_array_prepend(fx_array *array, fx_object *value);
|
|
|
|
/**
|
|
* Inserts an object into an fx_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 fx_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
|
|
* `FX_NPOS`, the object will be inserted at the end of the fx_array.
|
|
* @return FX_SUCCESS if the object was inserted, or a status code
|
|
* describing any error that occurred.
|
|
*/
|
|
FX_API fx_status fx_array_insert(fx_array *array, fx_object *value, size_t at);
|
|
|
|
/**
|
|
* Removes the object at the specified index from an fx_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 fx_array to remove the object from.
|
|
* @param at The index of the object to be removed.
|
|
* @return FX_SUCCESS if the object was removed, or a status code
|
|
* describing any error that occurred.
|
|
*/
|
|
FX_API fx_status fx_array_remove(fx_array *array, size_t at);
|
|
|
|
/**
|
|
* Removes the object at the beginning of an fx_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 fx_array to remove the object from.
|
|
* @return FX_SUCCESS if the object was removed, or a status code describing any
|
|
* error that occurred.
|
|
*/
|
|
FX_API fx_status fx_array_remove_front(fx_array *array);
|
|
|
|
/**
|
|
* Removes the object at the end of an fx_array. The reference count
|
|
* of the removed object will be decremented.
|
|
*
|
|
* @param array The fx_array to remove the object from.
|
|
* @return FX_SUCCESS if the object was removed, or a status code describing any
|
|
* error that occurred.
|
|
*/
|
|
FX_API fx_status fx_array_remove_back(fx_array *array);
|
|
|
|
/**
|
|
* Removes the object at the specified index of an fx_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 fx_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.
|
|
*/
|
|
FX_API fx_object *fx_array_pop(fx_array *array, size_t at);
|
|
|
|
/**
|
|
* Removes the object at the beginning of an fx_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 fx_array will be moved to
|
|
* fill the empty space left by the removed object.
|
|
*
|
|
* @param array The fx_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.
|
|
*/
|
|
FX_API fx_object *fx_array_pop_front(fx_array *array);
|
|
|
|
/**
|
|
* Removes the object at the end of an fx_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 fx_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.
|
|
*/
|
|
FX_API fx_object *fx_array_pop_back(fx_array *array);
|
|
|
|
/**
|
|
* Returns an unowned pointer to the object at the given index of an fx_array.
|
|
* The caller does not own the returned pointer, and MUST NOT release it.
|
|
*
|
|
* @param array The fx_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.
|
|
*/
|
|
FX_API fx_object *fx_array_at(const fx_array *array, size_t at);
|
|
|
|
/**
|
|
* Returns an owned pointer to the object at the given index of an
|
|
* fx_array. The caller owns the returned pointer, and must release it
|
|
* when they are finished with it.
|
|
*
|
|
* @param array The fx_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.
|
|
*/
|
|
FX_API fx_object *fx_array_get(fx_array *array, size_t at);
|
|
|
|
/**
|
|
* Returns the number of objects contained in an fx_array.
|
|
*
|
|
* @param array The fx_array.
|
|
* @return The number of objects contained in the fx_array.
|
|
*/
|
|
FX_API size_t fx_array_size(const fx_array *array);
|
|
|
|
/**
|
|
* Returns the current maximum capacity of an fx_array. This represents
|
|
* the number of objects that can be stored in an fx_array before its
|
|
* internal buffer would need to be re-sized.
|
|
*
|
|
* @param array The fx_array.
|
|
* @return The maximum capacity of the fx_array.
|
|
*/
|
|
FX_API size_t fx_array_capacity(const fx_array *array);
|
|
|
|
FX_DECLS_END;
|
|
|
|
#endif
|