Multi-Dimensional Dynamic Array Boost Library Proposal

From: Richard Hogaboom (richard.hogaboom_at_[hidden])
Date: 2019-10-23 20:20:39

I've written a library at GitHub/rahogaboom/daa that does dynamic array 
allocation in ptr to ptr ... style that is very simple to use(only two 
routines), header file only, can allocate an unlimited number of 
dimensions with subscripts for each dimension starting at an arbitrary 
number e.g. 0, 1, -5 etc, can allocate anything you can take sizeof() 
and allocates all in one contiguous block(stack, heap) for easy 
freeing.  I'm aware of the Boost.MultiArray library, however, I think 
daa has some advantages.  Specifically, a. each dimension has it's own 
starting subscript b. it's relative simplicity(2 routines) c. it's 
longevity - 30 years and two articles d. also can be used in a C only 
environment.  Following is the points noted in the GitHub README.md:

|Library:
 Â Â Â  daa.hpp

Dynamic Array Allocator - C++ header file only library

 Â Â Â  - ptr to ptr to ... style arbitrary N dimensional array allocator 
of anything you can take sizeof()

 Â Â Â  - arbitrary starting subscript(0, 1, -10, ...) for each separate 
dimension - Note: for each array
 Â Â Â Â Â  dimension the starting subscript and dimension size determine the 
valid subscripts for that
 Â Â Â Â Â  dimension - any index outside that range is invalid and will give 
unpredictable results

 Â Â Â  - allocates anything of any type(double, int, long, struct, ...)

 Â Â Â  - one contiguous block allocation of memory for all ptr's and 
data(locality of
 Â Â Â Â Â  reference and easy free())

 Â Â Â  - array or slices of array can be passed to subroutines to any 
depth, modified there,
 Â Â Â Â Â  and be seen at all levels

 Â Â Â  - simple library, two routines(das()(calculate space needed) and 
daa()(allocate ptr to ptr ... array))

 Â Â Â  - no library dependencies(except standard header files)

 Â Â Â  - initialization pointer argument set to instance of initialized 
type or NULL for no initialization

 Â Â Â  - implemented by a recursive routine(ptr_init()) which calls two 
other different recursive
 Â Â Â Â Â  routines(off() and doff())

 Â Â Â  - see article in Embedded Systems Programming, Dec. 2000, "Flexible 
Dynamic Array Allocation"(included)

 Â Â Â  - see article in The C Users Journal, Nov. 1990. "A Flexible 
Dynamic Array Allocator"(included)

 Â Â Â  - 18 verification tests that show code usage examples, see daa_test.cpp

 Â Â Â  - see cut/paste Examples section and API(das(), daa()) section below

 Â Â Â  - a daa-compile.tar file is provided with a non-header 
compiled(clang, clang++, gcc, g++) version

 Â Â Â  - for an excellent reference on this type of array(ptr to ptr to 
...) access see Numerical Recipes
 Â Â Â Â Â  in C, Press, Flannery, Teukolsky, and Vettering, Cambridge 
University Press, 1992, pg. 20-23.
 Â Â Â Â Â  Ch. 1 Preliminaries -> 1.2 Some C Conventions for Scientific 
Computing -> Matrices and
       Two-Dimensional Arrays.  From the above reference read:
 Â Â Â Â Â Â Â Â Â  'Here is our bottom line: We avoid the fixed-size 
two-dimensional arrays of C as
 Â Â Â Â Â Â Â Â Â Â  being unsuitable data structures for representing matrices 
in scientific computing. We
            adopt instead the convention “pointer to array of pointers,” 
with the array elements
 Â Â Â Â Â Â Â Â Â Â  pointing to the first element in the rows of each matrix.'

 Â Â Â  - this file is the entire documentation needed to use the library

 Â Â Â  - Author: Richard Hogaboom, richard.hogaboom_at_[hidden]|

|Â Â Â Â Â  Usage:
 Â Â Â  - das() - find size necessary
 Â Â Â Â Â  malloc()(or whatever memory allocation routine) - allocate memory
 Â Â Â Â Â  daa() - populate allocated memory

 Â Â Â  - allocate auto stack or static area storage e.g. unsigned char 
mem[SIZE]
 Â Â Â Â Â  das() - determine if array will fit in mem[]
 Â Â Â Â Â  daa() - populate allocated memory
|

|Example:|

|Â Â Â Â Â Â Â Â Â Â Â  int err_code = 0;
 Â Â Â Â Â Â Â Â Â Â Â  int asize = 0;
 Â Â Â Â Â Â Â Â Â Â Â  char *mem_ptr;

 Â Â Â Â Â Â Â Â Â Â Â  unsigned int d[4] = {3, 5, 4, 2}; /* dimensions */
 Â Â Â Â Â Â Â Â Â Â Â  int st[4] = {-1, -5, 10, 0}; /* starting subscripts */
 Â Â Â Â Â Â Â Â Â Â Â  double ****array = NULL; /* array pointer */

 Â Â Â Â Â Â Â Â Â Â Â  asize = das(sizeof(double), 4, d, &err_code);

 Â Â Â Â Â Â Â Â Â Â Â  mem_ptr = (char *)malloc(asize);

 Â Â Â Â Â Â Â Â Â Â Â  array = (double ****) daa(sizeof(double), 4, d, st, 
&err_code, mem_ptr, NULL);|

|Â Â Â Â Â Â Â Â Â Â Â  double d = array[-1][-5][10][0];|

-- 
Richard A Hogaboom
16 Alprilla Farm Road
Hopkinton, MA 01748-1922
richard.hogaboom_at_[hidden]
www.linkedin.com/in/richardhogaboom/
www.github.com/rahogaboom
M508-330-3775