ALLOCATE(3)

NAME
allocate - error checking matrix, vector, and byte allocation routines nn_malloc, nn_free, nn_realloc, allocate_vector,
allocate_ivector, allocate_iindex, allocate_dvector, allocate_pvector, allocate_structvector,
reallocate_vector, reallocate_ivector, reallocate_dvector, reallocate_pvector, reallocate_structvector,
deallocate_vector, deallocate_ivector, deallocate_dvector, deallocate_pvector, deallocate_structvector,
allocate_matrix, allocate_imatrix, allocate_dmatrix, allocate_pmatrix, allocate_structmatrix,
reallocate_matrix, reallocate_imatrix, reallocate_dmatrix, reallocate_pmatrix, reallocate_structmatrix,
reallocate_matrix_noncontig, reallocate_imatrix_noncontig, reallocate_dmatrix_noncontig, reallocate_pmatrix_noncontig, reallocate_structmatrix_noncontig,
deallocate_matrix, deallocate_imatrix, deallocate_dmatrix, deallocate_pmatrix, deallocate_structmatrix,

SYNOPSIS

char *nn_malloc(size, for_message)
int size;
char *for_message;

void *nn_free(p, for_message)
char *p;
char *for_message;

char *nn_realloc(p, size, for_message)
char *p;
int size;
char *for_message;

float *allocate_vector(n)
int n;

int *allocate_ivector(n)
int n;

int *allocate_iindex(n)
int n;

double *allocate_dvector(n)
int n;

void **allocate_pvector(n)
int n;

void *allocate_structvector(n, size)
int n, size;

float *reallocate_vector(v,old_n,new_n)
float *v;
int old_n, new_n;

int *reallocate_ivector(v,old_n,new_n)
int *v;
int old_n, new_n;

double *reallocate_dvector(v,old_n,new_n)
double *v;
int old_n, new_n;

void **reallocate_pvector(v,old_n,new_n)
void **v;
int old_n, new_n;

void *reallocate_structvector(v,old_n,new_n, size)
void *v;
int old_n, new_n, size;

void deallocate_vector(v)
float *v;

void deallocate_ivector(v)
int *v;

void deallocate_dvector(v)
double *v;

void deallocate_pvector(v)
void **v;

void deallocate_structvector(v)
void *v;

float **allocate_matrix(nrow, ncol)
int nrow, ncol;

int **allocate_imatrix(nrow, ncol)
int nrow, ncol;

double **allocate_dmatrix(nrow, ncol)
int nrow, ncol;

void ***allocate_pmatrix(nrow, ncol)
int nrow, ncol;

void **allocate_structmatrix(nrow, ncol, size)
int nrow, ncol, size;

float **reallocate_matrix(m, old_nrow, ncol, new_nrow)
float **m;
int old_nrow, ncol, new_nrow;

int **reallocate_imatrix(m, old_nrow, ncol, new_nrow)
int **m;
int old_nrow, ncol, new_nrow;

double **reallocate_dmatrix(m, old_nrow, ncol, new_nrow)
double **m;
int old_nrow, ncol, new_nrow;

void ***reallocate_pmatrix(m, old_nrow, ncol, new_nrow)
void ***m;
int old_nrow, ncol, new_nrow;

void **reallocate_structmatrix(m, old_nrow, ncol, new_nrow, size)
void **m;
int old_nrow, ncol, new_nrow, size;

float **reallocate_matrix_noncontig(m, old_nrow, ncol, new_nrow)
float **m;
int old_nrow, ncol, new_nrow;

int **reallocate_imatrix_noncontig(m, old_nrow, ncol, new_nrow)
int **m;
int old_nrow, ncol, new_nrow;

double **reallocate_dmatrix_noncontig(m, old_nrow, ncol, new_nrow)
double **m;
int old_nrow, ncol, new_nrow;

void ***reallocate_pmatrix_noncontig(m, old_nrow, ncol, new_nrow)
void ***m;
int old_nrow, ncol, new_nrow;

void **reallocate_structmatrix_noncontig(m, old_nrow, ncol, new_nrow, size)
void **m;
int old_nrow, ncol, new_nrow, size;

float **deallocate_matrix(m)
float **:

