Vector Functions
................

The functions described here perform various operations on vectors and
matrices.

 -- Function: math-concat X Y
     Do a vector concatenation; this operation is written `X | Y' in a
     symbolic formula.  See Building Vectors.

 -- Function: vec-length V
     Return the length of vector V.  If V is not a vector, the result
     is zero.  If V is a matrix, this returns the number of rows in
     the matrix.

 -- Function: mat-dimens M
     Determine the dimensions of vector or matrix M.  If M is not a
     vector, the result is an empty list.  If M is a plain vector but
     not a matrix, the result is a one-element list containing the
     length of the vector.  If M is a matrix with R rows and C
     columns, the result is the list `(R C)'.  Higher-order tensors
     produce lists of more than two dimensions.  Note that the object
     `[[1, 2, 3], [4, 5]]' is a vector of vectors not all the same
     size, and is treated by this and other Calc routines as a plain
     vector of two elements.

 -- Function: dimension-error
     Abort the current function with a message of "Dimension error."
     The Calculator will leave the function being evaluated in
     symbolic form; this is really just a special case of
     `reject-arg'.

 -- Function: build-vector ARGS
     Return a Calc vector with the zero-or-more ARGS as elements.  For
     example, `(build-vector 1 2 3)' returns the Calc vector `[1, 2,
     3]', stored internally as the list `(vec 1 2 3)'.

 -- Function: make-vec OBJ DIMS
     Return a Calc vector or matrix all of whose elements are equal to
     OBJ.  For example, `(make-vec 27 3 4)' returns a 3x4 matrix
     filled with 27's.

 -- Function: row-matrix V
     If V is a plain vector, convert it into a row matrix, i.e., a
     matrix whose single row is V.  If V is already a matrix, leave it
     alone.

 -- Function: col-matrix V
     If V is a plain vector, convert it into a column matrix, i.e., a
     matrix with each element of V as a separate row.  If V is already
     a matrix, leave it alone.

 -- Function: map-vec F V
     Map the Lisp function F over the Calc vector V.  For example,
     `(map-vec 'math-floor v)' returns a vector of the floored
     components of vector V.

 -- Function: map-vec-2 F A B
     Map the Lisp function F over the two vectors A and B.  If A and B
     are vectors of equal length, the result is a vector of the
     results of calling `(F AI BI)' for each pair of elements AI and
     BI.  If either A or B is a scalar, it is matched with each value
     of the other vector.  For example, `(map-vec-2 'math-add v 1)'
     returns the vector V with each element increased by one.  Note
     that using `'+' would not work here, since `defmath' does not
     expand function names everywhere, just where they are in the
     function position of a Lisp expression.

 -- Function: reduce-vec F V
     Reduce the function F over the vector V.  For example, if V is
     `[10, 20, 30, 40]', this calls `(f (f (f 10 20) 30) 40)'.  If V
     is a matrix, this reduces over the rows of V.

 -- Function: reduce-cols F M
     Reduce the function F over the columns of matrix M.  For example,
     if M is `[[1, 2], [3, 4], [5, 6]]', the result is a vector of the
     two elements `(f (f 1 3) 5)' and `(f (f 2 4) 6)'.

 -- Function: mat-row M N
     Return the Nth row of matrix M.  This is equivalent to `(elt m
     n)'.  For a slower but safer version, use `mrow'.  (*Note
     Extracting Elements::.)

 -- Function: mat-col M N
     Return the Nth column of matrix M, in the form of a vector.  The
     arguments are not checked for correctness.

 -- Function: mat-less-row M N
     Return a copy of matrix M with its Nth row deleted.  The number N
     must be in range from 1 to the number of rows in M.

 -- Function: mat-less-col M N
     Return a copy of matrix M with its Nth column deleted.

 -- Function: transpose M
     Return the transpose of matrix M.

 -- Function: flatten-vector V
     Flatten nested vector V into a vector of scalars.  For example,
     if V is `[[1, 2, 3], [4, 5]]' the result is `[1, 2, 3, 4, 5]'.

 -- Function: copy-matrix M
     If M is a matrix, return a copy of M.  This maps `copy-sequence'
     over the rows of M; in Lisp terms, each element of the result
     matrix will be `eq' to the corresponding element of M, but none
     of the `cons' cells that make up the structure of the matrix will
     be `eq'.  If M is a plain vector, this is the same as
     `copy-sequence'.

 -- Function: swap-rows M R1 R2
     Exchange rows R1 and R2 of matrix M in-place.  In other words,
     unlike most of the other functions described here, this function
     changes M itself rather than building up a new result matrix.
     The return value is M, i.e., `(eq (swap-rows m 1 2) m)' is true,
     with the side effect of exchanging the first two rows of M.