DG_dynarr.h

/*
 * A header-only typesafe dynamic array implementation for plain C,
 * kinda like C++ std::vector. This code is compatible with C++, but should
 * only be used with POD (plain old data) types, as it uses memcpy() etc
 * instead of copy/move construction/assignment.
 * It requires a new type (created with the DA_TYPEDEF(ELEMENT_TYPE, ARRAY_TYPE_NAME)
 * macro) for each kind of element you want to put in a dynamic array; however
 * the "functions" to manipulate the array are actually macros and the same
 * for all element types.
 * The array elements are accessed via dynArr.p[i] or da_get(dynArr, i)
 * - the latter checks whether i is a valid index and asserts if not.
 *
 * One thing to keep in mind is that, because of using macros, the arguments to
 * the "functions" are usually evaluated more than once, so you should avoid
 * putting things with side effect (like function-calls with side effects or i++)
 * into them. Notable exceptions are the value arguments (v) of da_push()
 * and da_insert(), so it's still ok to do da_push(arr, fun_with_sideffects());
 * or da_insert(a, 3, x++);
 *
 * The function-like da_* macros are short aliases of dg_dynarr_* macros.
 * If the short names clash with anything in your code or other headers
 * you are using, you can, before #including this header, do
 *  #define DG_DYNARR_NO_SHORTNAMES
 * and use the long dg_dynarr_* forms of the macros instead.
 *
 * Using this library in your project:
 *   Put this file somewhere in your project.
 *   In *one* of your .c/.cpp files, do
 *     #define DG_DYNARR_IMPLEMENTATION
 *     #include "DG_dynarr.h"
 *   to create the implementation of this library in that file.
 *   You can just #include "DG_dynarr.h" (without the #define) in other source
 *   files to use it there.
 *
 * See below this comment block for a usage example.
 *
 * You can #define your own allocators, assertion and the amount of runtime
 * checking of indexes, see CONFIGURATION section in the code for more information.
 *
 * 
 * This is heavily inspired by Sean Barrett's stretchy_buffer.h
 * ( see: https://github.com/nothings/stb/blob/master/stretchy_buffer.h )
 * However I wanted to have a struct that holds the array pointer and the length
 * and capacity, so that struct always remains at the same address while the
 * array memory might be reallocated.
 * I can live with arr.p[i] instead of arr[i], but I like how he managed to use
 * macros to create an API that doesn't force the user to specify the stored
 * type over and over again, so I stole some of his tricks :-)
 *
 * This has been tested with GCC 4.8 and clang 3.8 (-std=gnu89, -std=c99 and as C++;
 * -std=c89 works if you convert the C++-style comments to C comments) and
 * Microsoft Visual Studio 6 and 2010 (32bit) and 2013 (32bit and 64bit).
 * I guess it works with all (recentish) C++ compilers and C compilers supporting
 * C99 or even C89 + C++ comments (otherwise converting the comments should help).
 * 
 * (C) 2016 Daniel Gibson
 *
 * LICENSE
 *   This software is dual-licensed to the public domain and under the following
 *   license: you are granted a perpetual, irrevocable license to copy, modify,
 *   publish, and distribute this file as you see fit.
 *   No warranty implied; use at your own risk.
 *
 * So you can do whatever you want with this code, including copying it
 * (or parts of it) into your own source.
 * No need to mention me or this "license" in your code or docs, even though
 * it would be appreciated, of course.
 */
#if 0 // Usage Example:
 #define DG_DYNARR_IMPLEMENTATION // this define is only needed in *one* .c/.cpp file!
 #include "DG_dynarr.h"
 
 DA_TYPEDEF(int, MyIntArrType); // creates MyIntArrType - a dynamic array for ints
 
 void printIntArr(MyIntArrType* arr, const char* name)
 {
     // note that arr is a pointer here, so use *arr in the da_*() functions.
     printf("%s = {", name);
     if(da_count(*arr) > 0)
         printf(" %d", arr->p[0]);
     for(int i=1; i<da_count(*arr); ++i)
         printf(", %d", arr->p[i]);
     printf(" }\n");
 }

 void myFunction()
 {
     MyIntArrType a1 = {0}; // make sure to zero out the struct
     // instead of = {0}; you could also call da_init(a1);

     da_push(a1, 42);
     assert(da_count(a1) == 1 && a1.p[0] == 42);

     int* addedElements = da_addn_uninit(a1, 3);
     assert(da_count(a1) == 4);
     for(size_t i=0; i<3; ++i)
         addedElements[i] = i+5;

     printIntArr(&a1, "a1"); // "a1 = { 42, 5, 6, 7 }"

     MyIntArrType a2;
     da_init(a2);

     da_addn(a2, a1.p, da_count(a1)); // copy all elements from a1 to a2
     assert(da_count(a2) == 4);

     da_insert(a2, 1, 11);
     printIntArr(&a2, "a2"); // "a2 = { 42, 11, 5, 6, 7 }"

     da_delete(a2, 2);
     printIntArr(&a2, "a2"); // "a2 = { 42, 11, 6, 7 }"

     da_deletefast(a2, 0);
     printIntArr(&a2, "a2"); // "a2 = { 7, 11, 6 }"

     da_push(a1, 3);
     printIntArr(&a1, "a1"); // "a1 = { 42, 5, 6, 7, 3 }"

     int x=da_pop(a1);
     printf("x = %d\n", x);  // "x = 3"
     printIntArr(&a1, "a1"); // "a1 = { 42, 5, 6, 7 }"
     
     da_free(a1); // make sure not to leak memory!
     da_free(a2);
 }
