/* Copyright (c) Colorado School of Mines, 2011.*/
/* All rights reserved. */
/*********************** self documentation **********************/
/*****************************************************************************
ALLOC - Allocate and free multi-dimensional arrays
alloc1 allocate a 1-d array
realloc1 re-allocate a 1-d array
free1 free a 1-d array
alloc2 allocate a 2-d array
free2 free a 2-d array
alloc3 allocate a 3-d array
free3 free a 3-d array
alloc4 allocate a 4-d array
free4 free a 4-d array
alloc5 allocate a 5-d array
free5 free a 5-d array
alloc6 allocate a 6-d array
free6 free a 6-d arrayalloc1int
allocate a 1-d array of ints
realloc1int re-allocate a 1-d array of ints
free1int free a 1-d array of ints
alloc2int allocate a 2-d array of ints
free2int free a 2-d array of ints
alloc3int allocate a 3-d array of ints
free3int free a 3-d array of ints
alloc1float allocate a 1-d array of floats
realloc1float re-allocate a 1-d array of floats
free1float free a 1-d array of floats
alloc2float allocate a 2-d array of floats
free2float free a 2-d array of floats
alloc3float allocate a 3-d array of floats
free3float free a 3-d array of floats
alloc4float allocate a 4-d array of floats
free4float free a 4-d array of floats
alloc5float allocate a 5-d array of floats
free5float free a 5-d array of floats
alloc6float allocate a 6-d array of floats
free6float free a 6-d array of floats
alloc4int allocate a 4-d array of ints
free4int free a 4-d array of ints
alloc5int allocate a 5-d array of ints
free5int free a 5-d array of ints
alloc5uchar allocate a 5-d array of unsigned chars
free5uchar free a 5-d array of unsiged chars
alloc5ushort allocate a 5-d array of unsigned shorts
free5ushort free a 5-d array of unsiged shorts
alloc6ushort allocate a 6-d array of unsigned shorts
free6ushort free a 6-d array of unsiged shorts
alloc1double allocate a 1-d array of doubles
realloc1double re-allocate a 1-d array of doubles
free1double free a 1-d array of doubles
alloc2double allocate a 2-d array of doubles
free2double free a 2-d array of doubles
alloc3double allocate a 3-d array of doubles
free3double free a 3-d array of doubles
alloc1complex allocate a 1-d array of complexs
realloc1complex re-allocate a 1-d array of complexs
free1complex free a 1-d array of complexs
alloc2complex allocate a 2-d array of complexs
free2complex free a 2-d array of complexs
alloc3complex allocate a 3-d array of complexs
free3complex free a 3-d array of complexs
alloc1dcomplex allocate a 1-d array of complexs
realloc1dcomplex re-allocate a 1-d array of complexs
free1dcomplex free a 1-d array of complexs
alloc2dcomplex allocate a 2-d array of complexs
free2dcomplex free a 2-d array of complexs
alloc3dcomplex allocate a 3-d array of complexs
free3dcomplex free a 3-d array of complexs
******************************************************************************
Function Prototypes:
void *alloc1 (size_t n1, size_t size);
void *realloc1 (void *v, size_t n1, size_t size);
void free1 (void *p);
void **alloc2 (size_t n1, size_t n2, size_t size);
void free2 (void **p);
void ***alloc3 (size_t n1, size_t n2, size_t n3, size_t size);
void free3 (void ***p);
void ****alloc4 (size_t n1, size_t n2, size_t n3, size_t n4, size_t size);
void free4 (void ****p);
void *****alloc5 (size_t n1, size_t n2, size_t n3, size_t n4, size_t n5, size_t size);
void free5 (void *****p);
void ******alloc6 (size_t n1, size_t n2, size_t n3, size_t n4, size_t n5, size_t n6,
size_t size);
void free6 (void ******p);
int *alloc1int (size_t n1);
int *realloc1int (int *v, size_t n1);
void free1int (int *p);
int **alloc2int (size_t n1, size_t n2);
void free2int (int **p);
int ***alloc3int (size_t n1, size_t n2, size_t n3);
void free3int (int ***p);
float *alloc1float (size_t n1);
float *realloc1float (float *v, size_t n1);
void free1float (float *p);
float **alloc2float (size_t n1, size_t n2);
void free2float (float **p);
float ***alloc3float (size_t n1, size_t n2, size_t n3);
void free3float (float ***p);
float ****alloc4float (size_t n1, size_t n2, size_t n3, size_t n4);
void free4float (float ****p);
float *****alloc5float (size_t n1, size_t n2, size_t n3, size_t n4, size_t n5);
void free5float (float *****p);
float ******alloc6float (size_t n1, size_t n2, size_t n3, size_t n4, size_t n5,
size_t n6);
void free6float (float ******p);
int ****alloc4int (size_t n1, size_t n2, size_t n3, size_t n4);
void free4int (int ****p);
int *****alloc5int (size_t n1, size_t n2, size_t n3, size_t n4, size_t n5);
void free5int (int *****p);
unsigned char *****alloc5uchar(size_t n1,size_t n2,size_t n3,size_t n4,
size_t n5);
void free5uchar(unsigned char *****p);
unsigned short *****alloc5ushort(size_t n1,size_t n2,size_t n3,size_t n4,
size_t n5);
void free5ushort(unsigned short *****p);
unsigned short ******alloc6ushort(size_t n1,size_t n2,size_t n3,size_t n4,
size_t n5,size_t n6);
void free6ushort(unsigned short ******p);
double *alloc1double (size_t n1);
double *realloc1double (double *v, size_t n1);
void free1double (double *p);
double **alloc2double (size_t n1, size_t n2);
void free2double (double **p);
double ***alloc3double (size_t n1, size_t n2, size_t n3);
void free3double (double ***p);
complex *alloc1complex (size_t n1);
complex *realloc1complex (complex *v, size_t n1);
void free1complex (complex *p);
complex **alloc2complex (size_t n1, size_t n2);
void free2complex (complex **p);
complex ***alloc3complex (size_t n1, size_t n2, size_t n3);
void free3complex (complex ***p);
complex *alloc1dcomplex (size_t n1);
complex *realloc1dcomplex (dcomplex *v, size_t n1);
void free1dcomplex (dcomplex *p);
complex **alloc2dcomplex (size_t n1, size_t n2);
void free2dcomplex (dcomplex **p);
complex ***alloc3dcomplex (size_t n1, size_t n2, size_t n3);
void free3dcomplex (dcomplex ***p);
******************************************************************************
Notes:
The functions defined below are intended to simplify manipulation
of multi-dimensional arrays in scientific programming in C. These
functions are useful only because true multi-dimensional arrays
in C cannot have variable dimensions (as in FORTRAN). For example,
the following function IS NOT valid in C:
void badFunc(a,n1,n2)
float a[n2][n1];
{
a[n2-1][n1-1] = 1.0;
}
However, the following function IS valid in C:
void goodFunc(a,n1,n2)
float **a;
{
a[n2-1][n1-1] = 1.0;
}
Therefore, the functions defined below do not allocate true
multi-dimensional arrays, as described in the C specification.
Instead, they allocate and initialize pointers (and pointers to
pointers) so that, for example, a[i2][i1] behaves like a 2-D array.
The array dimensions are numbered, which makes it easy to add
functions for arrays of higher dimensions. In particular,
the 1st dimension of length n1 is always the fastest dimension,
the 2nd dimension of length n2 is the next fastest dimension,
and so on. Note that the 1st (fastest) dimension n1 is the
first argument to the allocation functions defined below, but
that the 1st dimension is the last subscript in a[i2][i1].
(This is another important difference between C and Fortran.)
The allocation of pointers to pointers implies that more storage
is required than is necessary to hold a true multi-dimensional array.
The fraction of the total storage allocated that is used to hold
pointers is approximately 1/(n1+1). This extra storage is unlikely
to represent a significant waste for large n1.
The functions defined below are significantly different from similar
functions described by Press et al, 1988, NR in C.
In particular, the functions defined below:
(1) Allocate arrays of arbitrary size elements.
(2) Allocate contiguous storage for arrays.
(3) Return NULL if allocation fails (just like malloc).
(4) Do not provide arbitrary lower and upper bounds for arrays.
Contiguous storage enables an allocated multi-dimensional array to
be passed to a C function that expects a one-dimensional array.
For example, to allocate and zero an n1 by n2 two-dimensional array
of floats, one could use
a = alloc2(n1,n2,sizeof(float));
zeroFloatArray(n1*n2,a[0]);
where zeroFloatArray is a function defined as
void zeroFloatArray(int n, float *a)
{
int i;
for (i=0; i
