17.6.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 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.