#endif // 0 (usage example)

#ifndef DG__DYNARR_H
#define DG__DYNARR_H

// ######### CONFIGURATION #########

// following: some #defines that you can tweak to your liking

// you can reduce some overhead by defining DG_DYNARR_INDEX_CHECK_LEVEL to 2, 1 or 0
#ifndef DG_DYNARR_INDEX_CHECK_LEVEL

	// 0: (almost) no index checking
	// 1: macros "returning" something return a.p[0] or NULL if the index was invalid
	// 2: assertions in all macros taking indexes that make sure they're valid
	// 3: 1 and 2
	#define DG_DYNARR_INDEX_CHECK_LEVEL 3

#endif // DG_DYNARR_INDEX_CHECK_LEVEL

// you can #define your own DG_DYNARR_ASSERT(condition, msgstring)
// that will be used for all assertions in this code.
#ifndef DG_DYNARR_ASSERT
	#include <assert.h>
	#define DG_DYNARR_ASSERT(cond, msg)  assert((cond) && msg)
#endif

// you can #define DG_DYNARR_OUT_OF_MEMORY to some code that will be executed
// if allocating memory fails
// it's needed only before the #define DG_DYNARR_IMPLEMENTATION #include of
// this header, so the following is here only for reference and commented out
/*
 #ifndef DG_DYNARR_OUT_OF_MEMORY
	#define DG_DYNARR_OUT_OF_MEMORY  DG_DYNARR_ASSERT(0, "Out of Memory!");
 #endif
*/

// By default, C's malloc(), realloc() and free() is used to allocate/free heap memory
// (see beginning of "#ifdef DG_DYNARR_IMPLEMENTATION" block below).
// You can #define DG_DYNARR_MALLOC, DG_DYNARR_REALLOC and DG_DYNARR_FREE yourself
// to provide alternative implementations like Win32 Heap(Re)Alloc/HeapFree
// it's needed only before the #define DG_DYNARR_IMPLEMENTATION #include of
// this header, so the following is here only for reference and commented out
/*
 #define DG_DYNARR_MALLOC(elemSize, numElems)  malloc(elemSize*numElems)

 // oldNumElems is not used for C's realloc, but maybe you need it for
 // your allocator to copy the old elements over
 #define DG_DYNARR_REALLOC(ptr, elemSize, oldNumElems, newCapacity) \
 	realloc(ptr, elemSize*newCapacity);

 #define DG_DYNARR_FREE(ptr)  free(ptr)
*/

// if you want to prepend something to the non inline (DG_DYNARR_INLINE) functions,
// like "__declspec(dllexport)" or whatever, #define DG_DYNARR_DEF
#ifndef DG_DYNARR_DEF
	// by defaults it's empty.
	#define DG_DYNARR_DEF
#endif

// some functions are inline, in case your compiler doesn't like "static inline"
// but wants "__inline__" or something instead, #define DG_DYNARR_INLINE accordingly.
#ifndef DG_DYNARR_INLINE
	// for pre-C99 compilers you might have to use something compiler-specific (or maybe only "static")
	#ifdef _MSC_VER
		#define DG_DYNARR_INLINE static __inline
	#else
		#define DG_DYNARR_INLINE static inline
	#endif
#endif



// ############### Short da_* aliases for the long names ###############

#ifndef DG_DYNARR_NO_SHORTNAMES

// this macro is used to create an array type (struct) for elements of TYPE
// use like DA_TYPEDEF(int, MyIntArrType); MyIntArrType ia = {0}; da_push(ia, 42); ...
#define DA_TYPEDEF(TYPE, NewArrayTypeName) \
	DG_DYNARR_TYPEDEF(TYPE, NewArrayTypeName)

// makes sure the array is initialized and can be used.
// either do YourArray arr = {0}; or YourArray arr; da_init(arr);
#define da_init(a) \
	dg_dynarr_init(a)

/*
 * This allows you to provide an external buffer that'll be used as long as it's big enough
 * once you add more elements than buf can hold, fresh memory will be allocated on the heap
 * Use like:
 * DA_TYPEDEF(double, MyDoubleArrType);
 * MyDoubleArrType arr;
 * double buf[8];
 * dg_dynarr_init_external(arr, buf, 8);
 * dg_dynarr_push(arr, 1.23);
 * ...
 */
#define da_init_external(a, buf, buf_cap) \
	dg_dynarr_init_external(a, buf, buf_cap)

// use this to free the memory allocated by dg_dynarr once you don't need the array anymore
// Note: it is safe to add new elements to the array after da_free()
//       it will allocate new memory, just like it would directly after da_init()
#define da_free(a) \
	dg_dynarr_free(a)


// add an element to the array (appended at the end)
#define da_push(a, v) \
	dg_dynarr_push(a, v)

// add an element to the array (appended at the end)
// does the same as push, just for consistency with addn (like insert and insertn)
#define da_add(a, v) \
	dg_dynarr_add(a, v)

// append n elements to a and initialize them from array vals, doesn't return anything
// ! vals (and all other args) are evaluated multiple times !
#define da_addn(a, vals, n) \
	dg_dynarr_addn(a, vals, n)

