wash/bluelib
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

ds: array: convert to new object system

Browse Source
This commit is contained in:
max 🍓
2025-10-19 11:02:59 +01:00
parent 3eebdddc21
commit 0a9eb4a085
3 changed files with 301 additions and 256 deletions
Download Patch File Download Diff File Expand all files Collapse all files

208
ds/include/blue/ds/array.h
View File

@@ -1,16 +1,29 @@
#ifndef BLUELIB_ARRAY_H_
#define BLUELIB_ARRAY_H_
/**
* 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>
#include <blue/ds/object.h>
#include <blue/ds/type.h>
/**
* Cast a generic b_dsref pointer to an b_array pointer.
*/
#define B_ARRAY(p) ((b_array *)(p))
B_DECLS_BEGIN;
#define B_TYPE_ARRAY (b_array_get_type())
struct b_array_p;
B_DECLARE_TYPE(b_array);
B_TYPE_CLASS_DECLARATION_BEGIN(b_array)
B_TYPE_CLASS_DECLARATION_END(b_array)
/**
* Iterate through each object in an b_array.
@@ -26,24 +39,10 @@
for (int z__b_unique_name() = b_array_iterator_begin(array, it); \
(it)->value != NULL; b_array_iterator_next(it))
#ifdef __cplusplus
extern "C" {
#endif
/**
* 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.
*/
typedef struct b_array b_array;
/**
* Iterator for traversing the contents of an b_array.
*
* The iterator provides the current b_dsref `value`, as well
* The iterator provides the current b_object `value`, as well
* as the index `i` of that value within the array.
*
* Any members whose names begin with _ (underscore) are reserved
@@ -52,57 +51,35 @@ typedef struct b_array b_array;
typedef struct b_array_iterator {
b_iterator _base;
b_array *_a;
struct b_array_p *_a_p;
/** The index of the current value */
size_t i;
/** The current value */
b_dsref *value;
b_object *value;
} b_array_iterator;
/**
* Creates an empty b_array.
*
* @return A pointer to the new array, or NULL if an error occurred.
*/
BLUE_API b_array *b_array_create(void);
BLUE_API b_type b_array_get_type(void);
B_TYPE_DEFAULT_CONSTRUCTOR(b_array, B_TYPE_ARRAY);
/**
* Creates an b_array initialised with the contents of the provided b_dsref
* 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.
* 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 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_dsref *const *values, size_t nr_values);
/**
* Increment the reference counter of an b_array.
*
* @param array The b_array to reference.
* @return The b_array pointer that was passed to the function.
*/
static inline b_array *b_array_retain(b_array *array)
{
return B_ARRAY(b_retain(B_DSREF(array)));
}
/**
* Decrement the reference counter of an b_array, destroying the array if it reaches zero.
* @param array The b_array reference to release.
*/
static inline void b_array_release(b_array *array)
{
b_release(B_DSREF(array));
}
b_object *const *values, size_t nr_values);
/**
* Remove all object references from an b_array, resetting the size of the array to zero.
@@ -113,49 +90,55 @@ static inline void b_array_release(b_array *array)
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.
* 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.
* @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_dsref *value);
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.
* 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.
* @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_dsref *value);
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.
* 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.
* @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_dsref *value, size_t at);
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.
* 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.
* @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);
@@ -179,32 +162,32 @@ BLUE_API b_status b_array_remove_front(b_array *array);
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.
* 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.
* @return An pointer to the removed object. This pointer is owned by
* the caller. Returns NULL if an error occurred.
*/
BLUE_API b_dsref *b_array_pop(b_array *array, size_t at);
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.
* 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.
* @return An pointer to the removed object. This pointer is owned by
* the caller. Returns NULL if an error occurred.
*/
BLUE_API b_dsref *b_array_pop_front(b_array *array);
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
@@ -215,7 +198,7 @@ BLUE_API b_dsref *b_array_pop_front(b_array *array);
* @return An pointer to the removed object. This pointer is owned by the
* caller. Returns NULL if an error occurred.
*/
BLUE_API b_dsref *b_array_pop_back(b_array *array);
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.
@@ -226,18 +209,19 @@ BLUE_API b_dsref *b_array_pop_back(b_array *array);
* @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_dsref *b_array_at(const b_array *array, size_t at);
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.
* 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.
* @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_dsref *b_array_get(b_array *array, size_t at);
BLUE_API b_object *b_array_get(b_array *array, size_t at);
/**
* Returns the number of objects contained in an b_array.
@@ -248,9 +232,9 @@ BLUE_API b_dsref *b_array_get(b_array *array, size_t at);
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.
* 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.
@@ -297,8 +281,6 @@ BLUE_API b_status b_array_iterator_erase(b_array_iterator *it);
*/
BLUE_API bool b_array_iterator_is_valid(const b_array_iterator *it);
#ifdef __cplusplus
}
#endif
B_DECLS_END;
#endif