destroy objects and free up memory

SYNOPSIS

#include "matrix.h"
void IV_FREE(IVEC *iv)
void M_FREE (MAT *A)
void PX_FREE(PERM *pi)
void V_FREE (VEC *v)
int  iv_free_vars(IVEC **iv1, IVEC **iv2, ..., NULL)
int   m_free_vars(MAT  **A1,  MAT  **A2,  ..., NULL)
int  px_free_vars(PERM **pi1, PERM **pi2, ..., NULL)
int   v_free_vars(VEC  **v1,  VEC  **v2,  ..., NULL)

#include "zmatrix.h"
void ZM_FREE(ZMAT *A)
void ZV_FREE(ZVEC *v)
int  zm_free_vars(ZMAT  **A1, ZMAT  **A2, ..., NULL)
int  zv_free_vars(ZVEC  **v1, ZVEC  **v2, ..., NULL)

DESCRIPTION

The .._FREE() routines are in fact all macros which result in calls to thje corresponding .._free() function, so that IV_FREE(iv) calls iv_free(iv). The effect of calling .._free() is to release all the memory associated with the object passed. The effect of the macros .._FREE(object) is to firstly release all the memory associated with the object passed, and to then set object to have the value NULL. The reason for using macros is to avoid the ``dangling pointer'' problem. The problems of dangling pointers cannot be entirely overcome within a conventional language, such as `C', as the following code illustrates:

VEC     *x, *y;
  ....
x = v_get(10);
y = x;          /* y and x now point to the same place */
V_FREE(x);      /* x is now VNULL */
/* y now "dangles" -- using y can be dangerous */
y->ve[9] = 1.0; /* overwriting malloc area! */
V_FREE(y);      /* program will probably crash here! */

The .._free_vars() functions free a NULL-terminated list of pointers to variables all of the same type. Calling

.._free_vars(&x1,&x2,...,&xN,NULL)

is equivalent to

.._free(x1);  x1 = NULL;
.._free(x2);  x2 = NULL;
  ......
.._free(xN);  xN = NULL;

The returned value of the .._free_vars() routines is the number of objects freed.