// add n elements to the end of the array and zeroes them with memset()
// returns pointer to first added element, NULL if out of memory (array is empty then)
#define da_addn_zeroed(a, n) \
	dg_dynarr_addn_zeroed(a, n)

// add n elements to the end of the array, will remain uninitialized
// returns pointer to first added element, NULL if out of memory (array is empty then)
#define da_addn_uninit(a, n) \
	dg_dynarr_addn_uninit(a, n)


// insert a single value v at index idx
#define da_insert(a, idx, v) \
	dg_dynarr_insert(a, idx, v)

// insert n elements into a at idx, initialize them from array vals
// doesn't return anything
// ! vals (and all other args) is evaluated multiple times ! 
#define da_insertn(a, idx, vals, n) \
	dg_dynarr_insertn(a, idx, vals, n)

// insert n elements into a at idx and zeroe them with memset() 
// returns pointer to first inserted element or NULL if out of memory
#define da_insertn_zeroed(a, idx, n) \
	dg_dynarr_insertn_zeroed(a, idx, n)

// insert n uninitialized elements into a at idx;
// returns pointer to first inserted element or NULL if out of memory
#define da_insertn_uninit(a, idx, n) \
	dg_dynarr_insertn_uninit(a, idx, n)

// set a single value v at index idx - like "a.p[idx] = v;" but with checks (unless disabled)
#define da_set(a, idx, v) \
	dg_dynarr_set(a, idx, v)

// overwrite n elements of a, starting at idx, with values from array vals
// doesn't return anything
// ! vals (and all other args) is evaluated multiple times ! 
#define da_setn(a, idx, vals, n) \
	dg_dynarr_setn(a, idx, vals, n)

// delete the element at idx, moving all following elements (=> keeps order)
#define da_delete(a, idx) \
	dg_dynarr_delete(a, idx)

// delete n elements starting at idx, moving all following elements (=> keeps order)
#define da_deleten(a, idx, n) \
	dg_dynarr_deleten(a, idx, n)

// delete the element at idx, move the last element there (=> doesn't keep order)
#define da_deletefast(a, idx) \
	dg_dynarr_deletefast(a, idx)

// delete n elements starting at idx, move the last n elements there (=> doesn't keep order)
#define da_deletenfast(a, idx, n) \
	dg_dynarr_deletenfast(a, idx, n)

// removes all elements from the array, but does not free the buffer
// (if you want to free the buffer too, just use da_free())
#define da_clear(a) \
	dg_dynarr_clear(a)

// sets the logical number of elements in the array
// if cnt > dg_dynarr_count(a), the logical count will be increased accordingly
// and the new elements will be uninitialized
#define da_setcount(a, cnt) \
	dg_dynarr_setcount(a, cnt)

// make sure the array can store cap elements without reallocating
// logical count remains unchanged
#define da_reserve(a, cap) \
	dg_dynarr_reserve(a, cap)

// this makes sure a only uses as much memory as for its elements
// => maybe useful if a used to contain a huge amount of elements,
//    but you deleted most of them and want to free some memory
// Note however that this implies an allocation and copying the remaining
// elements, so only do this if it frees enough memory to be worthwhile!
#define da_shrink_to_fit(a) \
	dg_dynarr_shrink_to_fit(a)


// removes and returns the last element of the array
#define da_pop(a) \
	dg_dynarr_pop(a)

// returns the last element of the array
#define da_last(a) \
	dg_dynarr_last(a)

// returns the pointer *to* the last element of the array
// (in contrast to dg_dynarr_end() which returns a pointer *after* the last element)
// returns NULL if array is empty
#define da_lastptr(a) \
	dg_dynarr_lastptr(a)

// get element at index idx (like a.p[idx]), but with checks
// (unless you disabled them with #define DG_DYNARR_INDEX_CHECK_LEVEL 0)
#define da_get(a, idx) \
	dg_dynarr_get(a,idx)

// get pointer to element at index idx (like &a.p[idx]), but with checks
// and it returns NULL if idx is invalid
#define da_getptr(a, idx) \
	dg_dynarr_getptr(a, idx)

// returns a pointer to the first element of the array
// (together with dg_dynarr_end() you can do C++-style iterating)
#define da_begin(a) \
	dg_dynarr_begin(a)

// returns a pointer to the past-the-end element of the array
// Allows C++-style iterating, in case you're into that kind of thing:
// for(T *it=da_begin(a), *end=da_end(a); it!=end; ++it) foo(*it);
// (see da_lastptr() to get a pointer *to* the last element)
#define da_end(a) \
	dg_dynarr_end(a)


// returns (logical) number of elements currently in the array
#define da_count(a) \
	dg_dynarr_count(a)

// get the current reserved capacity of the array
#define da_capacity(a) \
	dg_dynarr_capacity(a)

// returns 1 if the array is empty, else 0
#define da_empty(a) \
	dg_dynarr_empty(a)

// returns 1 if the last (re)allocation when inserting failed (Out Of Memory)
//   or if the array has never allocated any memory yet, else 0
// deleting the contents when growing fails instead of keeping old may seem
// a bit uncool, but it's simple and OOM should rarely happen on modern systems
// anyway - after all you need to deplete both RAM and swap/pagefile.sys
#define da_oom(a) \
	dg_dynarr_oom(a)


// sort a using the given qsort()-comparator cmp
// (just a slim wrapper around qsort())
#define da_sort(a, cmp) \
	dg_dynarr_sort(a, cmp)

