create and initialise objects

SYNOPSIS

#include "matrix.h"
BAND   *bd_get(int lb, int ub, int n)
IVEC   *iv_get(unsigned dim)
MAT    * m_get(unsigned m, unsigned n)
PERM   *px_get(unsigned size)
VEC    * v_get(unsigned dim)
int    *iv_get_vars(unsigned dim,
                    IVEC **x1, IVEC **x2, ..., NULL)
int    * m_get_vars(unsigned m, unsigned n,
                    MAT **A1, MAT **A2, ..., NULL)
int    *px_get_vars(unsigned size,
                    PERM **px1, PERM **px2, ..., NULL)
int    * v_get_vars(unsigned dim,
                    VEC **x1, VEC **x2, ..., NULL)
#include "zmatrix.h"
ZMAT   *zm_get(unsigned m, unsigned n)
ZVEC   *zv_get(unsigned dim)
int    *zm_get_vars(unsigned m, unsigned n,
                    ZMAT **A1, ZMAT **A2, ..., NULL)
int    *zv_get_vars(unsigned dim,
                    ZVEC **x1, ZVEC **x2, ..., NULL)

DESCRIPTION

All these routines create and initialise data structures for the associated type of objects. Any extra memory needed is obtained from malloc() and its related routines. Also note that zero relative\/ indexing is used; that is, the vector x returned by x = v_get(10) can have indexes x->ve[i] for i equal to 0, 1, 2,\dots, 9, not\/ 1, 2, \dots, 9, 10. This also applies for both the rows and columns of a matrix. The bd_get(lb,ub,n) routine creates a band matrix of size $n\times n$ with a lower bandwidth of lb and an upper banwidth of ub. The iv_get(dim) routine creates an integer vector of dimension dim. Its entries are initialised to be zero. The m_get(m, n) routine creates a matrix of size m${}\times{}$n. That is, it has m rows and n columns. The matrix elements are all initialised to being zero. The px_get(size) routine creates and returns a permutation of size size. Its entries are initialised to being those of an identity permutation. Consistent with C's array index conventions, a permutation of the given size is a permutation on the set \{0,1,\dots,size-1\}. The v_get(dim) routine creates and returns a vector of dimension dim. Its entries are all initialised to zero. The .._get_vars() routines allocate and initialise a NULL-terminated list of pointers to variables, all of the same type. All of the variables are initialised to objects of the same size. Calling

.._get_vars([m,]n,&x1,&x2,...,&xN,NULL)
is equivalent to
x1 = .._get([m,]n);
x2 = .._get([m,]n);
  ......
xN = .._get([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 .._get_vars() routines is the number of objects created.

EXAMPLE

MAT  *A;
  ......
/* allocate 10 x 15 matrix */
A = m_get(10,15);

SEE ALSO: .._free(), .._FREE(), and .._resize().

BUGS

As dynamic memory allocation is used, and it is not possible to build garbage collection into C, memory can be lost. It is the programmer's responsibility to free allocated memory when it is no longer needed.

SOURCE FILE: memory.c, zmemory.c, bdfactor.c