BLI_array.h File Reference

A (mainly) macro array library. More...

Go to the source code of this file.

Macros
Internal defines
#define	_bli_array_totalsize_dynamic(arr)    (((arr) == NULL) ? 0 : MEM_allocN_len(arr) / sizeof(*(arr)))
#define	_bli_array_totalsize_static(arr)   (sizeof(_##arr##_static) / sizeof(*(arr)))
#define	_bli_array_totalsize(arr)
Public defines
#define	BLI_array_declare(arr)
#define	BLI_array_staticdeclare(arr, maxstatic)
#define	BLI_array_len(arr)   ((void)0, _##arr##_len)
#define	BLI_array_reserve(arr, num)
#define	BLI_array_grow_items(arr, num)   (BLI_array_reserve(arr, num), (_##arr##_len += num))
#define	BLI_array_grow_one(arr)   BLI_array_grow_items(arr, 1)
#define	BLI_array_append(arr, item)    ((void)BLI_array_grow_one(arr), (void)(arr[_##arr##_len - 1] = item))
#define	BLI_array_append_r(arr, item)    ((void)BLI_array_grow_one(arr), (void)(arr[_##arr##_len - 1] = item), (&arr[_##arr##_len - 1]))
#define	BLI_array_append_ret(arr)   (BLI_array_reserve(arr, 1), &arr[(_##arr##_len++)])
#define	BLI_array_free(arr)
#define	BLI_array_pop(arr)   ((arr && _##arr##_len) ? arr[--_##arr##_len] : NULL)
#define	BLI_array_clear(arr)
#define	BLI_array_len_set(arr, len)
#define	BLI_array_fake_user(arr)   ((void)_##arr##_len, (void)_##arr##_static)
Generic Array Utils
other useful defines (unrelated to the main array macros)
#define	BLI_array_fixedstack_declare(arr, maxstatic, realsize, allocstr)
#define	BLI_array_fixedstack_free(arr)

Functions
void	_bli_array_grow_func (void **arr_p, const void *arr_static, const int sizeof_arr_p, const int arr_len, const int num, const char *alloc_str)

Detailed Description

A (mainly) macro array library.

Definition in file BLI_array.h.

Macro Definition Documentation

_bli_array_totalsize

#define _bli_array_totalsize

(

arr

)