#endif // DG_DYNARR_NO_SHORTNAMES


// ######### Implementation of the actual macros (using the long names) ##########

// use like DG_DYNARR_TYPEDEF(int, MyIntArrType); MyIntArrType ia = {0}; dg_dynarr_push(ia, 42); ...
#define DG_DYNARR_TYPEDEF(TYPE, NewArrayTypeName) \
	typedef struct { TYPE* p; dg__dynarr_md md; } NewArrayTypeName;

// makes sure the array is initialized and can be used.
// either do YourArray arr = {0}; or YourArray arr; dg_dynarr_init(arr);
#define dg_dynarr_init(a) \
	dg__dynarr_init((void**)&(a).p, &(a).md, NULL, 0)

// this allows you to provide an external buffer that'll be used as long as it's big enough
// once you add more elements than buf can hold, fresh memory will be allocated on the heap
#define dg_dynarr_init_external(a, buf, buf_cap) \
	dg__dynarr_init((void**)&(a).p, &(a).md, (buf), (buf_cap))

// use this to free the memory allocated by dg_dynarr
// Note: it is safe to add new elements to the array after dg_dynarr_free()
//       it will allocate new memory, just like it would directly after dg_dynarr_init()
#define dg_dynarr_free(a) \
	dg__dynarr_free((void**)&(a).p, &(a).md)


// add an element to the array (appended at the end)
#define dg_dynarr_push(a, v) \
	(dg__dynarr_maybegrowadd(dg__dynarr_unp(a), 1) ? (((a).p[(a).md.cnt++] = (v)),0) : 0)

// add an element to the array (appended at the end)
// does the same as push, just for consistency with addn (like insert and insertn)
#define dg_dynarr_add(a, v) \
	dg_dynarr_push((a), (v))

// append n elements to a and initialize them from array vals, doesn't return anything
// ! vals (and all other args) are evaluated multiple times !
#define dg_dynarr_addn(a, vals, n) do { \
	DG_DYNARR_ASSERT((vals)!=NULL, "Don't pass NULL als vals to dg_dynarr_addn!"); \
	if((vals)!=NULL && dg__dynarr_add(dg__dynarr_unp(a), n, 0)) { \
	  size_t i_=(a).md.cnt-(n), v_=0; \
	  while(i_<(a).md.cnt)  (a).p[i_++]=(vals)[v_++]; \
	} } DG__DYNARR_WHILE0

// add n elements to the end of the array and zeroe them with memset()
// returns pointer to first added element, NULL if out of memory (array is empty then)
#define dg_dynarr_addn_zeroed(a, n) \
	(dg__dynarr_add(dg__dynarr_unp(a), (n), 1) ? &(a).p[(a).md.cnt-(size_t)(n)] : NULL)

// add n elements to the end of the array, which are uninitialized
// returns pointer to first added element, NULL if out of memory (array is empty then)
#define dg_dynarr_addn_uninit(a, n) \
	(dg__dynarr_add(dg__dynarr_unp(a), (n), 0) ? &(a).p[(a).md.cnt-(size_t)(n)] : NULL)

// insert a single value v at index idx
#define dg_dynarr_insert(a, idx, v) \
	(dg__dynarr_checkidxle((a),(idx)), \
	 dg__dynarr_insert(dg__dynarr_unp(a), (idx), 1, 0), \
	 (a).p[dg__dynarr_idx((a).md, (idx))] = (v))

// insert n elements into a at idx, initialize them from array vals
// doesn't return anything
// ! vals (and all other args) is evaluated multiple times ! 
#define dg_dynarr_insertn(a, idx, vals, n) do { \
	DG_DYNARR_ASSERT((vals)!=NULL, "Don't pass NULL as vals to dg_dynarr_insertn!"); \
	dg__dynarr_checkidxle((a),(idx)); \
	if((vals)!=NULL && dg__dynarr_insert(dg__dynarr_unp(a), (idx), (n), 0)){ \
		size_t i_=(idx), v_=0, e_=(idx)+(n); \
		while(i_ < e_)  (a).p[i_++] = (vals)[v_++]; \
	}} DG__DYNARR_WHILE0

// insert n elements into a at idx and zeroe them with memset() 
// returns pointer to first inserted element or NULL if out of memory
#define dg_dynarr_insertn_zeroed(a, idx, n) \
	(dg__dynarr_checkidxle((a),(idx)), \
	 dg__dynarr_insert(dg__dynarr_unp(a), (idx), (n), 1) \
	  ? &(a).p[dg__dynarr_idx((a).md, (idx))] : NULL)

// insert n uninitialized elements into a at idx;
// returns pointer to first inserted element or NULL if out of memory
#define dg_dynarr_insertn_uninit(a, idx, n) \
	(dg__dynarr_checkidxle((a),(idx)), \
	 dg__dynarr_insert(dg__dynarr_unp(a), idx, n, 0) \
	  ? &(a).p[dg__dynarr_idx((a).md, (idx))] : NULL)

// set a single value v at index idx - like "a.p[idx] = v;" but with checks (unless disabled)
#define dg_dynarr_set(a, idx, v) \
	(dg__dynarr_checkidx((a),(idx)), \
	 (a).p[dg__dynarr_idx((a).md, (idx))] = (v))

