
#define	array_SIZEOF_DTYPE(size, dtype)
	get size of datatype.
#define	array_DTYPESTRING(dtstring, dtype)
	convert datatype to a string representation.
#define	array_NUMEL(a) ( ((a)->nbytes)/((a)->dtype_size) )
	get number of elements in array.
#define	array_DTYPEPRINT(out, dtype, mem)
	Print an array-datatype.
#define	array_MEMSET(mem, dtype, val)
	set the memory mem to value of type dtype.
#define	array_INDEX1(array, dtype, i1)
	fast 1D array indexing typecasting to C-type.
#define	array_INDEX2(array, dtype, i1, i2)
	fast 2D array indexing typecasting to C-type.
#define	array_INDEX3(array, dtype, i1, i2, i3)
	fast 3D array indexing typecasting to C-type.
#define	array_INDEXMEM1(array, i1)
	fast 1D array indexing returning a void pointer.
#define	array_INDEXMEM2(array, i1, i2)
	fast 2D array indexing returning a void pointer.
#define	array_INDEXMEM3(array, i1, i2, i3)
	fast 3D array indexing returning a void pointer.
enum	DType { CHAR = 0, UINT, INT, LONG, ULONG, FLOAT, DOUBLE }
	Data-types for Array struct. More...
Array *	array_new (DType dtype, uint ndim, const uint *dims)
	Initialize new array struct.
Array *	array_new2 (DType dtype, uint ndim,...)
	Initialize new array struct.
Array *	array_fromptr (DType dtype, uint ndim, void data, const uint size)
	Initialize new array struct.
Array *	array_fromptr2 (DType dtype, uint ndim, void *data,...)
	Initialize new array struct.
Array *	array_new_dummy (DType dtype, uint ndim,...)
	create array that is filled with values from 1 to n over all dimensions.
Array *	array_randunif (unsigned long seed, uint ndim,...)
	create array that is filled with random values from [0, ..., 1].
bool	array_comparable (const Array a, const Array b)
	Compare two array's dimensions and datatype.
Array *	array_copy (const Array *in, bool allocdata)
	makes a copy of an array.
void	array_free (Array *a)
	free all memory associated with the array.
void	array_shuffle (Array *a, unsigned long seed)
	shuffle the entries of an array.
void	array_typecast (Array *a, DType target_type)
	Array-typecast.
void *	array_index (const Array a, uint idx)
	Index the array.
void *	array_index2 (const Array *a,...)
	Index the array.
Array *	array_slice (const Array a, const char slicedesc)
	Extract sub-arrays from array.
Array *	array_concatenate (const Array a, const Array b, int dim)
	concatenate two arrays.
int	array_scale (Array *a, double x)
	multiply all entries in array with x.
void	array_reverse (Array *a)
	Reverse order of elements in a (in-place).
int	array_dimred (Array *a)
	Delete unnecessary dimensions (of size 1).
void *	array_max (const Array *a)
	Get maximum element from array.
void *	array_min (const Array *a)
	Get minimum element from array.
Array *	array_convert_rowcolmajor (Array *a, bool alloc)
	convert a row-major array to col-major.
void	array_calc_colindex (ulong idx, const uint size, uint nsize, uint index)
	calculate the column-major index-tuple given the offset from element 0.
void	array_calc_rowindex (ulong idx, const uint size, uint nsize, uint index)
	calculate the row-major index-tuple given the offset from element 0.
void	array_print (Array a, uint nel_per_dim, FILE out)
	print an array.
void	array_dtype_to_double (double out, void mem, DType dt)
	cast memory of type dt in location mem to double.

Detailed Description

STATUS: work in progress Numerical Arrays.

This is an efficient implementation of a numerical array of

arbitrary dimension and
arbitrary type. It wraps a thin layer around a one-dimensional (void *) for efficiency.

The library provides some convenient functionality:

Define Documentation

#define array_DTYPEPRINT	(	out,
		dtype,
		mem
	)

Value:

