mdarrays - a library to simplify using multidimensional arrays in C

Two of the biggest pitfalls creating mathematical software in C are the lack of array bounds checking, and the difficulty in working with multidimensional arrays. Bounds checking is desirable during debugging, but lack of bounds checking is desirable after a program has been debugged, because the speed penalty for bounds checking is enormous. This package addresses these two problems.

The type parameter is actually used two ways internally by the library. The first is as a macro stringification, which means that the macro compares what you use in the type parameter to a list of strings. The strings allowed are: char, int, bool, unsigned int, uint, long int, float, double, long double, real. Internally the bool type is really unsigned char type. The second way is to use sizeof(type) to determine the allocation needed for each array element.

If you are creating an array of pointers to objects, use MDARRAYS_ALLOCATE_OBJECT, MDARRAYS_ALLOCATE_AND_CLEAR_OBJECT, MDARRAYS_ALLOCATE_AND_FILL_OBJECT, which are identical to the above routines except that they allow type to be anything (internally, mdarrays just creates an array of void pointers and allocates space based on what sizeof(type) says).

For the special case of arrays to type gpointer, a direct memory image of each array element is written sequentially to a binary file. Note that this could case non-portability problems for several reasons.

All other arrays are represented as ASCII text numbers, with enough decimal places to hold their type. For all the file storage functions, the order of array output is the same as the order of array elements in memory for C. A simple example will probably make this clear. Assume a 2D array with dimensions [2][2]. The output will be:

aa[1][1] aa[1][2] aa[2][1] aa[2][2]
    

If you write a function to read these files, assume that the separator between each array element is "any amount of whitespace".

The printing functions are very similar to the save functions in the previous section, although they are modified to make arrays look better to humans. Also, the GPOINTER type is printed instead of writing a memory image like with the save functions. There are currently no non-mdarray print functions.

If the default print or save formatting style is not what you want, use the style macro functions. For style macros, the following definitions apply:

The style functions are:

void MDARRAYS_FOREACH(void *array, mdarrays_foreach_function foreach_function,
                      void *user_data);
    

where mdarrays_foreach_function is defined:

typedef void (*mdarrays_foreach_function)(void *array, uint *indices, void *user_data);
    

Call the user-defined foreach_function once for each element of array. user_data is passed directly to foreach_function. Note that foreach_function should not assume anything about the order it will receive the elements of the array.

An example using MDARRAYS_FOREACH:

void foreach_function(void *array, uint *indices, void *user_data)
{
  // Assign the value pointed to by user_data for all elements where the 
  // array indices are the same for both dimensions
  if (indices[0] == indices[1]) 
    array[indices[0]][indices[0]] = *((double *)user_data);
}

void main(void)
{
  double **aa;
  double value = 3;
  aa = (double **)MDARRAYS_ALLOCATE(double, 5, 6);
  MDARRAYS_FOREACH(aa, foreach_function, &value);
}
    

MDARRAYS_COPY(void *from, uint from_offset, void *to, uint to_offset)
    

Copy elements of from array to to array starting at element from_offset in the from array and to_offset in the to array. Stop if end of either array is reached.