// overwrite n elements of a, starting at idx, with values from array vals
// doesn't return anything
// ! vals (and all other args) is evaluated multiple times ! 
#define dg_dynarr_setn(a, idx, vals, n) do { \
	DG_DYNARR_ASSERT((vals)!=NULL, "Don't pass NULL as vals to dg_dynarr_setn!"); \
	size_t idx_=(idx); size_t end_=idx_+(size_t)n; \
	dg__dynarr_checkidx((a),idx_); dg__dynarr_checkidx((a),end_-1); \
	if((vals)!=NULL && idx_ < (a).md.cnt && end_ <= (a).md.cnt) { \
		size_t v_=0; \
		while(idx_ < end_)  (a).p[idx_++] = (vals)[v_++]; \
	}} DG__DYNARR_WHILE0


// delete the element at idx, moving all following elements (=> keeps order)
#define dg_dynarr_delete(a, idx) \
	(dg__dynarr_checkidx((a),(idx)), dg__dynarr_delete(dg__dynarr_unp(a), (idx), 1))

// delete n elements starting at idx, moving all following elements (=> keeps order)
#define dg_dynarr_deleten(a, idx, n) \
	(dg__dynarr_checkidx((a),(idx)), dg__dynarr_delete(dg__dynarr_unp(a), (idx), (n)))
	// TODO: check whether idx+n < count?

// delete the element at idx, move the last element there (=> doesn't keep order)
#define dg_dynarr_deletefast(a, idx) \
	(dg__dynarr_checkidx((a),(idx)), dg__dynarr_deletefast(dg__dynarr_unp(a), (idx), 1))

// delete n elements starting at idx, move the last n elements there (=> doesn't keep order)
#define dg_dynarr_deletenfast(a, idx, n) \
	(dg__dynarr_checkidx((a),(idx)), dg__dynarr_deletefast(dg__dynarr_unp(a), idx, n))
	// TODO: check whether idx+n < count?

// removes all elements from the array, but does not free the buffer
// (if you want to free the buffer too, just use dg_dynarr_free())
#define dg_dynarr_clear(a) \
	((a).md.cnt=0)

// sets the logical number of elements in the array
// if cnt > dg_dynarr_count(a), the logical count will be increased accordingly
// and the new elements will be uninitialized
#define dg_dynarr_setcount(a, n) \
	(dg__dynarr_maybegrow(dg__dynarr_unp(a), (n)) ? ((a).md.cnt = (n)) : 0)

// make sure the array can store cap elements without reallocating
// logical count remains unchanged
#define dg_dynarr_reserve(a, cap) \
	dg__dynarr_maybegrow(dg__dynarr_unp(a), (cap))

// this makes sure a only uses as much memory as for its elements
// => maybe useful if a used to contain a huge amount of elements,
//    but you deleted most of them and want to free some memory
// Note however that this implies an allocation and copying the remaining
// elements, so only do this if it frees enough memory to be worthwhile!
#define dg_dynarr_shrink_to_fit(a) \
	dg__dynarr_shrink_to_fit(dg__dynarr_unp(a))


#if (DG_DYNARR_INDEX_CHECK_LEVEL == 1) || (DG_DYNARR_INDEX_CHECK_LEVEL == 3)

	// removes and returns the last element of the array
	#define dg_dynarr_pop(a) \
		(dg__dynarr_check_notempty((a), "Don't pop an empty array!"), \
		 (a).p[((a).md.cnt > 0) ? (--(a).md.cnt) : 0])

	// returns the last element of the array
	#define dg_dynarr_last(a) \
		(dg__dynarr_check_notempty((a), "Don't call da_last() on an empty array!"), \
		 (a).p[((a).md.cnt > 0) ? ((a).md.cnt-1) : 0])

#elif (DG_DYNARR_INDEX_CHECK_LEVEL == 0) || (DG_DYNARR_INDEX_CHECK_LEVEL == 2)

	// removes and returns the last element of the array
	#define dg_dynarr_pop(a) \
		(dg__dynarr_check_notempty((a), "Don't pop an empty array!"), \
		 (a).p[--(a).md.cnt])

	// returns the last element of the array
	#define dg_dynarr_last(a) \
		(dg__dynarr_check_notempty((a), "Don't call da_last() on an empty array!"), \
		 (a).p[(a).md.cnt-1])

#else // invalid DG_DYNARR_INDEX_CHECK_LEVEL
	#error Invalid index check level DG_DYNARR_INDEX_CHECK_LEVEL (must be 0-3) !
#endif // DG_DYNARR_INDEX_CHECK_LEVEL

// returns the pointer *to* the last element of the array
// (in contrast to dg_dynarr_end() which returns a pointer *after* the last element)
// returns NULL if array is empty
#define dg_dynarr_lastptr(a) \
	(((a).md.cnt > 0) ? ((a).p + (a).md.cnt - 1) : NULL)

// get element at index idx (like a.p[idx]), but with checks
// (unless you disabled them with #define DG_DYNARR_INDEX_CHECK_LEVEL 0)
#define dg_dynarr_get(a, idx) \
	(dg__dynarr_checkidx((a),(idx)), (a).p[dg__dynarr_idx((a).md, (idx))])

// get pointer to element at index idx (like &a.p[idx]), but with checks
// (unless you disabled them with #define DG_DYNARR_INDEX_CHECK_LEVEL 0)
// if index-checks are disabled, it returns NULL on invalid index (else it asserts() before returning)
#define dg_dynarr_getptr(a, idx) \
	(dg__dynarr_checkidx((a),(idx)), \
	 ((size_t)(idx) < (a).md.cnt) ? ((a).p+(size_t)(idx)) : NULL)

