Release calc version 2.10.2t30

help/mat

@@ -0,0 +1,102 @@
+Using matrices
+
+    Matrices can have from 1 to 4 dimensions, and are indexed by a
+    normal-sized integer.  The lower and upper bounds of a matrix can
+    be specified at runtime.  The elements of a matrix are defaulted
+    to zeroes, but can be assigned to be of any type.  Thus matrices
+    can hold complex numbers, strings, objects, etc.  Matrices are
+    stored in memory as an array so that random access to the elements
+    is easy.
+
+    Matrices are normally indexed using square brackets.  If the matrix
+    is multi-dimensional, then an element can be indexed either by
+    using multiple pairs of square brackets (as in C), or else by
+    separating the indexes by commas.  Thus the following two statements
+    reference the same matrix element:
+
+	    x = name[3][5];
+	    x = name[3,5];
+
+    The double-square bracket operator can be used on any matrix to
+    make references to the elements easy and efficient.  This operator
+    bypasses the normal indexing mechanism, and treats the array as if
+    it was one-dimensional and with a lower bound of zero.  In this
+    indexing mode, elements correspond to the normal indexing mode where
+    the rightmost index increases most frequently.  For example, when
+    using double-square bracket indexing on a two-dimensional matrix,
+    increasing indexes will reference the matrix elements left to right,
+    row by row.  Thus in the following example, 'x' and 'y' are copied
+    from the same matrix element:
+
+	    mat m[1:2, 1:3];
+	    x = m[2,1];
+	    y = m[[3]];
+
+    There are functions which return information about a matrix.
+    The 'size' functions returns the total number of elements.
+    The 'matdim', 'matmin', and 'matmax' functions return the number
+    of dimensions of a matrix, and the lower and upper index bounds
+    for a dimension of a matrix.  For square matrices, the 'det'
+    function calculates the determinant of the matrix.
+
+    Some functions return matrices as their results.  These	functions
+    do not affect the original matrix argument, but instead return
+    new matrices.  For example, the 'mattrans' function returns the
+    transpose of a matrix, and 'inverse' returns the inverse of a
+    matrix.  So to invert a matrix called 'x', you could use:
+
+	    x = inverse(x);
+
+    The 'matfill' function fills all elements of a matrix with the
+    specified value, and optionally fills the diagonal elements of a
+    square matrix with a different value.  For example:
+
+	    matfill(x,1);
+
+    will fill any matrix with ones, and:
+
+	    matfill(x, 0, 1);
+
+    will create an identity matrix out of any square matrix.  Note that
+    unlike most matrix functions, this function does not return a matrix
+    value, but manipulates the matrix argument itself.
+
+    Matrices can be multiplied by numbers, which multiplies each element
+    by the number.  Matrices can also be negated, conjugated, shifted,
+    rounded, truncated, fractioned, and modulo'ed.  Each of these
+    operations is applied to each element.
+
+    Matrices can be added or multiplied together if the operation is
+    legal.  Note that even if the dimensions of matrices are compatible,
+    operations can still fail because of mismatched lower bounds.  The
+    lower bounds of two matrices must either match, or else one of them
+    must have a lower bound of zero.  Thus the following code:
+
+	    mat x[3:3];
+	    mat y[4:4];
+	    z = x + y;
+
+    fails because the calculator does not have a way of knowing what
+    the bounds should be on the resulting matrix.  If the bounds match,
+    then the resulting matrix has the same bounds.  If exactly one of
+    the lower bounds is zero, then the resulting matrix will have the
+    nonzero lower bounds.  Thus means that the bounds of a matrix are
+    preserved when operated on by matrices with lower bounds of zero.
+    For example:
+
+	    mat x[3:7];
+	    mat y[5];
+	    z = x + y;
+
+    will succeed and assign the variable 'z' a matrix whose
+    bounds are 3-7.
+
+    Vectors are matrices of only a single dimension.  The 'dp' and 'cp'
+    functions calculate the dot product and cross product of a vector
+    (cross product is only defined for vectors of size 3).
+
+    Matrices can be searched for particular values by using the 'search'
+    and 'rsearch' functions.  They return the element number of the
+    found value (zero based), or null if the value does not exist in the
+    matrix.  Using the element number in double-bracket indexing will
+    then refer to the found element.