#### 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 section 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`. (See section Extracting Vector 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.