Value:

  ((size_t)(((void *)(arr) == (void *)_##arr##_static && (void *)(arr) != NULL) ? \
                _bli_array_totalsize_static(arr) : \
                _bli_array_totalsize_dynamic(arr)))

Definition at line 37 of file BLI_array.h.

_bli_array_totalsize_dynamic

#define _bli_array_totalsize_dynamic

(

arr

)

(((arr) == NULL) ? 0 : MEM_allocN_len(arr) / sizeof(*(arr)))

this returns the entire size of the array, including any buffering.

Definition at line 32 of file BLI_array.h.

_bli_array_totalsize_static

#define _bli_array_totalsize_static

(

arr

)

(sizeof(_##arr##_static) / sizeof(*(arr)))

Definition at line 35 of file BLI_array.h.

BLI_array_append

#define BLI_array_append	(		arr,
			item
	)		((void)BLI_array_grow_one(arr), (void)(arr[_##arr##_len - 1] = item))

appends an item to the array.

Definition at line 104 of file BLI_array.h.

BLI_array_append_r

#define BLI_array_append_r	(		arr,
			item
	)		((void)BLI_array_grow_one(arr), (void)(arr[_##arr##_len - 1] = item), (&arr[_##arr##_len - 1]))

appends an item to the array and returns a pointer to the item in the array. item is not a pointer, but actual data value.

Definition at line 110 of file BLI_array.h.

BLI_array_append_ret

#define BLI_array_append_ret

(

arr

)

(BLI_array_reserve(arr, 1), &arr[(_##arr##_len++)])

appends (grows) & returns a pointer to the uninitialized memory

Definition at line 114 of file BLI_array.h.

BLI_array_clear

#define BLI_array_clear

(

arr

)

Value:

  { \
    _##arr##_len = 0; \
  } \
  ((void)0)

Resets the logical size of an array to zero, but doesn't free the memory.

Definition at line 130 of file BLI_array.h.

BLI_array_declare

#define BLI_array_declare

(

arr

)

Value:

  int _##arr##_len = ((void)(sizeof(*(arr))), 0); \
  void *_##arr##_static = NULL

use sizeof(*(arr)) to ensure the array exists and is an array

Definition at line 62 of file BLI_array.h.

BLI_array_fake_user

#define BLI_array_fake_user

(

arr

)

((void)_##arr##_len, (void)_##arr##_static)

only to prevent unused warnings

Definition at line 146 of file BLI_array.h.

BLI_array_fixedstack_declare

#define BLI_array_fixedstack_declare	(		arr,
			maxstatic,
			realsize,
			allocstr
	)

Value:

  char _##arr##_static[maxstatic * sizeof(*(arr))]; \
  const bool _##arr##_is_static = ((void *)_##arr##_static) != \
                                  (arr = ((realsize) <= maxstatic) ? \
                                             (void *)_##arr##_static : \
                                             MEM_mallocN(sizeof(*(arr)) * (realsize), allocstr))

not part of the 'API' but handy funcs, same purpose as BLI_array_staticdeclare() but use when the max size is known ahead of time

Definition at line 161 of file BLI_array.h.

BLI_array_fixedstack_free

#define BLI_array_fixedstack_free

(

arr

)

Value:

  if (_##arr##_is_static) { \
    MEM_freeN(arr); \
  } \
  ((void)0)

Definition at line 168 of file BLI_array.h.

BLI_array_free

#define BLI_array_free

(

arr

)

Value:

  { \
    if (arr && (char *)arr != _##arr##_static) { \
      BLI_array_fake_user(arr); \
      MEM_freeN((void *)arr); \
    } \
  } \
  ((void)0)

Definition at line 116 of file BLI_array.h.

BLI_array_grow_items

#define BLI_array_grow_items	(		arr,
			num
	)		(BLI_array_reserve(arr, num), (_##arr##_len += num))

returns length of array

Definition at line 99 of file BLI_array.h.

BLI_array_grow_one

#define BLI_array_grow_one

(

arr

)

BLI_array_grow_items(arr, 1)

Definition at line 101 of file BLI_array.h.

BLI_array_len

#define BLI_array_len

(

arr

)

((void)0, _##arr##_len)

returns the logical size of the array, not including buffering.

Definition at line 74 of file BLI_array.h.

BLI_array_len_set

#define BLI_array_len_set	(		arr,
			len
	)

Value:

  { \
    _##arr##_len = (len); \
  } \
  ((void)0)

Set the length of the array, doesn't actually increase the allocated array size. don't use this unless you know what you're doing.

Definition at line 139 of file BLI_array.h.

BLI_array_pop

#define BLI_array_pop

(

arr

)

((arr && _##arr##_len) ? arr[--_##arr##_len] : NULL)

Definition at line 125 of file BLI_array.h.

BLI_array_reserve

#define BLI_array_reserve	(		arr,
			num
	)

Value:

  (void)((((void *)(arr) == NULL) && \
          ((void *)(_##arr##_static) != \
           NULL) && /* don't add _##arr##_len below because it must be zero */ \
          (_bli_array_totalsize_static(arr) >= \
           (size_t)(_##arr##_len + \
                    (num)))) ? /* we have an empty array and a static var big enough */ \
             (void)(arr = (void *)_##arr##_static) : /* use existing static array or allocate */ \
             (LIKELY(_bli_array_totalsize(arr) >= (size_t)(_##arr##_len + (num))) ? \
                  (void)0 /* do nothing */ : \
                  _bli_array_grow_func((void **)&(arr), \
                                       _##arr##_static, \
                                       sizeof(*(arr)), \
                                       _##arr##_len, \
                                       num, \
                                       "BLI_array." #arr)))

Grow the array by a fixed number of items.

Allow for a large 'num' value when the new size is more than double to allocate the exact sized array.

Definition at line 81 of file BLI_array.h.

BLI_array_staticdeclare

#define BLI_array_staticdeclare	(		arr,
			maxstatic
	)

Value:

  int _##arr##_len = 0; \
  char _##arr##_static[maxstatic * sizeof(*(arr))]

this will use stack space, up to maxstatic array elements, before switching to dynamic heap allocation

Definition at line 69 of file BLI_array.h.

Function Documentation

_bli_array_grow_func()

void _bli_array_grow_func	(	void **	arr_p,
		const void *	arr_static,
		const int	sizeof_arr_p,
		const int	arr_len,
		const int	num,
		const char *	alloc_str
	)

BLI_array.c

Doing the realloc in a macro isn't so simple, so use a function the macros can use.

This function is only to be called via macros.

Note

The caller must adjust arr_len

Definition at line 62 of file BLI_array.c.

References MEM_freeN, and MEM_mallocN.