Resizing data structures

SYNOPSIS

#include "matrix.h"
BAND  *bd_resize(BAND *A,
                 int new_lb, int new_ub, int new_n)
IVEC  *iv_resize(IVEC *iv, int new_dim)
MAT   *m_resize (MAT *A, int new_m, int new_n)
PERM  *px_resize(PERM *px, int new_size)
VEC   *v_resize (VEC *x, int new_dim)
int   *iv_resize_vars(unsigned new_dim,
                      IVEC **x1, IVEC **x2, ..., NULL)
int   *m_resize_vars (unsigned new_m, unsigned new_n,
                      MAT **A1, MAT **A2, ..., NULL)
int   *px_resize_vars(unsigned new_size,
                      PERM **px1, PERM **px2, ..., NULL)
int   *v_resize_vars (unsigned new_dim,
                      VEC **x1, VEC **x2, ..., NULL)
#include "zmatrix.h"
ZMAT  *zm_resize(ZMAT *A, int new_m, int new_n)
ZVEC  *zv_resize(ZVEC *x, int new_dim)
int   *zm_resize_vars(unsigned new_m, unsigned new_n,
                      ZMAT **A1, ZMAT **A2, ..., NULL)
int   *zv_resize_vars(unsigned new_dim,
                      ZVEC **x1, ZVEC **x2, ..., NULL)

DESCRIPTION

Each of these routines sets the (apparent) size of data structure to be identical to that obtained by using .._get(new_...). Thus the VEC * returned by \newlinev_resize(x,new_dim) has x->dim equal to new_dim. The MAT * returned by \hfill\breakm_resize(A,new_m,new_n) is a new_m${}\times{}$new_n matrix. The following rules hold for all of the above functions except for px_resize(). Whenever there is overlap between the object passed and the re-sized data structure, the entries of the new data structure are identical, and elsewhere the entries are zero. So if A is a $5\times 2$ matrix and new_A = m_resize(A,2,5), then new_A->me[1][0] is identical to the old A->me[1][0]. However, new_A->me[1][3] is zero. For px_resize() the rules are somewhat different because permutations do not remain permutations under such arbitrary operations. Instead, if the size is reduced, then the returned permutation is an identity permutation. If size is increased, then new_px->pe[i] == i for i greater than or equal to the old size. Allocation or reallocation and copying of data structure entries is avoided if possible (except, to some extent, in m_resize()). There is a ``high-water mark'' field contained within each data structure; for the VEC and IVEC data structures it is max_dim, which contains the actual amount of memory that has been allocated (at some time) for this data structure. Thus {\bf resizing does not deallocate memory}! To actually free up memory, use one of the .._free() routines or the .._FREE() macros. You should not rely on the values of entries outside the apparent size of the data structures but inside the maximum allocated area. These areas may be zeroed or overwritten, especially by the m_resize() routine. The .._resize_vars() routines resize a NULL-terminated list of pointers to variables, all of the same type. The new sizes of the all variables in the list are the same. Calling

.._resize_vars([m,]n,&x1,&x2,...,&xN,NULL)
is equivalent to
x1 = .._resize(x1,[m,]n);
x2 = .._resize(x2,[m,]n);
  ......
xN = .._resize(xN,[m,]n);
(Note that ``[m,]'' indicates that ``m,'' might or might not be present, depending on whether the data structure involved is a matrix or not.) The returned value of the .._resize_vars() routines is the number of objects resized.

EXAMPLE

/* an alternative to workspace arrays */
... my_function(...)
{
    static VEC *x = VNULL;
      ......
    x = v_resize(x,new_size);
    MEM_STAT_REG(x,TYPE_VEC);
      ......
    v_copy(..., x);
      ......
}

BUGS

Note the above comment: {\bf resizing does not deallocate memory}! To free up the actual memory allocated you will need to use the .._FREE() macros or the .._free() function calls.

SEE ALSO: .._get() routines; MEM_STAT_REG(). \sourcefile{memory.c, zmemory.c, bdfactor.c{\rm\ and }ivecop.c}