// returns a pointer to the first element of the array
// (together with dg_dynarr_end() you can do C++-style iterating)
#define dg_dynarr_begin(a) \
	((a).p)

// returns a pointer to the past-the-end element of the array
// Allows C++-style iterating, in case you're into that kind of thing:
// for(T *it=dg_dynarr_begin(a), *end=dg_dynarr_end(a); it!=end; ++it) foo(*it);
// (see dg_dynarr_lastptr() to get a pointer *to* the last element)
#define dg_dynarr_end(a) \
	((a).p + (a).md.cnt)


// returns (logical) number of elements currently in the array
#define dg_dynarr_count(a) \
	((a).md.cnt)

// get the current reserved capacity of the array
#define dg_dynarr_capacity(a) \
	((a).md.cap & DG__DYNARR_SIZE_T_ALL_BUT_MSB)

// returns 1 if the array is empty, else 0
#define dg_dynarr_empty(a) \
	((a).md.cnt == 0)

// returns 1 if the last (re)allocation when inserting failed (Out Of Memory)
//   or if the array has never allocated any memory yet, else 0
// deleting the contents when growing fails instead of keeping old may seem
// a bit uncool, but it's simple and OOM should rarely happen on modern systems
// anyway - after all you need to deplete both RAM and swap/pagefile.sys
// or deplete the address space, which /might/ happen with 32bit applications
// but probably not with 64bit (at least in the foreseeable future)
#define dg_dynarr_oom(a) \
	((a).md.cap == 0)


// sort a using the given qsort()-comparator cmp
// (just a slim wrapper around qsort())
#define dg_dynarr_sort(a, cmp) \
	qsort((a).p, (a).md.cnt, sizeof((a).p[0]), (cmp))


// ######### Implementation-Details that are not part of the API ##########

#include <stdlib.h> // size_t, malloc(), free(), realloc()
#include <string.h> // memset(), memcpy(), memmove()

