diff options
author | Campbell Barton <ideasman42@gmail.com> | 2021-12-09 12:01:44 +0300 |
---|---|---|
committer | Campbell Barton <ideasman42@gmail.com> | 2021-12-09 12:01:44 +0300 |
commit | 9e365069afe156f33fadfad9705e1325f894cd54 (patch) | |
tree | 78373044d029feb51f987b45208e0c1a36958625 /source/blender/blenlib/BLI_array_utils.h | |
parent | d8b42751625c915113b64f5a2d9c72f19f009fee (diff) |
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
Diffstat (limited to 'source/blender/blenlib/BLI_array_utils.h')
-rw-r--r-- | source/blender/blenlib/BLI_array_utils.h | 60 |
1 files changed, 60 insertions, 0 deletions
diff --git a/source/blender/blenlib/BLI_array_utils.h b/source/blender/blenlib/BLI_array_utils.h index 52d41173a0e..eb14b030bf9 100644 --- a/source/blender/blenlib/BLI_array_utils.h +++ b/source/blender/blenlib/BLI_array_utils.h @@ -28,12 +28,29 @@ extern "C" { #endif +/** + * In-place array reverse. + * + * Access via #BLI_array_reverse + */ void _bli_array_reverse(void *arr, uint arr_len, size_t arr_stride); #define BLI_array_reverse(arr, arr_len) _bli_array_reverse(arr, arr_len, sizeof(*(arr))) +/** + * In-place array wrap. + * (rotate the array one step forward or backwards). + * + * Access via #BLI_array_wrap + */ void _bli_array_wrap(void *arr, uint arr_len, size_t arr_stride, int dir); #define BLI_array_wrap(arr, arr_len, dir) _bli_array_wrap(arr, arr_len, sizeof(*(arr)), dir) +/** + *In-place array permute. + * (re-arrange elements based on an array of indices). + * + * Access via #BLI_array_wrap + */ void _bli_array_permute( void *arr, const uint arr_len, const size_t arr_stride, const uint *order, void *arr_temp); #define BLI_array_permute(arr, arr_len, order) \ @@ -41,13 +58,30 @@ void _bli_array_permute( #define BLI_array_permute_ex(arr, arr_len, order, arr_temp) \ _bli_array_permute(arr, arr_len, sizeof(*(arr)), order, arr_temp) +/** + * In-place array de-duplication of an ordered array. + * + * \return The new length of the array. + * + * Access via #BLI_array_deduplicate_ordered + */ uint _bli_array_deduplicate_ordered(void *arr, uint arr_len, size_t arr_stride); #define BLI_array_deduplicate_ordered(arr, arr_len) \ _bli_array_deduplicate_ordered(arr, arr_len, sizeof(*(arr))) +/** + * Find the first index of an item in an array. + * + * Access via #BLI_array_findindex + * + * \note Not efficient, use for error checks/asserts. + */ int _bli_array_findindex(const void *arr, uint arr_len, size_t arr_stride, const void *p); #define BLI_array_findindex(arr, arr_len, p) _bli_array_findindex(arr, arr_len, sizeof(*(arr)), p) +/** + * A version of #BLI_array_findindex that searches from the end of the list. + */ int _bli_array_rfindindex(const void *arr, uint arr_len, size_t arr_stride, const void *p); #define BLI_array_rfindindex(arr, arr_len, p) \ _bli_array_rfindindex(arr, arr_len, sizeof(*(arr)), p) @@ -66,6 +100,22 @@ void _bli_array_binary_or( CHECK_TYPE_PAIR_INLINE(*(arr), *(arr_b)), \ _bli_array_binary_or(arr, arr_a, arr_b, arr_len, sizeof(*(arr)))) +/** + * Utility function to iterate over contiguous items in an array. + * + * \param use_wrap: Detect contiguous ranges across the first/last points. + * In this case the second index of \a span_step may be lower than the first, + * which indicates the values are wrapped. + * \param use_delimit_bounds: When false, + * ranges that defined by the start/end indices are excluded. + * This option has no effect when \a use_wrap is enabled. + * \param test_fn: Function to test if the item should be included in the range. + * \param user_data: User data for \a test_fn. + * \param span_step: Indices to iterate over, + * initialize both values to the array length to initialize iteration. + * \param r_span_len: The length of the span, useful when \a use_wrap is enabled, + * where calculating the length isn't a simple subtraction. + */ bool _bli_array_iter_span(const void *arr, uint arr_len, size_t arr_stride, @@ -87,9 +137,19 @@ bool _bli_array_iter_span(const void *arr, span_step, \ r_span_len) +/** + * Simple utility to check memory is zeroed. + */ bool _bli_array_is_zeroed(const void *arr, uint arr_len, size_t arr_stride); #define BLI_array_is_zeroed(arr, arr_len) _bli_array_is_zeroed(arr, arr_len, sizeof(*(arr))) +/** + * Smart function to sample a rectangle spiraling outside. + * Nice for selection ID. + * + * \param arr_shape: dimensions [w, h]. + * \param center: coordinates [x, y] indicating where to start traversing. + */ bool _bli_array_iter_spiral_square(const void *arr_v, const int arr_shape[2], const size_t elem_size, |