switch( dtype ){                                                                    \
  case CHAR:                                                                            \
     fprintf( out, "%c", *(char*)(mem) ); break;                                \
  case UINT:                                                                            \
     fprintf( out, "%i", *(uint*)(mem) ); break;                                \
  case INT:                                                                             \
     fprintf( out, "%i", *(int*)(mem) ); break;                             \
  case LONG:                                                                            \
     fprintf( out, "%li", *(long*)(mem) ); break;                           \
  case ULONG:                                                                           \
     fprintf( out, "%li", *(ulong*)(mem) ); break;                          \
  case FLOAT:                                                                           \
     fprintf( out, "%.2f", *(float*)(mem) ); break;                         \
  case DOUBLE:                                                                          \
     fprintf( out, "%.2f", *(double*)(mem) ); break;                            \
  default:                                                                              \
     warnprintf("Do not know this datatype: %i\n", dtype );             \
  }

Print an array-datatype.

Parameters:

	out	FILE* output stream
	dtype	one of DType
	mem	void* memory containing the to-be-printed value

Definition at line 233 of file array.h.

#define array_DTYPESTRING	(	dtstring,
		dtype
	)

Value:

switch( dtype ){                                                                    \
  case CHAR:                                                                            \
     dtstring="char";break;                                                         \
  case UINT:                                                                            \
     dtstring="uint";break;                                                         \
  case INT:                                                                             \
     dtstring="int";break;                                                          \
  case LONG:                                                                            \
     dtstring="long";break;                                                         \
  case ULONG:                                                                           \
     dtstring="unsigned long"; break;                                           \
  case FLOAT:                                                                           \
     dtstring="float"; break;                                                       \
  case DOUBLE:                                                                          \
     dtstring="double"; break;                                                      \
  default:                                                                              \
     warnprintf("Do not know this datatype: %i\n", dtype );             \
  }

convert datatype to a string representation.

Parameters:

	dtstring	(output), char* to hold the string
	dtype	(input) the datatype

Definition at line 201 of file array.h.

#define array_INDEX1	(	array,
		dtype,
		i1
	)

Value:

(*((dtype*)( ((array)->data) +                                      \
                    ((i1)*((array)->dtype_size)) )))

fast 1D array indexing typecasting to C-type.

index the array and assume only one dimension (not checked). These indexing macros are not safe but as fast as you can get. For more convenience, you can use the dimension independant array_index() and array_index2() functions.

Example:

     double a;
     a = array_INDEX1( a, double, 10 ); // accesses a[10] and converts to double

Parameters:

	array	an Array object
	dtype	a valid c-data type (int, float, double, ... )
	i1,...,iN	the index for each of the dimensions

Definition at line 297 of file array.h.

#define array_INDEX2	(	array,
		dtype,
		i1,
		i2
	)

Value:

(*((dtype*)( ((array)->data)+                                                           \
                    ((i1)*((array)->size[1])*((array)->dtype_size))+                    \
                    ((i2)*((array)->dtype_size)) )))

fast 2D array indexing typecasting to C-type.

Definition at line 302 of file array.h.

#define array_INDEX3	(	array,
		dtype,
		i1,
		i2,
		i3
	)

Value:

(*((dtype*)( ((array)->data)+                                                           \
                    ((i1)*((array)->size[1])*((array)->size[2])*((array)->dtype_size))+ \
                    ((i2)*((array)->size[2])*((array)->dtype_size))+                    \
                    ((i3)*((array)->dtype_size)) )))

fast 3D array indexing typecasting to C-type.

Definition at line 308 of file array.h.

#define array_INDEXMEM1	(	array,
		i1
	)

Value:

( ((array)->data) +                                                     \
     ((i1)*((array)->dtype_size)) )

fast 1D array indexing returning a void pointer.

index the array and assume only one dimension (not checked). These indexing macros are not safe but as fast as you can get. For more convenience, you can use the dimension independant array_index() and array_index2() functions.

Example:

     void *a;
     a = array_INDEXMEM1( a, 10 ); // accesses a[10] of any type

Parameters:

	array	an Array object
	i1,...,iN	the index for each of the dimensions

Definition at line 331 of file array.h.

#define array_INDEXMEM2	(	array,
		i1,
		i2
	)

Value:

( ((array)->data)+                                                                      \
     ((i1)*((array)->size[1])*((array)->dtype_size))+                               \
     ((i2)*((array)->dtype_size)) )

fast 2D array indexing returning a void pointer.