#ifdef __cplusplus
extern "C" {
#endif

typedef struct {
	size_t cnt; // logical number of elements
	size_t cap; // cap & DG__DYNARR_SIZE_T_ALL_BUT_MSB is actual capacity (in elements, *not* bytes!)
		// if(cap & DG__DYNARR_SIZE_T_MSB) the current memory is not allocated by dg_dynarr,
		// but was set with dg_dynarr_init_external()
		// that's handy to give an array a base-element storage on the stack, for example
		// TODO: alternatively, we could introduce a flag field to this struct and use that,
		//       so we don't have to calculate & everytime cap is needed
} dg__dynarr_md;

// I used to have the following in an enum, but MSVC assumes enums are always 32bit ints
static const size_t DG__DYNARR_SIZE_T_MSB = ((size_t)1) << (sizeof(size_t)*8 - 1);
static const size_t DG__DYNARR_SIZE_T_ALL_BUT_MSB = (((size_t)1) << (sizeof(size_t)*8 - 1))-1;

// "unpack" the elements of an array struct for use with helper functions
// (to void** arr, dg__dynarr_md* md, size_t itemsize)
#define dg__dynarr_unp(a) \
	(void**)&(a).p, &(a).md, sizeof((a).p[0])

// MSVC warns about "conditional expression is constant" when using the
// do { ... } while(0) idiom in macros.. 
#ifdef _MSC_VER
  #if _MSC_VER >= 1400 // MSVC 2005 and newer
    // people claim MSVC 2005 and newer support __pragma, even though it's only documented
    // for 2008+ (https://msdn.microsoft.com/en-us/library/d9x1s805%28v=vs.90%29.aspx)
    // the following workaround is based on
    // http://cnicholson.net/2009/03/stupid-c-tricks-dowhile0-and-c4127/
    #define DG__DYNARR_WHILE0 \
      __pragma(warning(push)) \
      __pragma(warning(disable:4127)) \
      while(0) \
      __pragma(warning(pop))
  #else // older MSVC versions don't support __pragma - I heard this helps for them
    #define DG__DYNARR_WHILE0  while(0,0)
  #endif

#else // other compilers

	#define DG__DYNARR_WHILE0  while(0)

#endif // _MSC_VER


#if (DG_DYNARR_INDEX_CHECK_LEVEL == 2) || (DG_DYNARR_INDEX_CHECK_LEVEL == 3)

	#define dg__dynarr_checkidx(a,i) \
		DG_DYNARR_ASSERT((size_t)i < a.md.cnt, "index out of bounds!")

	// special case for insert operations: == cnt is also ok, insert will append then
	#define dg__dynarr_checkidxle(a,i) \
		DG_DYNARR_ASSERT((size_t)i <= a.md.cnt, "index out of bounds!")

	#define dg__dynarr_check_notempty(a, msg) \
		DG_DYNARR_ASSERT(a.md.cnt > 0, msg)

#elif (DG_DYNARR_INDEX_CHECK_LEVEL == 0) || (DG_DYNARR_INDEX_CHECK_LEVEL == 1)

	// no assertions that check if index is valid
	#define dg__dynarr_checkidx(a,i) (void)0
	#define dg__dynarr_checkidxle(a,i) (void)0

	#define dg__dynarr_check_notempty(a, msg) (void)0

#else // invalid DG_DYNARR_INDEX_CHECK_LEVEL
	#error Invalid index check level DG_DYNARR_INDEX_CHECK_LEVEL (must be 0-3) !
#endif // DG_DYNARR_INDEX_CHECK_LEVEL


#if (DG_DYNARR_INDEX_CHECK_LEVEL == 1) || (DG_DYNARR_INDEX_CHECK_LEVEL == 3)

	// the given index, if valid, else 0
	#define dg__dynarr_idx(md,i) \
		(((size_t)(i) < md.cnt) ? (size_t)(i) : 0)

#elif (DG_DYNARR_INDEX_CHECK_LEVEL == 0) || (DG_DYNARR_INDEX_CHECK_LEVEL == 2)

	// don't check and default to 0 if invalid, but just use the given value
	#define dg__dynarr_idx(md,i) (size_t)(i)

#else // invalid DG_DYNARR_INDEX_CHECK_LEVEL
	#error Invalid index check level DG_DYNARR_INDEX_CHECK_LEVEL (must be 0-3) !
#endif // DG_DYNARR_INDEX_CHECK_LEVEL

// the functions allocating/freeing memory are not implemented inline, but
// in the #ifdef DG_DYNARR_IMPLEMENTATION section
// one reason is that dg__dynarr_grow has the most code in it, the other is
// that windows has weird per-dll heaps so free() or realloc() should be
// called from code in the same dll that allocated the memory - these kind
// of wrapper functions that end up compiled into the exe or *one* dll
// (instead of inline functions compiled into everything) should ensure that.

DG_DYNARR_DEF void
dg__dynarr_free(void** p, dg__dynarr_md* md);

DG_DYNARR_DEF void
dg__dynarr_shrink_to_fit(void** arr, dg__dynarr_md* md, size_t itemsize);

// grow array to have enough space for at least min_needed elements
// if it fails (OOM), the array will be deleted, a.p will be NULL, a.md.cap and a.md.cnt will be 0
// and the functions returns 0; else (on success) it returns 1
DG_DYNARR_DEF int
dg__dynarr_grow(void** arr, dg__dynarr_md* md, size_t itemsize, size_t min_needed);


// the following functions are implemented inline, because they're quite short
// and mosty implemented in functions so the macros don't get too ugly

DG_DYNARR_INLINE void
dg__dynarr_init(void** p, dg__dynarr_md* md, void* buf, size_t buf_cap)
{
	*p = buf;
	md->cnt = 0;
	if(buf == NULL)  md->cap = 0;
	else md->cap = (DG__DYNARR_SIZE_T_MSB | buf_cap);
}

DG_DYNARR_INLINE int
dg__dynarr_maybegrow(void** arr, dg__dynarr_md* md, size_t itemsize, size_t min_needed)
{
	if((md->cap & DG__DYNARR_SIZE_T_ALL_BUT_MSB) >= min_needed)  return 1;
	else return dg__dynarr_grow(arr, md, itemsize, min_needed);
}

DG_DYNARR_INLINE int
dg__dynarr_maybegrowadd(void** arr, dg__dynarr_md* md, size_t itemsize, size_t num_add)
{
	size_t min_needed = md->cnt+num_add;
	if((md->cap & DG__DYNARR_SIZE_T_ALL_BUT_MSB) >= min_needed)  return 1;
	else return dg__dynarr_grow(arr, md, itemsize, min_needed);
}

DG_DYNARR_INLINE int
dg__dynarr_insert(void** arr, dg__dynarr_md* md, size_t itemsize, size_t idx, size_t n, int init0)
{
	// allow idx == md->cnt to append
	size_t oldCount = md->cnt;
	size_t newCount = oldCount+n;
	if(idx <= oldCount && dg__dynarr_maybegrow(arr, md, itemsize, newCount))
	{
		unsigned char* p = (unsigned char*)*arr; // *arr might have changed in dg__dynarr_grow()!
		// move all existing items after a[idx] to a[idx+n]
		if(idx < oldCount)  memmove(p+(idx+n)*itemsize, p+idx*itemsize, itemsize*(oldCount - idx));

		// if the memory is supposed to be zeroed, do that
		if(init0)  memset(p+idx*itemsize, 0, n*itemsize);

		md->cnt = newCount;
		return 1;
	}
	return 0;
}

DG_DYNARR_INLINE int
dg__dynarr_add(void** arr, dg__dynarr_md* md, size_t itemsize, size_t n, int init0)
{
	size_t cnt = md->cnt;
	if(dg__dynarr_maybegrow(arr, md, itemsize, cnt+n))
	{
		unsigned char* p = (unsigned char*)*arr; // *arr might have changed in dg__dynarr_grow()!
		// if the memory is supposed to be zeroed, do that
		if(init0)  memset(p+cnt*itemsize, 0, n*itemsize);

		md->cnt += n;
		return 1;
	}
	return 0;
}

DG_DYNARR_INLINE void
dg__dynarr_delete(void** arr, dg__dynarr_md* md, size_t itemsize, size_t idx, size_t n)
{
	size_t cnt = md->cnt;
	if(idx < cnt)
	{
		if(idx+n >= cnt)  md->cnt = idx; // removing last element(s) => just reduce count
		else
		{
			unsigned char* p = (unsigned char*)*arr;
			// move all items following a[idx+n] to a[idx]
			memmove(p+itemsize*idx, p+itemsize*(idx+n), itemsize*(cnt - (idx+n)));
			md->cnt -= n;
		}
	}
}

DG_DYNARR_INLINE void
dg__dynarr_deletefast(void** arr, dg__dynarr_md* md, size_t itemsize, size_t idx, size_t n)
{
	size_t cnt = md->cnt;
	if(idx < cnt)
	{
		if(idx+n >= cnt)  md->cnt = idx; // removing last element(s) => just reduce count
		else
		{
			unsigned char* p = (unsigned char*)*arr;
			// copy the last n items to a[idx] - but handle the case that
			// the array has less than n elements left after the deleted elements
			size_t numItemsAfterDeleted = cnt - (idx+n);
			size_t m = (n < numItemsAfterDeleted) ? n : numItemsAfterDeleted;
			memcpy(p+itemsize*idx, p+itemsize*(cnt - m), itemsize*m);
			md->cnt -= n;
		}
	}
}

#ifdef __cplusplus
} // extern "C"
#endif

