Next: Symbolic Lisp Functions, Previous: Computational Lisp Functions, Up: Internals

##### 18.5.7.6 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 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 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.