DS_WRAP_PREALLOCATED_N_ELEMENT_ARRAY(3)

FUNCTION
ds_wrap_preallocated_n_element_array - Wrap a data structure around an array.

SYNOPSIS
#include <karma_ds.h>

multi_array * ds_wrap_preallocated_n_element_array

(char *array, unsigned int num_dim, CONST uaddr *lengths, CONST double *first_arr, CONST double *last_arr, CONST double **coordinates, CONST char **names, unsigned int num_elements, CONST unsigned int *data_types, CONST char **data_names)

DESCRIPTION
This routine will "wrap" an externally allocated array by allocating the required descriptors. The array is NOT tiled nor are any address offsets computed. The data packet that may be stored in the array contains many atomic data.

array
    The externally allocated array. This data must be externally deallocated when no longer needed. If this is NULL, then the array data is internally allocated (and should not be externally deallocated).

num_dim
    The number of dimensions of the array.

lengths
    The array of dimension lengths.

first_arr
    An array of first co-ordinate values for each dimension.

last_arr
    An array of last co-ordinate values for each dimension.

coordinates
    The array of co-ordinate array pointers. If this is NULL, all dimensions are assumed to be regularly spaced. If any co-ordinate array pointer is NULL, the corresponding dimension is assumed to be regularly spaced.

names
    The array of dimension names. If this is NULL, the names "Axis 0", "Axis 1", ...etc will be used. The character arrays are copied, so the arrays of characters and the array of pointers may be subsequently deallocated.

num_elements
    The number of elements in the array packets.

data_types
    The types of the elements in the array. See <-ds_KARMA_DATA_TYPES-> for a list of legal values.

data_names
    The names of the data type. The name strings are copied, thus the memory used for the input string may be subsequently deallocated.

RETURN VALUE
A pointer the multi_array descriptor on success, else NULL.

Multi-threading Level
Unsafe.

NOTES
This routine does NOT create a Karma arrayfile. This must be done with a call to <-dsxfr_put_multi->.

If either of <<first_arr>> or <<last_arr>> is NULL, the range of the co-ordinates will be the lengths of the dimensions minus 1. If one of the pointers is NULL, the other array is used to tie one end of the range for each dimension. If both pointers are NULL,the minima are 0.0 and the maxima are the lengths minus 1.

AUTHOR
Richard Gooch (rgooch@atnf.csiro.au)

AVAILABLITY
The Karma Distribution is available for anonymous ftp from: ftp://ftp.atnf.csiro.au/pub/software/karma/ ftp://wuarchive.wustl.edu/graphics/graphics/packages/karma/ ftp://ftp.pwr.wroc.pl/pub/karma/ The Karma Home Page is: http://www.atnf.csiro.au/karma/