#endif // DG__DYNARR_H


// ############## Implementation of non-inline functions ##############

#ifdef DG_DYNARR_IMPLEMENTATION

// by default, C's malloc(), realloc() and free() is used to allocate/free heap memory.
// you can #define DG_DYNARR_MALLOC, DG_DYNARR_REALLOC and DG_DYNARR_FREE
// to provide alternative implementations like Win32 Heap(Re)Alloc/HeapFree
// 
#ifndef DG_DYNARR_MALLOC
	#define DG_DYNARR_MALLOC(elemSize, numElems)  malloc(elemSize*numElems)

	// oldNumElems is not used here, but maybe you need it for your allocator
	// to copy the old elements over
	#define DG_DYNARR_REALLOC(ptr, elemSize, oldNumElems, newCapacity) \
		realloc(ptr, elemSize*newCapacity);

	#define DG_DYNARR_FREE(ptr)  free(ptr)
#endif

// you can #define DG_DYNARR_OUT_OF_MEMORY to some code that will be executed
// if allocating memory fails
#ifndef DG_DYNARR_OUT_OF_MEMORY
	#define DG_DYNARR_OUT_OF_MEMORY  DG_DYNARR_ASSERT(0, "Out of Memory!");
#endif


#ifdef __cplusplus
extern "C" {
#endif

DG_DYNARR_DEF void
dg__dynarr_free(void** p, dg__dynarr_md* md)
{
	// only free memory if it doesn't point to external memory
	if(!(md->cap & DG__DYNARR_SIZE_T_MSB))
	{
		DG_DYNARR_FREE(*p);
		*p = NULL;
		md->cap = 0;
	}
	md->cnt = 0;
}


DG_DYNARR_DEF int
dg__dynarr_grow(void** arr, dg__dynarr_md* md, size_t itemsize, size_t min_needed)
{
	size_t cap = md->cap & DG__DYNARR_SIZE_T_ALL_BUT_MSB;

	DG_DYNARR_ASSERT(min_needed > cap, "dg__dynarr_grow() should only be called if storage actually needs to grow!");

	if(min_needed < DG__DYNARR_SIZE_T_MSB)
	{
		size_t newcap = (cap > 4) ? (2*cap) : 8; // allocate for at least 8 elements
		// make sure not to set DG__DYNARR_SIZE_T_MSB (unlikely anyway)
		if(newcap >= DG__DYNARR_SIZE_T_MSB)  newcap = DG__DYNARR_SIZE_T_MSB-1;
		if(min_needed > newcap)  newcap = min_needed;

		// the memory was allocated externally, don't free it, just copy contents
		if(md->cap & DG__DYNARR_SIZE_T_MSB)
		{
			void* p = DG_DYNARR_MALLOC(itemsize, newcap);
			if(p != NULL)  memcpy(p, *arr, itemsize*md->cnt);
			*arr = p;
		}
		else
		{
			void* p = DG_DYNARR_REALLOC(*arr, itemsize, md->cnt, newcap);
			if(p == NULL)  DG_DYNARR_FREE(*arr); // realloc failed, at least don't leak memory
			*arr = p;
		}

		// TODO: handle OOM by setting highest bit of count and keeping old data?

		if(*arr)  md->cap = newcap;
		else
		{
			md->cap = 0;
			md->cnt = 0;
			
			DG_DYNARR_OUT_OF_MEMORY ;
			
			return 0;
		}
		return 1;
	}
	DG_DYNARR_ASSERT(min_needed < DG__DYNARR_SIZE_T_MSB, "Arrays must stay below SIZE_T_MAX/2 elements!");
	return 0;
}

DG_DYNARR_DEF void
dg__dynarr_shrink_to_fit(void** arr, dg__dynarr_md* md, size_t itemsize)
{
	// only do this if we allocated the memory ourselves
	if(!(md->cap & DG__DYNARR_SIZE_T_MSB))
	{
		size_t cnt = md->cnt;
		if(cnt == 0)  dg__dynarr_free(arr, md);
		else if((md->cap & DG__DYNARR_SIZE_T_ALL_BUT_MSB) > cnt)
		{
			void* p = DG_DYNARR_MALLOC(itemsize, cnt);
			if(p != NULL)
			{
				memcpy(p, *arr, cnt*itemsize);
				md->cap = cnt;
				DG_DYNARR_FREE(*arr);
				*arr = p;
			}
		}
	}
}

#ifdef __cplusplus
} // extern "C"
#endif

#endif // DG_DYNARR_IMPLEMENTATION