Definition at line 336 of file array.h.

#define array_INDEXMEM3	(	array,
		i1,
		i2,
		i3
	)

Value:

( ((array)->data)+                                                                      \
     ((i1)*((array)->size[1])*((array)->size[2])*((array)->dtype_size))+            \
     ((i2)*((array)->size[2])*((array)->dtype_size))+                               \
     ((i3)*((array)->dtype_size)) )

fast 3D array indexing returning a void pointer.

Definition at line 342 of file array.h.

#define array_MEMSET	(	mem,
		dtype,
		val
	)

Value:

switch( dtype ){                                                                        \
  case CHAR:                                                                                \
     *((char*)(mem)) = (char)val;break;                                             \
  case UINT:                                                                                \
     *((uint*)(mem)) = (uint)val;break;                                             \
  case INT:                                                                                 \
     *((int*)(mem)) = (int)val;break;                                                   \
  case LONG:                                                                                \
     *((long*)(mem)) = (long)val;break;                                             \
  case ULONG:                                                                               \
     *((ulong*)(mem)) = (ulong)val;break;                                               \
  case FLOAT:                                                                               \
     *((float*)(mem)) = (float)val;break;                                               \
  case DOUBLE:                                                                              \
     *((double*)(mem)) = (double)val;break;                                         \
  default:                                                                                  \
     warnprintf("Do not know this datatype: %i\n", dtype );                 \
  }

set the memory mem to value of type dtype.

Parameters:

	(out)	void * mem
	dtype	one of DType
	val	int,float,double...

Definition at line 259 of file array.h.

#define array_NUMEL ( a ) ( ((a)->nbytes)/((a)->dtype_size) )

get number of elements in array.

Parameters:

a

Array*

Definition at line 224 of file array.h.

#define array_SIZEOF_DTYPE	(	size,
		dtype
	)

Value:

switch( dtype ) {                                                                   \
  case CHAR:                                                                            \
    size=sizeof(char);break;                                                        \
  case UINT:                                                                            \
    size=sizeof(uint);break;                                                        \
  case INT:                                                                             \
    size=sizeof(int);break;                                                         \
  case LONG:                                                                            \
    size=sizeof(long);break;                                                        \
  case ULONG:                                                                           \
    size=sizeof(unsigned long); break;                                          \
  case FLOAT:                                                                           \
    size=sizeof(float); break;                                                      \
  case DOUBLE:                                                                          \
    size=sizeof(double); break;                                                 \
  default:                                                                              \
     warnprintf("Do not know this datatype: %i\n", dtype );             \
  }

get size of datatype.

fill variable size with the size of the datatype dtype in bytes. E.g.

        array_SIZEOF_DTYPE( array->dtype_size, dtype );

Parameters:

	size	(output) uint to hold the size
	dtype	(input) the datatype

Definition at line 177 of file array.h.

Enumeration Type Documentation

enum DType

Data-types for Array struct.

Enumerator:

CHAR
UINT
INT
LONG
ULONG
FLOAT
DOUBLE

Definition at line 349 of file array.h.

Function Documentation

void array_calc_colindex	(	ulong	offset,
		const uint *	size,
		uint	nsize,
		uint *	index
	)

calculate the column-major index-tuple given the offset from element 0.

It is assumed, that the data is in row-major format.

Parameters:

	offset
	size	the dimensions of the array
	nsize	number of dimensions
	index	(output) the index tuple

Definition at line 271 of file array.c.

void array_calc_rowindex	(	ulong	offset,
		const uint *	size,
		uint	nsize,
		uint *	index
	)

calculate the row-major index-tuple given the offset from element 0.

It is assumed, that the data is in row-major format.

Parameters:

	offset
	size	the dimensions of the array
	nsize	number of dimensions
	index	(output) the index tuple

Definition at line 244 of file array.c.

bool array_comparable	(	const Array *	a,
		const Array *	b
	)

Compare two array's dimensions and datatype.

Parameters:

a,b

the two arrays to be tested

Returns:: TRUE if both arrays have same dimensionality, FALSE otherwise.

Definition at line 344 of file array.c.

Array* array_concatenate	(	const Array *	a,
		const Array *	b,
		int	dim
	)

