From 9e365069afe156f33fadfad9705e1325f894cd54 Mon Sep 17 00:00:00 2001 From: Campbell Barton Date: Thu, 9 Dec 2021 20:01:44 +1100 Subject: Cleanup: move public doc-strings into headers for 'blenlib' - Added space below non doc-string comments to make it clear these aren't comments for the symbols directly below them. - Use doxy sections for some headers. - Minor improvements to doc-strings. Ref T92709 --- source/blender/blenlib/BLI_listbase.h | 160 ++++++++++++++++++++++++++++++++-- 1 file changed, 155 insertions(+), 5 deletions(-) (limited to 'source/blender/blenlib/BLI_listbase.h') diff --git a/source/blender/blenlib/BLI_listbase.h b/source/blender/blenlib/BLI_listbase.h index cf525d1c2af..7d808d339e9 100644 --- a/source/blender/blenlib/BLI_listbase.h +++ b/source/blender/blenlib/BLI_listbase.h @@ -33,89 +33,233 @@ extern "C" { #endif +/** + * Returns the position of \a vlink within \a listbase, numbering from 0, or -1 if not found. + */ int BLI_findindex(const struct ListBase *listbase, const void *vlink) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1); +/** + * Returns the 0-based index of the first element of listbase which contains the specified + * null-terminated string at the specified offset, or -1 if not found. + */ int BLI_findstringindex(const struct ListBase *listbase, const char *id, const int offset) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1); -/* find forwards */ +/* Find forwards. */ + +/** + * Returns the nth element of \a listbase, numbering from 0. + */ void *BLI_findlink(const struct ListBase *listbase, int number) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1); +/** + * Finds the first element of \a listbase which contains the null-terminated + * string \a id at the specified offset, returning NULL if not found. + */ void *BLI_findstring(const struct ListBase *listbase, const char *id, const int offset) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1); +/** + * Finds the first element of \a listbase which contains a pointer to the + * null-terminated string \a id at the specified offset, returning NULL if not found. + */ void *BLI_findstring_ptr(const struct ListBase *listbase, const char *id, const int offset) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1); +/** + * Finds the first element of listbase which contains the specified pointer value + * at the specified offset, returning NULL if not found. + */ void *BLI_findptr(const struct ListBase *listbase, const void *ptr, const int offset) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1); +/** + * Finds the first element of listbase which contains the specified bytes + * at the specified offset, returning NULL if not found. + */ void *BLI_listbase_bytes_find(const ListBase *listbase, const void *bytes, const size_t bytes_size, const int offset) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1, 2); +/** + * Find the first item in the list that matches the given string, or the given index as fallback. + * + * \note The string is only used is non-NULL and non-empty. + * + * \return The found item, or NULL. + */ void *BLI_listbase_string_or_index_find(const struct ListBase *listbase, const char *string, const size_t string_offset, const int index) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1); -/* find backwards */ +/* Find backwards. */ + +/** + * Returns the nth-last element of \a listbase, numbering from 0. + */ void *BLI_rfindlink(const struct ListBase *listbase, int number) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1); +/** + * Finds the last element of \a listbase which contains the + * null-terminated string \a id at the specified offset, returning NULL if not found. + */ void *BLI_rfindstring(const struct ListBase *listbase, const char *id, const int offset) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1); +/** + * Finds the last element of \a listbase which contains a pointer to the + * null-terminated string \a id at the specified offset, returning NULL if not found. + */ void *BLI_rfindstring_ptr(const struct ListBase *listbase, const char *id, const int offset) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1); +/** + * Finds the last element of listbase which contains the specified pointer value + * at the specified offset, returning NULL if not found. + */ void *BLI_rfindptr(const struct ListBase *listbase, const void *ptr, const int offset) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1); +/** + * Finds the last element of listbase which contains the specified bytes + * at the specified offset, returning NULL if not found. + */ void *BLI_listbase_bytes_rfind(const ListBase *listbase, const void *bytes, const size_t bytes_size, const int offset) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1, 2); +/** + * Removes and disposes of the entire contents of \a listbase using guardedalloc. + */ void BLI_freelistN(struct ListBase *listbase) ATTR_NONNULL(1); +/** + * Appends \a vlink (assumed to begin with a Link) onto listbase. + */ void BLI_addtail(struct ListBase *listbase, void *vlink) ATTR_NONNULL(1); +/** + * Removes \a vlink from \a listbase. Assumes it is linked into there! + */ void BLI_remlink(struct ListBase *listbase, void *vlink) ATTR_NONNULL(1); +/** + * Checks that \a vlink is linked into listbase, removing it from there if so. + */ bool BLI_remlink_safe(struct ListBase *listbase, void *vlink) ATTR_NONNULL(1); +/** + * Removes the head from \a listbase and returns it. + */ void *BLI_pophead(ListBase *listbase) ATTR_NONNULL(1); +/** + * Removes the tail from \a listbase and returns it. + */ void *BLI_poptail(ListBase *listbase) ATTR_NONNULL(1); +/** + * Prepends \a vlink (assumed to begin with a Link) onto listbase. + */ void BLI_addhead(struct ListBase *listbase, void *vlink) ATTR_NONNULL(1); +/** + * Inserts \a vnewlink immediately preceding \a vnextlink in listbase. + * Or, if \a vnextlink is NULL, puts \a vnewlink at the end of the list. + */ void BLI_insertlinkbefore(struct ListBase *listbase, void *vnextlink, void *vnewlink) ATTR_NONNULL(1); +/** + * Inserts \a vnewlink immediately following \a vprevlink in \a listbase. + * Or, if \a vprevlink is NULL, puts \a vnewlink at the front of the list. + */ void BLI_insertlinkafter(struct ListBase *listbase, void *vprevlink, void *vnewlink) ATTR_NONNULL(1); +/** + * Insert a link in place of another, without changing its position in the list. + * + * Puts `vnewlink` in the position of `vreplacelink`, removing `vreplacelink`. + * - `vreplacelink` *must* be in the list. + * - `vnewlink` *must not* be in the list. + */ void BLI_insertlinkreplace(ListBase *listbase, void *vreplacelink, void *vnewlink) ATTR_NONNULL(1, 2, 3); +/** + * Sorts the elements of listbase into the order defined by cmp + * (which should return 1 if its first arg should come after its second arg). + * This uses insertion sort, so NOT ok for large list. + */ void BLI_listbase_sort(struct ListBase *listbase, int (*cmp)(const void *, const void *)) ATTR_NONNULL(1, 2); void BLI_listbase_sort_r(ListBase *listbase, int (*cmp)(void *, const void *, const void *), void *thunk) ATTR_NONNULL(1, 2); +/** + * Reinsert \a vlink relative to its current position but offset by \a step. Doesn't move + * item if new position would exceed list (could optionally move to head/tail). + * + * \param step: Absolute value defines step size, sign defines direction. E.g pass -1 + * to move \a vlink before previous, or 1 to move behind next. + * \return If position of \a vlink has changed. + */ bool BLI_listbase_link_move(ListBase *listbase, void *vlink, int step) ATTR_NONNULL(); +/** + * Move the link at the index \a from to the position at index \a to. + * + * \return If the move was successful. + */ bool BLI_listbase_move_index(ListBase *listbase, int from, int to) ATTR_NONNULL(); +/** + * Removes and disposes of the entire contents of listbase using direct free(3). + */ void BLI_freelist(struct ListBase *listbase) ATTR_NONNULL(1); +/** + * Returns the number of elements in \a listbase, up until (and including count_max) + * + * \note Use to avoid redundant looping. + */ int BLI_listbase_count_at_most(const struct ListBase *listbase, const int count_max) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1); +/** + * Returns the number of elements in \a listbase. + */ int BLI_listbase_count(const struct ListBase *listbase) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1); +/** + * Removes \a vlink from listbase and disposes of it. Assumes it is linked into there! + */ void BLI_freelinkN(struct ListBase *listbase, void *vlink) ATTR_NONNULL(1); +/** + * Swaps \a vlinka and \a vlinkb in the list. Assumes they are both already in the list! + */ void BLI_listbase_swaplinks(struct ListBase *listbase, void *vlinka, void *vlinkb) ATTR_NONNULL(1, 2); +/** + * Swaps \a vlinka and \a vlinkb from their respective lists. + * Assumes they are both already in their \a listbasea! + */ void BLI_listbases_swaplinks(struct ListBase *listbasea, struct ListBase *listbaseb, void *vlinka, void *vlinkb) ATTR_NONNULL(2, 3); +/** + * Moves the entire contents of \a src onto the end of \a dst. + */ void BLI_movelisttolist(struct ListBase *dst, struct ListBase *src) ATTR_NONNULL(1, 2); +/** + * Moves the entire contents of \a src at the beginning of \a dst. + */ void BLI_movelisttolist_reverse(struct ListBase *dst, struct ListBase *src) ATTR_NONNULL(1, 2); +/** + * Sets dst to a duplicate of the entire contents of src. dst may be the same as src. + */ void BLI_duplicatelist(struct ListBase *dst, const struct ListBase *src) ATTR_NONNULL(1, 2); void BLI_listbase_reverse(struct ListBase *lb) ATTR_NONNULL(1); +/** + * \param vlink: Link to make first. + */ void BLI_listbase_rotate_first(struct ListBase *lb, void *vlink) ATTR_NONNULL(1, 2); +/** + * \param vlink: Link to make last. + */ void BLI_listbase_rotate_last(struct ListBase *lb, void *vlink) ATTR_NONNULL(1, 2); /** @@ -134,7 +278,9 @@ BLI_INLINE void BLI_listbase_clear(struct ListBase *lb) lb->first = lb->last = (void *)0; } -/* create a generic list node containing link to provided data */ +/** + * Create a generic list node containing link to provided data. + */ struct LinkData *BLI_genericNodeN(void *data); /** @@ -188,13 +334,17 @@ struct LinkData *BLI_genericNodeN(void *data); #define LISTBASE_FOREACH_BACKWARD(type, var, list) \ for (type var = (type)((list)->last); var != NULL; var = (type)(((Link *)(var))->prev)) -/** A version of #LISTBASE_FOREACH that supports removing the item we're looping over. */ +/** + * A version of #LISTBASE_FOREACH that supports removing the item we're looping over. + */ #define LISTBASE_FOREACH_MUTABLE(type, var, list) \ for (type var = (type)((list)->first), *var##_iter_next; \ ((var != NULL) ? ((void)(var##_iter_next = (type)(((Link *)(var))->next)), 1) : 0); \ var = var##_iter_next) -/** A version of #LISTBASE_FOREACH_BACKWARD that supports removing the item we're looping over. */ +/** + * A version of #LISTBASE_FOREACH_BACKWARD that supports removing the item we're looping over. + */ #define LISTBASE_FOREACH_BACKWARD_MUTABLE(type, var, list) \ for (type var = (type)((list)->last), *var##_iter_prev; \ ((var != NULL) ? ((void)(var##_iter_prev = (type)(((Link *)(var))->prev)), 1) : 0); \ -- cgit v1.2.3