wv_matalloc: usage

The following description is also available in the source code (wv_matalloc.c):

  void \*wv\_matalloc (size\_t size, void \*data, int ndim, ...)
  void \*wv\_matallocv (size\_t size, void \*data, int ndim, unsigned int\*dims)

  allocates memory and builds pointerstructure for
  ndim dimensional matrix. 

  Note: wv\_matalloc is thread safe I think. 

  size: size in bytes of matrix elements to be allocated
  data: if (void \*)0: wv\_matalloc allocates memory
        else it is assumed data is already allocated
  ndim: number of dimensions of matrix to allocate
  ... : dimensions of the matrix to be allocated of type unsigned int

  dims: dimensions of matrix to be allocated

  return value: pointer to pointerstructure to access arrayelements
                (void *)0 if something wrong with parameters or
                          if malloc doesn't work

  example:

   allocate 2-dimensional matrix, elements of type double,
   dimensions M and N:

     double **a;
     a=wv\_matalloc(sizeof(double),(void *)0,2,M,N);

     usage of a is then like: a[i][j] = 3;

   allocate 4-dimensional matrix, elements of type int,
   dimensions m,n,p,q:

     int ****a;
     m=8; n=123; p=9; q=11;
     a=wv\_matalloc(sizeof(int),(void *)0,4,m,n,p,q);
     
     a[i][j][k][l] = 12;

   3-dimensional matrix, elements of type double,
   dimensions l,m,n. Space for data is already allocated,
   so in fact, only the pointer structure is set up:

   double *a;
   double ***x;

   a=(double *) malloc(sizeof(double)*l*m*n);  
   
      a allocated outside wv\_matalloc 

   x=wv\_matalloc(sizeof(double),a,3,l,m,n);

      x[0][0][0] is the same element as a[0] 

 void wv\_matfree(void *p)
   
   Frees memory occupied by pointers and perhaps data allocated by
   wv\_matalloc. Only the space allocated by wv\_matalloc is freed.

   p:  returnvalue of wv\_matalloc

   example

   char ***a;
   a=wv\_matalloc(sizeof(char),(void *)0,3,10,20,15);
   
   wv\_matfree(a);