concatenate two arrays.

The two arrays must have the same number of elements in all dimensions except in the concatenated dimension.

Todo:: currently works only for 1D and 2D. implement nD if necessary.

Example:

	 [ 1 2     [ 7 8 
	   3 4       9 10
      5 6 ]    11 12] 

		=> [ 1 2
		     3 4
           5 6
           7 8
           9 10
			  11 12 ]

Parameters:

	a,b	the two arrays to concatenate (must be 1D/2D arrays of arbitrary type); if one of them is NULL, return a copy of the other one
	dim	the dimension along which they are to be concatenated (0-rows, 1-columns)

Returns:: the concatenation of a and b

Definition at line 167 of file array.c.

Array* array_convert_rowcolmajor	(	Array *	a,
		bool	alloc
	)

convert a row-major array to col-major.

This is a d-dimensional matrix-transpose.

Parameters:

	a	the row-major array
	alloc	if TRUE, allocate new memory, else overwrite a

Returns:: a new col-major array

Definition at line 297 of file array.c.

Array* array_copy	(	const Array *	in,
		bool	allocdata
	)

makes a copy of an array.

The flag allocdata determines, whether the memory is copied.

Parameters:

	in	input
	allocdata	allocate own data, or share data between arrays. Shared memory belongs to to the passed array.

Returns:: the copy

Definition at line 376 of file array.c.

int array_dimred ( Array * a )

Delete unnecessary dimensions (of size 1).

Dimensions of size 1 are removed from the size-array of the struct.

Parameters:

a

in-place reduction

Returns:: 0 on success, other on failure

Definition at line 395 of file array.c.

void array_dtype_to_double	(	double *	out,
		void *	mem,
		DType	dt
	)

cast memory of type dt in location mem to double.

Parameters:

	out	output double
	mem	the memory
	dt	the DType of mem

Definition at line 933 of file array.c.

void array_free ( Array * a )

free all memory associated with the array.

Definition at line 958 of file array.c.

Array* array_fromptr	(	DType	dtype,
		uint	ndim,
		void *	data,
		const uint *	size
	)

Initialize new array struct.

Memory for the data is not allocated but set to data.

Warning:: the array does NOT take over the responsibility for the memory. I.e. if you call array_free() it is NOT free'd. If you want this to happen, you need to set array->free_data to TRUE.

Parameters:

	dtype	the datatype of the array
	ndim	number of dimensions
	data	the data for the array
	...	the number of elements in each of the dimensions

Returns:: array

Definition at line 904 of file array.c.

Array* array_fromptr2	(	DType	dtype,
		uint	ndim,
		void *	data,
			...
	)

Initialize new array struct.

Memory for the data is not allocated but set to data.

Warning:: the array does NOT take over the responsibility for the memory. I.e. if you call array_free() it is NOT free'd. If you want this to happen, you need to set array->free_data to TRUE.

Parameters:

	dtype	the datatype of the array
	ndim	number of dimensions
	data	the data for the array
	...	the number of elements in each of the dimensions

Returns:: array

Definition at line 869 of file array.c.

void* array_index	(	const Array *	a,
		uint *	idx
	)

Index the array.

You need to provide as many arguments as there are dimensions in the array. A pointer to the corresponding memory in the array is returned. To use it you need to cast it:

     uint idx[3]={1,2,3};
     float a = *(float*)array_index( arr, idx );

Parameters:

	a	the array
	idx	array of size a->ndim giving the indices

Returns:: pointer to the memory at the specific location

Definition at line 638 of file array.c.

void* array_index2	(	const Array *	a,
			...
	)

Index the array.

You need to provide as many arguments as there are dimensions in the array. A pointer to the corresponding memory in the array is returned. To use it you need to cast it:

     float a = *(float*)array_index2( arr, 1, 2 );

Parameters:

	a	the array
	...	a->ndim integers

Returns:: pointer to the memory at the specific location

Definition at line 672 of file array.c.

void* array_max ( const Array * a )

Get maximum element from array.

You can easily find the index of this element by doing

     Array *a = get_array_from_somewhere();
     long idx = (array_max(a)-(a->data))/a->dtype_size;
     // if you need an index-tuple, you can do
     uint idxtuple[num_dimension];
     array_calc_rowindex( idx, a->size, a->ndim, idxtuple );