int **deallocate_imatrix(m)
int **m;

double **deallocate_dmatrix(m)
double **m;

void ***deallocate_pmatrix(m)
void ***m;

void **deallocate_structmatrix(m)
void **m;

DESCRIPTION
This is a collection of routines for doing most types of memory allocation. There is error checking for all of the routines, checking that the allocation has been successful and generating a fatal error if it was not.

BYTE ALLOCATION

nn_malloc()
nn_free()
nn_realloc()
    These routines mimic their malloc (3) counterparts. nn_malloc allocates n bytes of memory. nn_realloc changes the size of the memory block at p to size bytes long. nn_free frees space allocated using nn_malloc or nn_realloc.
    For all three routines, there is an extra argument. The for_message is a string which describes what the allocation is for. It is used in the fatal error message printed when the requested memory cannot be allocated or freed.

VECTOR ALLOCATION

allocate_vector()
allocate_ivector()
allocate_iindex()
allocate_dvector()
allocate_pvector()
allocate_structvector()
    Allocates and returns a pointer to an array of n floats, ints, doubles, pointers, or structures. All entries in the array are initialized to 0 or NULL. In the case of allocate_structvector() the structures in the array are size bytes large. allocate_iindex() uses allocate_ivector to allocate an array of n integers and then initializes the array so that array[i] = i for 0 <= i < n.

reallocate_vector()
reallocate_ivector()
reallocate_dvector()
reallocate_pvector()
reallocate_structvector()
    Changes the length of the array v, allocated as old_n entries long to new_n entries long. The pointer returned is to the new value for v, which may have been moved. All of the new data is initialized to 0 or NULL. All of the old data is copied into the new memory. The original array should have been allocated by one of the allocate_vector() routines.

deallocate_vector()
deallocate_ivector()
deallocate_dvector()
deallocate_pvector()
deallocate_structvector()
    Frees the array v which was allocated by one of the allocate_vector() routines.

MATRIX ALLOCATION

allocate_matrix()
allocate_imatrix()
allocate_dmatrix()
allocate_pmatrix()
allocate_structmatrix()
    Allocates a matrix of floats, ints, doubles, pointers, or structures. The matrix has nrow rows and ncol columns. The actual pointer returned is to a vector which holds pointers to each of the rows. This allows the user to have m[i] be a pointer to the ith row and m[i][j] be the value of the jth item in that row. &m[0][0] is a pointer to the actual matrix. The matrix entries are initialized to 0 or NULL. When using allocate_structmatrix(), size is the size of the structure.

reallocate_matrix()
reallocate_imatrix()
reallocate_dmatrix()
reallocate_pmatrix()
reallocate_structmatrix()
    Changes the number of rows in the matrix m which was allocated by one of the allocate_matrix() routines. old_nrow is the current number of rows in m. new_nrow is the number of rows in the matrix returned by reallocate_matrix.The number of columns in m, ncol, cannot be changed. All of the new data is initialized to 0 or NULL. The old data in the matrix is copied into the new memory. The array of pointers to the matrix rows, which is what m really points to, changes completely, since the whole matrix moves. size is used by reallocate_structmatrix() as the size of the structure.

reallocate_matrix_noncontig()
reallocate_imatrix_noncontig()
reallocate_dmatrix_noncontig()
reallocate_pmatrix_noncontig()
reallocate_structmatrix_noncontig()
    Increases the number of rows in the matrix m from old_nrow to new_nrow. The new rows are added as a separate matrix block and the addresses of the new rows are added to the vector of row pointers which is actually stored at m. The old rows and the pointers to them are left alone. Because the new rows were allocated separately, &m[0][0] does not point to a block of memory containing the whole matrix. Once reallocate_matrix_noncontig() has been used to increase the size of a matrix m, reallocate_matrix() cannot be used on it again.

deallocate_matrix()
deallocate_imatrix()
deallocate_dmatrix()
deallocate_pmatrix()
deallocate_structmatrix()
    Frees the matrix m which was allocated by one of the allocate_matrix() routines.

BUGS

SEE ALSO

HISTORY
First written 26 January 1993
Modified 22 June 1994: added allocate_iindex()