Note:: this function is a bit slow, as it converts everything to double before comparing. If you need it fast, you should consider writing a specialised function.

Parameters:

a

the array

Returns:: pointer to the maximum element

Definition at line 46 of file array.c.

void* array_min ( const Array * a )

Get minimum element from array.

You can easily find the index of this element by doing

     Array *a = get_array_from_somewhere();
     long idx = (array_min(a)-(a->data))/a->dtype_size;
     // if you need an index-tuple, you can do
     uint idxtuple[num_dimension];
     array_calc_rowindex( idx, a->size, a->ndim, idxtuple );

Note:: this function is a bit slow, as it converts everything to double before comparing. If you need it fast, you should consider writing a specialised function.

Parameters:

a

the array

Returns:: pointer to the minimum element

Definition at line 80 of file array.c.

Array* array_new	(	DType	dtype,
		uint	ndim,
		const uint *	dims
	)

Initialize new array struct.

Memory for the data is allocated and set to zero.

Parameters:

	dtype	the datatype of the array
	ndim	number of dimensions
	dims	number of elements in each of the dimensions

Returns:: array

Definition at line 699 of file array.c.

Array* array_new2	(	DType	dtype,
		uint	ndim,
			...
	)

Initialize new array struct.

Memory for the data is allocated and set to zero.

Parameters:

	dtype	the datatype of the array
	ndim	number of dimensions
	...	the number of elements in each of the dimensions

Returns:: array

Definition at line 737 of file array.c.

Array* array_new_dummy	(	DType	dtype,
		uint	ndim,
			...
	)

create array that is filled with values from 1 to n over all dimensions.

Mainly used for debugging stuff.

Parameters:

	dtype	the datatype of the array
	ndim	number of dimensions
	...	the number of elements in each of the dimensions

Returns:: array

Definition at line 830 of file array.c.

void array_print	(	Array *	a,
		uint	nel_per_dim,
		FILE *	out
	)

print an array.

Print to an output stream, nel_per_dim elements per dimension. Passing -1 for nel_per_dim prints everything.

Parameters:

	a	the array
	nel_per_dim	number of elements to print per dimension
	out	the output file/stream

Definition at line 603 of file array.c.

Array* array_randunif	(	unsigned long	seed,
		uint	ndim,
			...
	)

create array that is filled with random values from [0, ..., 1].

Mainly used for debugging stuff.

Parameters:

	seed	to use for the random numbers; if seed=0, the current time is used
	ndim	number of dimensions
	...	the number of elements in each of the dimensions

Returns:: array

Definition at line 767 of file array.c.

void array_reverse ( Array * a )

Reverse order of elements in a (in-place).

Dimensionality is not considered. I.e., the function loops over all elements such as they are stored in memory.

Parameters:

a

the array

Definition at line 323 of file array.c.

int array_scale	(	Array *	a,
		double	x
	)

multiply all entries in array with x.

Parameters:

	a	the input/output array
	x	the scalar to multiply a with

Definition at line 422 of file array.c.

void array_shuffle	(	Array *	a,
		unsigned long	seed
	)

shuffle the entries of an array.

Parameters:

	a	the array (arbitrary type and dimensionality)
	seed	if 0, use time(NULL), else the seed

Definition at line 805 of file array.c.

Array* array_slice	(	const Array *	a,
		const char *	slicedesc
	)

Extract sub-arrays from array.

This is a function for creating array slices from an existing array. I.e. you can extract sub-arrays similar to interpreted languages like python or MATLAB.

See Slicing Array Objects for the format of the slice string.

Parameters:

	a	the array
	slicedesc	the description of the slice as described in Slicing Array Objects

Returns:: a freshly allocated array containing the slice

Definition at line 522 of file array.c.

void array_typecast	(	Array *	a,
		DType	target_type
	)

Array-typecast.

Typecast the whole array.

Warning:

in case that sizeof(target_type)<sizeof(current_type), you lose precision
in case that sizeof(target_type)!=sizeof(current_type), it is slow because the whole data is copied

Parameters:

	a	the array
	target_type	the target type

Definition at line 108 of file array.c.