Mercurial > octave-nkf
changeset 3369:f37ca3017116
[project @ 1999-11-21 16:26:02 by jwe]
line wrap: on
line diff
--- a/doc/interpreter/matrix.txi Sat Nov 20 17:23:01 1999 +0000 +++ b/doc/interpreter/matrix.txi Sun Nov 21 16:26:08 1999 +0000 @@ -27,34 +27,9 @@ The @code{find} function is also useful in determining which elements of a matrix meet a specified condition. -@deftypefn {Built-in Function} {} any (@var{x}) -For a vector argument, return 1 if any element of the vector is -nonzero. - -For a matrix argument, return a row vector of ones and -zeros with each element indicating whether any of the elements of the -corresponding column of the matrix are nonzero. For example, +@DOCSTRING(any) -@example -@group -any (eye (2, 4)) - @result{} [ 1, 1, 0, 0 ] -@end group -@end example - -To see if any of the elements of a matrix are nonzero, you can use a -statement like - -@example -any (any (a)) -@end example -@end deftypefn - -@deftypefn {Built-in Function} {} all (@var{x}) -The function @code{all} behaves like the function @code{any}, except -that it returns true only if all the elements of a vector, or all the -elements in a column of a matrix, are nonzero. -@end deftypefn +@DOCSTRING(all) Since the comparison operators (@pxref{Comparison Ops}) return matrices of ones and zeros, it is easy to test a matrix for many things, not just @@ -75,250 +50,32 @@ @code{while} statements) Octave treats the test as if you had typed @code{all (all (condition))}. -@deftypefn {Function File} {[@var{err}, @var{y1}, ...] =} common_size (@var{x1}, ...) -Determine if all input arguments are either scalar or of common -size. If so, @var{err} is zero, and @var{yi} is a matrix of the -common size with all entries equal to @var{xi} if this is a scalar or -@var{xi} otherwise. If the inputs cannot be brought to a common size, -errorcode is 1, and @var{yi} is @var{xi}. For example, - -@example -@group -[errorcode, a, b] = common_size ([1 2; 3 4], 5) - @result{} errorcode = 0 - @result{} a = [ 1, 2; 3, 4 ] - @result{} b = [ 5, 5; 5, 5 ] -@end group -@end example - -@noindent -This is useful for implementing functions where arguments can either -be scalars or of common size. -@end deftypefn +@DOCSTRING(common_size) -@deftypefn {Function File} {} diff (@var{x}, @var{k}) -If @var{x} is a vector of length @var{n}, @code{diff (@var{x})} is the -vector of first differences -@iftex -@tex - $x_2 - x_1, \ldots{}, x_n - x_{n-1}$. -@end tex -@end iftex -@ifinfo - @var{x}(2) - @var{x}(1), @dots{}, @var{x}(n) - @var{x}(n-1). -@end ifinfo - -If @var{x} is a matrix, @code{diff (@var{x})} is the matrix of column -differences. +@DOCSTRING(diff) -The second argument is optional. If supplied, @code{diff (@var{x}, -@var{k})}, where @var{k} is a nonnegative integer, returns the -@var{k}-th differences. -@end deftypefn - -@deftypefn {Mapping Function} {} isinf (@var{x}) -Return 1 for elements of @var{x} that are infinite and zero -otherwise. For example, - -@example -@group -isinf ([13, Inf, NaN]) - @result{} [ 0, 1, 0 ] -@end group -@end example -@end deftypefn - -@deftypefn {Mapping Function} {} isnan (@var{x}) -Return 1 for elements of @var{x} that are NaN values and zero -otherwise. For example, +@DOCSTRING(isinf) -@example -@group -isnan ([13, Inf, NaN]) - @result{} [ 0, 0, 1 ] -@end group -@end example -@end deftypefn - -@deftypefn {Mapping Function} {} finite (@var{x}) -Return 1 for elements of @var{x} that are NaN values and zero -otherwise. For example, - -@example -@group -finite ([13, Inf, NaN]) - @result{} [ 1, 0, 0 ] -@end group -@end example -@end deftypefn - -@deftypefn {Loadable Function} {} find (@var{x}) -Return a vector of indices of nonzero elements of a matrix. To obtain a -single index for each matrix element, Octave pretends that the columns -of a matrix form one long vector (like Fortran arrays are stored). For -example, +@DOCSTRING(isnan) -@example -@group -find (eye (2)) - @result{} [ 1; 4 ] -@end group -@end example - -If two outputs are requested, @code{find} returns the row and column -indices of nonzero elements of a matrix. For example, +@DOCSTRING(finite) -@example -@group -[i, j] = find (2 * eye (2)) - @result{} i = [ 1; 2 ] - @result{} j = [ 1; 2 ] -@end group -@end example - -If three outputs are requested, @code{find} also returns a vector -containing the nonzero values. For example, - -@example -@group -[i, j, v] = find (3 * eye (2)) - @result{} i = [ 1; 2 ] - @result{} j = [ 1; 2 ] - @result{} v = [ 3; 3 ] -@end group -@end example -@end deftypefn +@DOCSTRING(find) @node Rearranging Matrices, Special Utility Matrices, Finding Elements and Checking Conditions, Matrix Manipulation @section Rearranging Matrices -@deftypefn {Function File} {} fliplr (@var{x}) -Return a copy of @var{x} with the order of the columns reversed. For -example, - -@example -@group -fliplr ([1, 2; 3, 4]) - @result{} 2 1 - 4 3 -@end group -@end example -@end deftypefn - -@deftypefn {Function File} {} flipud (@var{x}) -Return a copy of @var{x} with the order of the rows reversed. For -example, - -@example -@group -flipud ([1, 2; 3, 4]) - @result{} 3 4 - 1 2 -@end group -@end example -@end deftypefn +@DOCSTRING(fliplr) -@deftypefn {Function File} {} rot90 (@var{x}, @var{n}) -Return a copy of @var{x} with the elements rotated counterclockwise in -90-degree increments. The second argument is optional, and specifies -how many 90-degree rotations are to be applied (the default value is 1). -Negative values of @var{n} rotate the matrix in a clockwise direction. -For example, - -@example -@group -rot90 ([1, 2; 3, 4], -1) - @result{} 3 1 - 4 2 -@end group -@end example - -@noindent -rotates the given matrix clockwise by 90 degrees. The following are all -equivalent statements: +@DOCSTRING(flipud) -@example -@group -rot90 ([1, 2; 3, 4], -1) -@equiv{} -rot90 ([1, 2; 3, 4], 3) -@equiv{} -rot90 ([1, 2; 3, 4], 7) -@end group -@end example -@end deftypefn - -@deftypefn {Function File} {} reshape (@var{a}, @var{m}, @var{n}) -Return a matrix with @var{m} rows and @var{n} columns whose elements are -taken from the matrix @var{a}. To decide how to order the elements, -Octave pretends that the elements of a matrix are stored in column-major -order (like Fortran arrays are stored). - -For example, +@DOCSTRING(rot90) -@example -@group -reshape ([1, 2, 3, 4], 2, 2) - @result{} 1 3 - 2 4 -@end group -@end example - -If the variable @code{do_fortran_indexing} is nonzero, the -@code{reshape} function is equivalent to - -@example -@group -retval = zeros (m, n); -retval (:) = a; -@end group -@end example - -@noindent -but it is somewhat less cryptic to use @code{reshape} instead of the -colon operator. Note that the total number of elements in the original -matrix must match the total number of elements in the new matrix. -@end deftypefn - -@deftypefn {Function File} {} shift (@var{x}, @var{b}) -If @var{x} is a vector, perform a circular shift of length @var{b} of -the elements of @var{x}. - -If @var{x} is a matrix, do the same for each column of @var{x}. -@end deftypefn +@DOCSTRING(reshape) -@deftypefn {Loadable Function} {[@var{s}, @var{i}] =} sort (@var{x}) -Return a copy of @var{x} with the elements elements arranged in -increasing order. For matrices, @code{sort} orders the elements in each -column. - -For example, - -@example -@group -sort ([1, 2; 2, 3; 3, 1]) - @result{} 1 1 - 2 2 - 3 3 -@end group -@end example +@DOCSTRING(shift) -The @code{sort} function may also be used to produce a matrix -containing the original row indices of the elements in the sorted -matrix. For example, - -@example -@group -[s, i] = sort ([1, 2; 2, 3; 3, 1]) - @result{} s = 1 1 - 2 2 - 3 3 - @result{} i = 1 3 - 2 1 - 3 2 -@end group -@end example -@end deftypefn +@DOCSTRING(sort) Since the @code{sort} function does not allow sort keys to be specified, it can't be used to order the rows of a matrix according to the values @@ -341,162 +98,24 @@ @end group @end example -@deftypefn {Function File} {} tril (@var{a}, @var{k}) -@deftypefnx {Function File} {} triu (@var{a}, @var{k}) -Return a new matrix formed by extracting extract the lower (@code{tril}) -or upper (@code{triu}) triangular part of the matrix @var{a}, and -setting all other elements to zero. The second argument is optional, -and specifies how many diagonals above or below the main diagonal should -also be set to zero. - -The default value of @var{k} is zero, so that @code{triu} and -@code{tril} normally include the main diagonal as part of the result -matrix. - -If the value of @var{k} is negative, additional elements above (for -@code{tril}) or below (for @code{triu}) the main diagonal are also -selected. - -The absolute value of @var{k} must not be greater than the number of -sub- or super-diagonals. - -For example, +@DOCSTRING(tril) -@example -@group -tril (ones (3), -1) - @result{} 0 0 0 - 1 0 0 - 1 1 0 -@end group -@end example - -@noindent -and +@DOCSTRING(vec) -@example -@group -tril (ones (3), 1) - @result{} 1 1 0 - 1 1 1 - 1 1 1 -@end group -@end example -@end deftypefn - -@deftypefn {Function File} {} vec (@var{x}) -Return the vector obtained by stacking the columns of the matrix @var{x} -one above the other. -@end deftypefn - -@deftypefn {Function File} {} vech (@var{x}) -Return the vector obtained by eliminating all supradiagonal elements of -the square matrix @var{x} and stacking the result one column above the -other. -@end deftypefn +@DOCSTRING(vech) @node Special Utility Matrices, Famous Matrices, Rearranging Matrices, Matrix Manipulation @section Special Utility Matrices -@deftypefn {Built-in Function} {} eye (@var{x}) -@deftypefnx {Built-in Function} {} eye (@var{n}, @var{m}) -Return an identity matrix. If invoked with a single scalar argument, -@code{eye} returns a square matrix with the dimension specified. If you -supply two scalar arguments, @code{eye} takes them to be the number of -rows and columns. If given a vector with two elements, @code{eye} uses -the values of the elements as the number of rows and columns, -respectively. For example, - -@example -@group -eye (3) - @result{} 1 0 0 - 0 1 0 - 0 0 1 -@end group -@end example - -The following expressions all produce the same result: +@DOCSTRING(eye) -@example -@group -eye (2) -@equiv{} -eye (2, 2) -@equiv{} -eye (size ([1, 2; 3, 4]) -@end group -@end example - -For compatibility with @sc{Matlab}, calling @code{eye} with no arguments -is equivalent to calling it with an argument of 1. -@end deftypefn - -@deftypefn {Built-in Function} {} ones (@var{x}) -@deftypefnx {Built-in Function} {} ones (@var{n}, @var{m}) -Return a matrix whose elements are all 1. The arguments are handled -the same as the arguments for @code{eye}. - -If you need to create a matrix whose values are all the same, you should -use an expression like - -@example -val_matrix = val * ones (n, m) -@end example -@end deftypefn +@DOCSTRING(ones) -@deftypefn {Built-in Function} {} zeros (@var{x}) -@deftypefnx {Built-in Function} {} zeros (@var{n}, @var{m}) -Return a matrix whose elements are all 0. The arguments are handled -the same as the arguments for @code{eye}. -@end deftypefn - -@deftypefn {Loadable Function} {} rand (@var{x}) -@deftypefnx {Loadable Function} {} rand (@var{n}, @var{m}) -@deftypefnx {Loadable Function} {} rand (@code{"seed"}, @var{x}) -Return a matrix with random elements uniformly distributed on the -interval (0, 1). The arguments are handled the same as the arguments -for @code{eye}. In -addition, you can set the seed for the random number generator using the -form - -@example -rand ("seed", @var{x}) -@end example - -@noindent -where @var{x} is a scalar value. If called as - -@example -rand ("seed") -@end example +@DOCSTRING(zeros) -@noindent -@code{rand} returns the current value of the seed. -@end deftypefn - -@deftypefn {Loadable Function} {} randn (@var{x}) -@deftypefnx {Loadable Function} {} randn (@var{n}, @var{m}) -@deftypefnx {Loadable Function} {} randn (@code{"seed"}, @var{x}) -Return a matrix with normally distributed random elements. The -arguments are handled the same as the arguments for @code{eye}. In -addition, you can set the seed for the random number generator using the -form +@DOCSTRING(rand) -@example -randn ("seed", @var{x}) -@end example - -@noindent -where @var{x} is a scalar value. If called as - -@example -randn ("seed") -@end example - -@noindent -@code{randn} returns the current value of the seed. -@end deftypefn +@DOCSTRING(randn) The @code{rand} and @code{randn} functions use separate generators. This ensures that @@ -544,23 +163,7 @@ Biomathematics at The University of Texas, M.D. Anderson Cancer Center, Houston, TX 77030. -@deftypefn {Built-in Function} {} diag (@var{v}, @var{k}) -Return a diagonal matrix with vector @var{v} on diagonal @var{k}. The -second argument is optional. If it is positive, the vector is placed on -the @var{k}-th super-diagonal. If it is negative, it is placed on the -@var{-k}-th sub-diagonal. The default value of @var{k} is 0, and the -vector is placed on the main diagonal. For example, - -@example -@group -diag ([1, 2, 3], 1) - @result{} 0 1 0 0 - 0 0 2 0 - 0 0 0 3 - 0 0 0 0 -@end group -@end example -@end deftypefn +@DOCSTRING(diag) @c XXX FIXME XXX -- is this really worth documenting? @c @@ -580,213 +183,25 @@ create vectors with evenly or logarithmically spaced elements. @xref{Ranges}. -@deftypefn {Function File} {} linspace (@var{base}, @var{limit}, @var{n}) -Return a row vector with @var{n} linearly spaced elements between -@var{base} and @var{limit}. The number of elements, @var{n}, must be -greater than 1. The @var{base} and @var{limit} are always included in -the range. If @var{base} is greater than @var{limit}, the elements are -stored in decreasing order. If the number of points is not specified, a -value of 100 is used. - -The @code{linspace} function always returns a row vector, regardless of -the value of @code{prefer_column_vectors}. -@end deftypefn - -@deftypefn {Function File} {} logspace (@var{base}, @var{limit}, @var{n}) -Similar to @code{linspace} except that the values are logarithmically -spaced from -@iftex -@tex -$10^{base}$ to $10^{limit}$. -@end tex -@end iftex -@ifinfo -10^base to 10^limit. -@end ifinfo +@DOCSTRING(linspace) -If @var{limit} is equal to -@iftex -@tex -$\pi$, -@end tex -@end iftex -@ifinfo -pi, -@end ifinfo -the points are between -@iftex -@tex -$10^{base}$ and $\pi$, -@end tex -@end iftex -@ifinfo -10^base and pi, -@end ifinfo -@emph{not} -@iftex -@tex -$10^{base}$ and $10^{\pi}$, -@end tex -@end iftex -@ifinfo -10^base and 10^pi, -@end ifinfo -in order to be compatible with the corresponding @sc{Matlab} function. -@end deftypefn +@DOCSTRING(logspace) -@defvr {Built-in Variable} treat_neg_dim_as_zero -If the value of @code{treat_neg_dim_as_zero} is nonzero, expressions -like - -@example -eye (-1) -@end example - -@noindent -produce an empty matrix (i.e., row and column dimensions are zero). -Otherwise, an error message is printed and control is returned to the -top level. The default value is 0. -@end defvr +@DOCSTRING(treat_neg_dim_as_zero) @node Famous Matrices, , Special Utility Matrices, Matrix Manipulation @section Famous Matrices The following functions return famous matrix forms. -@deftypefn {Function File} {} hankel (@var{c}, @var{r}) -Return the Hankel matrix constructed given the first column @var{c}, and -(optionally) the last row @var{r}. If the last element of @var{c} is -not the same as the first element of @var{r}, the last element of -@var{c} is used. If the second argument is omitted, the last row is -taken to be the same as the first column. - -A Hankel matrix formed from an m-vector @var{c}, and an n-vector -@var{r}, has the elements -@iftex -@tex -$$ -H (i, j) = \cases{c_{i+j-1},&$i+j-1\le m$;\cr r_{i+j-m},&otherwise.\cr} -$$ -@end tex -@end iftex -@ifinfo - -@example -@group -H (i, j) = c (i+j-1), i+j-1 <= m; -H (i, j) = r (i+j-m), otherwise -@end group -@end example -@end ifinfo -@end deftypefn +@DOCSTRING(hankel) -@deftypefn {Function File} {} hilb (@var{n}) -Return the Hilbert matrix of order @var{n}. The -@iftex -@tex -$i,\,j$ -@end tex -@end iftex -@ifinfo -i, j -@end ifinfo -element of a Hilbert matrix is defined as -@iftex -@tex -$$ -H (i, j) = {1 \over (i + j - 1)} -$$ -@end tex -@end iftex -@ifinfo +@DOCSTRING(hilb) -@example -H (i, j) = 1 / (i + j - 1) -@end example -@end ifinfo -@end deftypefn - -@deftypefn {Function File} {} invhilb (@var{n}) -Return the inverse of a Hilbert matrix of order @var{n}. This is exact. -Compare with the numerical calculation of @code{inverse (hilb (n))}, -which suffers from the ill-conditioning of the Hilbert matrix, and the -finite precision of your computer's floating point arithmetic. -@end deftypefn +@DOCSTRING(invhilb) -@deftypefn {Function File} {} sylvester_matrix (@var{k}) -Return the Sylvester matrix of order -@iftex -@tex -$n = 2^k$. -@end tex -@end iftex -@ifinfo -n = 2^k. -@end ifinfo -@end deftypefn - -@deftypefn {Function File} {} toeplitz (@var{c}, @var{r}) -Return the Toeplitz matrix constructed given the first column @var{c}, -and (optionally) the first row @var{r}. If the first element of @var{c} -is not the same as the first element of @var{r}, the first element of -@var{c} is used. If the second argument is omitted, the first row is -taken to be the same as the first column. - -A square Toeplitz matrix has the form -@iftex -@tex -$$ -\left[\matrix{c_0 & r_1 & r_2 & \ldots & r_n\cr - c_1 & c_0 & r_1 & & c_{n-1}\cr - c_2 & c_1 & c_0 & & c_{n-2}\cr - \vdots & & & & \vdots\cr - c_n & c_{n-1} & c_{n-2} & \ldots & c_0}\right]. -$$ -@end tex -@end iftex -@ifinfo +@DOCSTRING(sylvester_matrix) -@example -@group -c(0) r(1) r(2) ... r(n) -c(1) c(0) r(1) r(n-1) -c(2) c(1) c(0) r(n-2) - . . - . . - . . - -c(n) c(n-1) c(n-2) ... c(0) -@end group -@end example -@end ifinfo -@end deftypefn - -@deftypefn {Function File} {} vander (@var{c}) -Return the Vandermonde matrix whose next to last column is @var{c}. +@DOCSTRING(toeplitz) -A Vandermonde matrix has the form -@iftex -@tex -$$ -\left[\matrix{c_0^n & \ldots & c_0^2 & c_0 & 1\cr - c_1^n & \ldots & c_1^2 & c_1 & 1\cr - \vdots & & \vdots & \vdots & \vdots\cr - c_n^n & \ldots & c_n^2 & c_n & 1}\right]. -$$ -@end tex -@end iftex -@ifinfo - -@example -@group -c(0)^n ... c(0)^2 c(0) 1 -c(1)^n ... c(1)^2 c(1) 1 - . . . . - . . . . - . . . . - -c(n)^n ... c(n)^2 c(n) 1 -@end group -@end example -@end ifinfo -@end deftypefn +@DOCSTRING(vander)
--- a/scripts/ChangeLog Sat Nov 20 17:23:01 1999 +0000 +++ b/scripts/ChangeLog Sun Nov 21 16:26:08 1999 +0000 @@ -1,3 +1,24 @@ +1999-11-21 John W. Eaton <jwe@bevo.che.wisc.edu> + + * special-matrix/hankel.m: Texinfoize doc string. + * special-matrix/hilb.m: Ditto. + * special-matrix/invhilb.m: Ditto. + * special-matrix/sylvester_matrix.m: Ditto. + * special-matrix/toeplitz.m: Ditto. + * special-matrix/vander.m: Ditto. + * linear-algebra/vec.m: Ditto. + * linear-algebra/vech.m: Ditto. + * general/common_size.m: Ditto. + * general/diff.m: Ditto. + * general/fliplr.m: Ditto. + * general/flipud.m: Ditto. + * general/rot90.m: Ditto. + * general/reshape.m: Ditto. + * general/shift.m: Ditto. + * general/tril.m: Ditto. + * general/triu.m: Ditto. + * general/logspace.m: Ditto. + 1999-11-20 John W. Eaton <jwe@bevo.che.wisc.edu> * statistics/base/mean: Texinfoize doc string.
--- a/scripts/general/common_size.m Sat Nov 20 17:23:01 1999 +0000 +++ b/scripts/general/common_size.m Sun Nov 21 16:26:08 1999 +0000 @@ -14,24 +14,27 @@ ## along with this file. If not, write to the Free Software Foundation, ## 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. -## usage: [errorcode, y_1, ...] = common_size (x_1, ...) -## +## -*- texinfo -*- +## @deftypefn {Function File} {[@var{err}, @var{y1}, ...] =} common_size (@var{x1}, ...) ## Determine if all input arguments are either scalar or of common -## size. In this case, errorcode is zero, and y_i is a matrix of the -## common size with all entries equal to x_i if this is a scalar or -## x_i otherwise. -## -## If the inputs cannot be brought to a common size, errorcode is 1, and -## y_i is x_i. -## -## For example, -## -## [errorcode, a, b] = common_size ([1 2; 3 4], 5) -## -## returns errorcode = 0, a = [1 2, 3 4], b = [5 5; 5 5]. -## +## size. If so, @var{err} is zero, and @var{yi} is a matrix of the +## common size with all entries equal to @var{xi} if this is a scalar or +## @var{xi} otherwise. If the inputs cannot be brought to a common size, +## errorcode is 1, and @var{yi} is @var{xi}. For example, +## +## @example +## @group +## [errorcode, a, b] = common_size ([1 2; 3 4], 5) +## @result{} errorcode = 0 +## @result{} a = [ 1, 2; 3, 4 ] +## @result{} b = [ 5, 5; 5, 5 ] +## @end group +## @end example +## +## @noindent ## This is useful for implementing functions where arguments can either ## be scalars or of common size. +## @end deftypefn ## Author: KH <Kurt.Hornik@ci.tuwien.ac.at> ## Created: 15 October 1994
--- a/scripts/general/diff.m Sat Nov 20 17:23:01 1999 +0000 +++ b/scripts/general/diff.m Sun Nov 21 16:26:08 1999 +0000 @@ -14,14 +14,26 @@ ## along with this file. If not, write to the Free Software Foundation, ## 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. -## usage: diff (x [, k]) -## -## If x is a vector of length n, diff (x) is the vector of first -## differences x(2) - x(1), ..., x(n) - x(n-1). -## -## If x is a matrix, diff (x) is the matrix of column differences. -## diff (x, k), where k is a nonnegative integer, returns the k-th +## -*- texinfo -*- +## @deftypefn {Function File} {} diff (@var{x}, @var{k}) +## If @var{x} is a vector of length @var{n}, @code{diff (@var{x})} is the +## vector of first differences +## @iftex +## @tex +## $x_2 - x_1, \ldots{}, x_n - x_{n-1}$. +## @end tex +## @end iftex +## @ifinfo +## @var{x}(2) - @var{x}(1), @dots{}, @var{x}(n) - @var{x}(n-1). +## @end ifinfo +## +## If @var{x} is a matrix, @code{diff (@var{x})} is the matrix of column ## differences. +## +## The second argument is optional. If supplied, @code{diff (@var{x}, +## @var{k})}, where @var{k} is a nonnegative integer, returns the +## @var{k}-th differences. +## @end deftypefn ## Author: KH <Kurt.Hornik@ci.tuwien.ac.at> ## Created: 2 February 1995
--- a/scripts/general/fliplr.m Sat Nov 20 17:23:01 1999 +0000 +++ b/scripts/general/fliplr.m Sun Nov 21 16:26:08 1999 +0000 @@ -17,10 +17,20 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## usage: fliplr (x) -## -## Return x with the columns swapped. -## +## -*- texinfo -*- +## @deftypefn {Function File} {} fliplr (@var{x}) +## Return a copy of @var{x} with the order of the columns reversed. For +## example, +## +## @example +## @group +## fliplr ([1, 2; 3, 4]) +## @result{} 2 1 +## 4 3 +## @end group +## @end example +## @end deftypefn + ## See also: flipu, rot90 ## Author: jwe
--- a/scripts/general/flipud.m Sat Nov 20 17:23:01 1999 +0000 +++ b/scripts/general/flipud.m Sun Nov 21 16:26:08 1999 +0000 @@ -17,10 +17,20 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## usage: flipud (x) -## -## Return x with the rows swapped. -## +## -*- texinfo -*- +## @deftypefn {Function File} {} flipud (@var{x}) +## Return a copy of @var{x} with the order of the rows reversed. For +## example, +## +## @example +## @group +## flipud ([1, 2; 3, 4]) +## @result{} 3 4 +## 1 2 +## @end group +## @end example +## @end deftypefn + ## See also: fliplr, rot90 ## Author: jwe
--- a/scripts/general/logspace.m Sat Nov 20 17:23:01 1999 +0000 +++ b/scripts/general/logspace.m Sun Nov 21 16:26:08 1999 +0000 @@ -17,22 +17,49 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## usage: logspace (x1, x2, n) -## -## Return a vector of n logarithmically equally spaced points between -## 10^x1 and 10^x2 inclusive. -## -## If the final argument is omitted, n = 50 is assumed. -## -## All three arguments must be scalars. -## -## Note that if if x2 is pi, the points are between 10^x1 and pi, NOT -## 10^x1 and 10^pi. -## -## Yes, this is pretty stupid, because you could achieve the same -## result with logspace (x1, log10 (pi)), but Matlab does this, and -## claims that is useful for signal processing applications. -## +## -*- texinfo -*- +## @deftypefn {Function File} {} logspace (@var{base}, @var{limit}, @var{n}) +## Similar to @code{linspace} except that the values are logarithmically +## spaced from +## @iftex +## @tex +## $10^{base}$ to $10^{limit}$. +## @end tex +## @end iftex +## @ifinfo +## 10^base to 10^limit. +## @end ifinfo +## +## If @var{limit} is equal to +## @iftex +## @tex +## $\pi$, +## @end tex +## @end iftex +## @ifinfo +## pi, +## @end ifinfo +## the points are between +## @iftex +## @tex +## $10^{base}$ and $\pi$, +## @end tex +## @end iftex +## @ifinfo +## 10^base and pi, +## @end ifinfo +## @emph{not} +## @iftex +## @tex +## $10^{base}$ and $10^{\pi}$, +## @end tex +## @end iftex +## @ifinfo +## 10^base and 10^pi, +## @end ifinfo +## in order to be compatible with the corresponding @sc{Matlab} function. +## @end deftypefn + ## See also: linspace ## Author: jwe
--- a/scripts/general/reshape.m Sat Nov 20 17:23:01 1999 +0000 +++ b/scripts/general/reshape.m Sun Nov 21 16:26:08 1999 +0000 @@ -17,11 +17,39 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## usage: reshape (a, m, n) -## -## Form an m x n matrix from the elements of a (taken in Fortran's -## column major ordering). -## +## -*- texinfo -*- +## @deftypefn {Function File} {} reshape (@var{a}, @var{m}, @var{n}) +## Return a matrix with @var{m} rows and @var{n} columns whose elements are +## taken from the matrix @var{a}. To decide how to order the elements, +## Octave pretends that the elements of a matrix are stored in column-major +## order (like Fortran arrays are stored). +## +## For example, +## +## @example +## @group +## reshape ([1, 2, 3, 4], 2, 2) +## @result{} 1 3 +## 2 4 +## @end group +## @end example +## +## If the variable @code{do_fortran_indexing} is nonzero, the +## @code{reshape} function is equivalent to +## +## @example +## @group +## retval = zeros (m, n); +## retval (:) = a; +## @end group +## @end example +## +## @noindent +## but it is somewhat less cryptic to use @code{reshape} instead of the +## colon operator. Note that the total number of elements in the original +## matrix must match the total number of elements in the new matrix. +## @end deftypefn + ## See also: `:', do_fortran_indexing ## Author: jwe
--- a/scripts/general/rot90.m Sat Nov 20 17:23:01 1999 +0000 +++ b/scripts/general/rot90.m Sun Nov 21 16:26:08 1999 +0000 @@ -17,12 +17,37 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## usage: rot90 (x, k) -## -## Rotate the matrix x counterclockwise k*90 degrees. -## -## If the second argument is omitted, k is taken to be 1. -## +## -*- texinfo -*- +## @deftypefn {Function File} {} rot90 (@var{x}, @var{n}) +## Return a copy of @var{x} with the elements rotated counterclockwise in +## 90-degree increments. The second argument is optional, and specifies +## how many 90-degree rotations are to be applied (the default value is 1). +## Negative values of @var{n} rotate the matrix in a clockwise direction. +## For example, +## +## @example +## @group +## rot90 ([1, 2; 3, 4], -1) +## @result{} 3 1 +## 4 2 +## @end group +## @end example +## +## @noindent +## rotates the given matrix clockwise by 90 degrees. The following are all +## equivalent statements: +## +## @example +## @group +## rot90 ([1, 2; 3, 4], -1) +## @equiv{} +## rot90 ([1, 2; 3, 4], 3) +## @equiv{} +## rot90 ([1, 2; 3, 4], 7) +## @end group +## @end example +## @end deftypefn + ## See also: flipud, fliplr ## Author: jwe
--- a/scripts/general/shift.m Sat Nov 20 17:23:01 1999 +0000 +++ b/scripts/general/shift.m Sun Nov 21 16:26:08 1999 +0000 @@ -14,12 +14,13 @@ ## along with this file. If not, write to the Free Software Foundation, ## 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. -## usage: y = shift (x, b) -## -## If x is a vector, perform a circular shift of length b of the -## elements of x. -## -## If x is a matrix, do the same for each column of x. +## -*- texinfo -*- +## @deftypefn {Function File} {} shift (@var{x}, @var{b}) +## If @var{x} is a vector, perform a circular shift of length @var{b} of +## the elements of @var{x}. +## +## If @var{x} is a matrix, do the same for each column of @var{x}. +## @end deftypefn ## Author: AW <Andreas.Weingessel@ci.tuwien.ac.at> ## Created: 14 September 1994
--- a/scripts/general/tril.m Sat Nov 20 17:23:01 1999 +0000 +++ b/scripts/general/tril.m Sun Nov 21 16:26:08 1999 +0000 @@ -17,11 +17,50 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## usage: tril (x, k) -## -## Return the lower triangular part of x above the k-th diagonal. If -## the second argument is omitted, k = 0 is assumed. -## +## -*- texinfo -*- +## @deftypefn {Function File} {} tril (@var{a}, @var{k}) +## @deftypefnx {Function File} {} triu (@var{a}, @var{k}) +## Return a new matrix formed by extracting extract the lower (@code{tril}) +## or upper (@code{triu}) triangular part of the matrix @var{a}, and +## setting all other elements to zero. The second argument is optional, +## and specifies how many diagonals above or below the main diagonal should +## also be set to zero. +## +## The default value of @var{k} is zero, so that @code{triu} and +## @code{tril} normally include the main diagonal as part of the result +## matrix. +## +## If the value of @var{k} is negative, additional elements above (for +## @code{tril}) or below (for @code{triu}) the main diagonal are also +## selected. +## +## The absolute value of @var{k} must not be greater than the number of +## sub- or super-diagonals. +## +## For example, +## +## @example +## @group +## tril (ones (3), -1) +## @result{} 0 0 0 +## 1 0 0 +## 1 1 0 +## @end group +## @end example +## +## @noindent +## and +## +## @example +## @group +## tril (ones (3), 1) +## @result{} 1 1 0 +## 1 1 1 +## 1 1 1 +## @end group +## @end example +## @end deftypefn + ## See also: triu, diag ## Author: jwe
--- a/scripts/general/triu.m Sat Nov 20 17:23:01 1999 +0000 +++ b/scripts/general/triu.m Sun Nov 21 16:26:08 1999 +0000 @@ -17,12 +17,7 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## usage: triu (x, k) -## -## Return the upper triangular part of x above the k-th diagonal. If -## the second argument is omitted, k = 0 is assumed. -## -## See also: tril, diag +## See tril. ## Author: jwe
--- a/scripts/linear-algebra/vec.m Sat Nov 20 17:23:01 1999 +0000 +++ b/scripts/linear-algebra/vec.m Sun Nov 21 16:26:08 1999 +0000 @@ -14,11 +14,12 @@ ## along with this file. If not, write to the Free Software Foundation, ## 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. -## usage: vec (x) -## -## Returns vec (x), the vector obtained by stacking the columns of x +## -*- texinfo -*- +## @deftypefn {Function File} {} vec (@var{x}) +## Return the vector obtained by stacking the columns of the matrix @var{x} ## one above the other. -## +## @end deftypefn + ## See Magnus and Neudecker (1988), Matrix differential calculus with ## applications in statistics and econometrics.
--- a/scripts/linear-algebra/vech.m Sat Nov 20 17:23:01 1999 +0000 +++ b/scripts/linear-algebra/vech.m Sun Nov 21 16:26:08 1999 +0000 @@ -14,12 +14,13 @@ ## along with this file. If not, write to the Free Software Foundation, ## 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. -## usage: vech (x) -## -## For square x, returns the vector vech (x) which is obtained from x -## by eliminating all supradiagonal elements and stacking the result -## one column above the other. -## +## -*- texinfo -*- +## @deftypefn {Function File} {} vech (@var{x}) +## Return the vector obtained by eliminating all supradiagonal elements of +## the square matrix @var{x} and stacking the result one column above the +## other. +## @end deftypefn + ## See Magnus and Neudecker (1988), Matrix differential calculus with ## applications in statistics and econometrics.
--- a/scripts/special-matrix/hankel.m Sat Nov 20 17:23:01 1999 +0000 +++ b/scripts/special-matrix/hankel.m Sun Nov 21 16:26:08 1999 +0000 @@ -17,15 +17,34 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## usage: hankel (c, r) -## -## Return the Hankel matrix constructed given the first column -## c, and (optionally) the last row r. -## -## If the second argument is omitted, zeros are inserted below the main -## anti-diagonal. If the last element of c is not the same as the first -## element of r, the last element of c is used. -## +## -*- texinfo -*- +## @deftypefn {Function File} {} hankel (@var{c}, @var{r}) +## Return the Hankel matrix constructed given the first column @var{c}, and +## (optionally) the last row @var{r}. If the last element of @var{c} is +## not the same as the first element of @var{r}, the last element of +## @var{c} is used. If the second argument is omitted, the last row is +## taken to be the same as the first column. +## +## A Hankel matrix formed from an m-vector @var{c}, and an n-vector +## @var{r}, has the elements +## @iftex +## @tex +## $$ +## H (i, j) = \cases{c_{i+j-1},&$i+j-1\le m$;\cr r_{i+j-m},&otherwise.\cr} +## $$ +## @end tex +## @end iftex +## @ifinfo +## +## @example +## @group +## H (i, j) = c (i+j-1), i+j-1 <= m; +## H (i, j) = r (i+j-m), otherwise +## @end group +## @end example +## @end ifinfo +## @end deftypefn + ## See also: vander, sylvester_matrix, hilb, invhilb, toeplitz ## Author: jwe
--- a/scripts/special-matrix/hilb.m Sat Nov 20 17:23:01 1999 +0000 +++ b/scripts/special-matrix/hilb.m Sun Nov 21 16:26:08 1999 +0000 @@ -17,13 +17,33 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## usage: hilb (n) -## -## Return the Hilbert matrix of order n. The i, j element of a Hilbert -## matrix is defined as -## -## H (i, j) = 1 / (i + j - 1); -## +## -*- texinfo -*- +## @deftypefn {Function File} {} hilb (@var{n}) +## Return the Hilbert matrix of order @var{n}. The +## @iftex +## @tex +## $i,\,j$ +## @end tex +## @end iftex +## @ifinfo +## i, j +## @end ifinfo +## element of a Hilbert matrix is defined as +## @iftex +## @tex +## $$ +## H (i, j) = {1 \over (i + j - 1)} +## $$ +## @end tex +## @end iftex +## @ifinfo +## +## @example +## H (i, j) = 1 / (i + j - 1) +## @end example +## @end ifinfo +## @end deftypefn + ## See also: hankel, vander, sylvester_matrix, invhilb, toeplitz ## Author: jwe
--- a/scripts/special-matrix/invhilb.m Sat Nov 20 17:23:01 1999 +0000 +++ b/scripts/special-matrix/invhilb.m Sun Nov 21 16:26:08 1999 +0000 @@ -17,11 +17,14 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## usage: invhilb (n) -## -## Return the inverse of a Hilbert matrix of order n. This is slow but -## exact. Compare with inv (hilb (n)). -## +## -*- texinfo -*- +## @deftypefn {Function File} {} invhilb (@var{n}) +## Return the inverse of a Hilbert matrix of order @var{n}. This is exact. +## Compare with the numerical calculation of @code{inverse (hilb (n))}, +## which suffers from the ill-conditioning of the Hilbert matrix, and the +## finite precision of your computer's floating point arithmetic. +## @end deftypefn + ## See also: hankel, vander, sylvester_matrix, hilb, toeplitz ## Author: jwe
--- a/scripts/special-matrix/sylvester_matrix.m Sat Nov 20 17:23:01 1999 +0000 +++ b/scripts/special-matrix/sylvester_matrix.m Sun Nov 21 16:26:08 1999 +0000 @@ -17,10 +17,19 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## usage: sylvester_matrix (k) -## -## Return the Sylvester matrix of order n = 2^k. -## +## -*- texinfo -*- +## @deftypefn {Function File} {} sylvester_matrix (@var{k}) +## Return the Sylvester matrix of order +## @iftex +## @tex +## $n = 2^k$. +## @end tex +## @end iftex +## @ifinfo +## n = 2^k. +## @end ifinfo +## @end deftypefn + ## See also: hankel, vander, hilb, invhilb, toeplitz ## Author: jwe
--- a/scripts/special-matrix/toeplitz.m Sat Nov 20 17:23:01 1999 +0000 +++ b/scripts/special-matrix/toeplitz.m Sun Nov 21 16:26:08 1999 +0000 @@ -17,15 +17,43 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## usage: toeplitz (c, r) -## -## Return the Toeplitz matrix constructed given the first column -## c, and (optionally) the first row r. -## -## If the second argument is omitted, the first row is taken to be the -## same as the first column. If the first element of c is not the same -## as the first element of r, the first element of c is used. -## +## -*- texinfo -*- +## @deftypefn {Function File} {} toeplitz (@var{c}, @var{r}) +## Return the Toeplitz matrix constructed given the first column @var{c}, +## and (optionally) the first row @var{r}. If the first element of @var{c} +## is not the same as the first element of @var{r}, the first element of +## @var{c} is used. If the second argument is omitted, the first row is +## taken to be the same as the first column. +## +## A square Toeplitz matrix has the form +## @iftex +## @tex +## $$ +## \left[\matrix{c_0 & r_1 & r_2 & \ldots & r_n\cr +## c_1 & c_0 & r_1 & & c_{n-1}\cr +## c_2 & c_1 & c_0 & & c_{n-2}\cr +## \vdots & & & & \vdots\cr +## c_n & c_{n-1} & c_{n-2} & \ldots & c_0}\right]. +## $$ +## @end tex +## @end iftex +## @ifinfo +## +## @example +## @group +## c(0) r(1) r(2) ... r(n) +## c(1) c(0) r(1) r(n-1) +## c(2) c(1) c(0) r(n-2) +## . . +## . . +## . . +## +## c(n) c(n-1) c(n-2) ... c(0) +## @end group +## @end example +## @end ifinfo +## @end deftypefn + ## See also: hankel, vander, sylvester_matrix, hilb, invhib ## Author: jwe
--- a/scripts/special-matrix/vander.m Sat Nov 20 17:23:01 1999 +0000 +++ b/scripts/special-matrix/vander.m Sun Nov 21 16:26:08 1999 +0000 @@ -17,10 +17,37 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## usage: vander (c) -## -## Return the Vandermonde matrix whose next to last column is c. -## +## -*- texinfo -*- +## @deftypefn {Function File} {} vander (@var{c}) +## Return the Vandermonde matrix whose next to last column is @var{c}. +## +## A Vandermonde matrix has the form +## @iftex +## @tex +## $$ +## \left[\matrix{c_0^n & \ldots & c_0^2 & c_0 & 1\cr +## c_1^n & \ldots & c_1^2 & c_1 & 1\cr +## \vdots & & \vdots & \vdots & \vdots\cr +## c_n^n & \ldots & c_n^2 & c_n & 1}\right]. +## $$ +## @end tex +## @end iftex +## @ifinfo +## +## @example +## @group +## c(0)^n ... c(0)^2 c(0) 1 +## c(1)^n ... c(1)^2 c(1) 1 +## . . . . +## . . . . +## . . . . +## +## c(n)^n ... c(n)^2 c(n) 1 +## @end group +## @end example +## @end ifinfo +## @end deftypefn + ## See also: hankel, sylvester_matrix, hilb, invhilb, toeplitz ## Author: jwe
--- a/src/ChangeLog Sat Nov 20 17:23:01 1999 +0000 +++ b/src/ChangeLog Sun Nov 21 16:26:08 1999 +0000 @@ -1,3 +1,12 @@ +1999-11-21 John W. Eaton <jwe@bevo.che.wisc.edu> + + * utils.cc (Vtreat_neg_dim_as_zero): Texinfoize doc string. + * DLD-FUNCTIONS/find.cc (Ffind): Ditto. + * DLD-FUNCTIONS/rand.cc (Frand, Frandn): Ditto. + * DLD-FUNCTIONS/sort.cc (Fsort): Ditto. + * mappers.cc (Fisinf, Fisnan, Ffinite): Ditto. + * data.cc (Fall, Fany, Fdiag, Fones, Fzeros, Feye, Flinspace): Ditto. + 1999-11-20 John W. Eaton <jwe@bevo.che.wisc.edu> * DLD-FUNCTIONS/fft.cc (Ffft): Texinfoize doc string.
--- a/src/DLD-FUNCTIONS/find.cc Sat Nov 20 17:23:01 1999 +0000 +++ b/src/DLD-FUNCTIONS/find.cc Sun Nov 21 16:26:08 1999 +0000 @@ -157,7 +157,43 @@ } DEFUN_DLD (find, args, nargout, - "find (X) or [I, J, V] = find (X): Return indices of nonzero elements") + "-*- texinfo -*-\n\ +@deftypefn {Loadable Function} {} find (@var{x})\n\ +Return a vector of indices of nonzero elements of a matrix. To obtain a\n\ +single index for each matrix element, Octave pretends that the columns\n\ +of a matrix form one long vector (like Fortran arrays are stored). For\n\ +example,\n\ +\n\ +@example\n\ +@group\n\ +find (eye (2))\n\ + @result{} [ 1; 4 ]\n\ +@end group\n\ +@end example\n\ +\n\ +If two outputs are requested, @code{find} returns the row and column\n\ +indices of nonzero elements of a matrix. For example,\n\ +\n\ +@example\n\ +@group\n\ +[i, j] = find (2 * eye (2))\n\ + @result{} i = [ 1; 2 ]\n\ + @result{} j = [ 1; 2 ]\n\ +@end group\n\ +@end example\n\ +\n\ +If three outputs are requested, @code{find} also returns a vector\n\ +containing the nonzero values. For example,\n\ +\n\ +@example\n\ +@group\n\ +[i, j, v] = find (3 * eye (2))\n\ + @result{} i = [ 1; 2 ]\n\ + @result{} j = [ 1; 2 ]\n\ + @result{} v = [ 3; 3 ]\n\ +@end group\n\ +@end example\n\ +@end deftypefn") { octave_value_list retval;
--- a/src/DLD-FUNCTIONS/rand.cc Sat Nov 20 17:23:01 1999 +0000 +++ b/src/DLD-FUNCTIONS/rand.cc Sun Nov 21 16:26:08 1999 +0000 @@ -331,15 +331,30 @@ } DEFUN_DLD (rand, args, nargout, - "rand -- generate a random value from a uniform distribution\n\ + "-*- texinfo -*-\n\ +@deftypefn {Loadable Function} {} rand (@var{x})\n\ +@deftypefnx {Loadable Function} {} rand (@var{n}, @var{m})\n\ +@deftypefnx {Loadable Function} {} rand (@code{\"seed\"}, @var{x})\n\ +Return a matrix with random elements uniformly distributed on the\n\ +interval (0, 1). The arguments are handled the same as the arguments\n\ +for @code{eye}. In\n\ +addition, you can set the seed for the random number generator using the\n\ +form\n\ \n\ -rand (N) -- generate N x N matrix\n\ -rand (size (A)) -- generate matrix the size of A\n\ -rand (N, M) -- generate N x M matrix\n\ -rand (\"seed\") -- get current seed\n\ -rand (\"seed\", N) -- set seed\n\ +@example\n\ +rand (\"seed\", @var{x})\n\ +@end example\n\ +\n\ +@noindent\n\ +where @var{x} is a scalar value. If called as\n\ \n\ -See also: randn") +@example\n\ +rand (\"seed\")\n\ +@end example\n\ +\n\ +@noindent\n\ +@code{rand} returns the current value of the seed.\n\ +@end deftypefn") { octave_value_list retval; @@ -365,15 +380,29 @@ } DEFUN_DLD (randn, args, nargout, - "randn -- generate a random value from a normal distribution\n\ + "-*- texinfo -*-\n\ +@deftypefn {Loadable Function} {} randn (@var{x})\n\ +@deftypefnx {Loadable Function} {} randn (@var{n}, @var{m})\n\ +@deftypefnx {Loadable Function} {} randn (@code{\"seed\"}, @var{x})\n\ +Return a matrix with normally distributed random elements. The\n\ +arguments are handled the same as the arguments for @code{eye}. In\n\ +addition, you can set the seed for the random number generator using the\n\ +form\n\ \n\ -randn (N) -- generate N x N matrix\n\ -randn (size (A)) -- generate matrix the size of A\n\ -randn (N, M) -- generate N x M matrix\n\ -randn (\"seed\") -- get current seed\n\ -randn (\"seed\", N) -- set seed\n\ +@example\n\ +randn (\"seed\", @var{x})\n\ +@end example\n\ +\n\ +@noindent\n\ +where @var{x} is a scalar value. If called as\n\ \n\ -See also: rand") +@example\n\ +randn (\"seed\")\n\ +@end example\n\ +\n\ +@noindent\n\ +@code{randn} returns the current value of the seed.\n\ +@end deftypefn") { octave_value_list retval;
--- a/src/DLD-FUNCTIONS/sort.cc Sat Nov 20 17:23:01 1999 +0000 +++ b/src/DLD-FUNCTIONS/sort.cc Sun Nov 21 16:26:08 1999 +0000 @@ -308,9 +308,39 @@ } DEFUN_DLD (sort, args, nargout, - "[S, I] = sort (X)\n\ + "-*- texinfo -*-\n\ +@deftypefn {Loadable Function} {[@var{s}, @var{i}] =} sort (@var{x})\n\ +Return a copy of @var{x} with the elements elements arranged in\n\ +increasing order. For matrices, @code{sort} orders the elements in each\n\ +column.\n\ +\n\ +For example,\n\ +\n\ +@example\n\ +@group\n\ +sort ([1, 2; 2, 3; 3, 1])\n\ + @result{} 1 1\n\ + 2 2\n\ + 3 3\n\ +@end group\n\ +@end example\n\ \n\ -sort the columns of X, optionally return sort index") +The @code{sort} function may also be used to produce a matrix\n\ +containing the original row indices of the elements in the sorted\n\ +matrix. For example,\n\ +\n\ +@example\n\ +@group\n\ +[s, i] = sort ([1, 2; 2, 3; 3, 1])\n\ + @result{} s = 1 1\n\ + 2 2\n\ + 3 3\n\ + @result{} i = 1 3\n\ + 2 1\n\ + 3 2\n\ +@end group\n\ +@end example\n\ +@end deftypefn") { octave_value_list retval;
--- a/src/data.cc Sat Nov 20 17:23:01 1999 +0000 +++ b/src/data.cc Sun Nov 21 16:26:08 1999 +0000 @@ -50,7 +50,12 @@ #endif DEFUN (all, args, , - "all (X): are all elements of X nonzero?") + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {} all (@var{x})\n\ +The function @code{all} behaves like the function @code{any}, except\n\ +that it returns true only if all the elements of a vector, or all the\n\ +elements in a column of a matrix, are nonzero.\n\ +@end deftypefn") { octave_value_list retval; @@ -65,7 +70,29 @@ } DEFUN (any, args, , - "any (X): are any elements of X nonzero?") + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {} any (@var{x})\n\ +For a vector argument, return 1 if any element of the vector is\n\ +nonzero.\n\ +\n\ +For a matrix argument, return a row vector of ones and\n\ +zeros with each element indicating whether any of the elements of the\n\ +corresponding column of the matrix are nonzero. For example,\n\ +\n\ +@example\n\ +@group\n\ +any (eye (2, 4))\n\ + @result{} [ 1, 1, 0, 0 ]\n\ +@end group\n\ +@end example\n\ +\n\ +To see if any of the elements of a matrix are nonzero, you can use a\n\ +statement like\n\ +\n\ +@example\n\ +any (any (a))\n\ +@end example\n\ +@end deftypefn") { octave_value_list retval; @@ -494,7 +521,24 @@ } DEFUN (diag, args, , - "diag (X [,k]): form/extract diagonals") + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {} diag (@var{v}, @var{k})\n\ +Return a diagonal matrix with vector @var{v} on diagonal @var{k}. The\n\ +second argument is optional. If it is positive, the vector is placed on\n\ +the @var{k}-th super-diagonal. If it is negative, it is placed on the\n\ +@var{-k}-th sub-diagonal. The default value of @var{k} is 0, and the\n\ +vector is placed on the main diagonal. For example,\n\ +\n\ +@example\n\ +@group\n\ +diag ([1, 2, 3], 1)\n\ + @result{} 0 1 0 0\n\ + 0 0 2 0\n\ + 0 0 0 3\n\ + 0 0 0 0\n\ +@end group\n\ +@end example\n\ +@end deftypefn") { octave_value_list retval; @@ -933,13 +977,30 @@ } DEFUN (ones, args, , - "ones (N), ones (N, M), ones (X): create a matrix of all ones") + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {} ones (@var{x})\n\ +@deftypefnx {Built-in Function} {} ones (@var{n}, @var{m})\n\ +Return a matrix whose elements are all 1. The arguments are handled\n\ +the same as the arguments for @code{eye}.\n\ +\n\ +If you need to create a matrix whose values are all the same, you should\n\ +use an expression like\n\ +\n\ +@example\n\ +val_matrix = val * ones (n, m)\n\ +@end example\n\ +@end deftypefn") { return fill_matrix (args, 1.0, "ones"); } DEFUN (zeros, args, , - "zeros (N), zeros (N, M), zeros (X): create a matrix of all zeros") + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {} zeros (@var{x})\n\ +@deftypefnx {Built-in Function} {} zeros (@var{n}, @var{m})\n\ +Return a matrix whose elements are all 0. The arguments are handled\n\ +the same as the arguments for @code{eye}.\n\ +@end deftypefn") { return fill_matrix (args, 0.0, "zeros"); } @@ -960,7 +1021,40 @@ } DEFUN (eye, args, , - "eye (N), eye (N, M), eye (X): create an identity matrix") + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {} eye (@var{x})\n\ +@deftypefnx {Built-in Function} {} eye (@var{n}, @var{m})\n\ +Return an identity matrix. If invoked with a single scalar argument,\n\ +@code{eye} returns a square matrix with the dimension specified. If you\n\ +supply two scalar arguments, @code{eye} takes them to be the number of\n\ +rows and columns. If given a vector with two elements, @code{eye} uses\n\ +the values of the elements as the number of rows and columns,\n\ +respectively. For example,\n\ +\n\ +@example\n\ +@group\n\ +eye (3)\n\ + @result{} 1 0 0\n\ + 0 1 0\n\ + 0 0 1\n\ +@end group\n\ +@end example\n\ +\n\ +The following expressions all produce the same result:\n\ +\n\ +@example\n\ +@group\n\ +eye (2)\n\ +@equiv{}\n\ +eye (2, 2)\n\ +@equiv{}\n\ +eye (size ([1, 2; 3, 4])\n\ +@end group\n\ +@end example\n\ +\n\ +For compatibility with @sc{Matlab}, calling @code{eye} with no arguments\n\ +is equivalent to calling it with an argument of 1.\n\ +@end deftypefn") { octave_value retval; @@ -1001,16 +1095,18 @@ } DEFUN (linspace, args, , - "usage: linspace (x1, x2, n)\n\ -\n\ -Return a vector of n equally spaced points between x1 and x2\n\ -inclusive.\n\ + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {} linspace (@var{base}, @var{limit}, @var{n})\n\ +Return a row vector with @var{n} linearly spaced elements between\n\ +@var{base} and @var{limit}. The number of elements, @var{n}, must be\n\ +greater than 1. The @var{base} and @var{limit} are always included in\n\ +the range. If @var{base} is greater than @var{limit}, the elements are\n\ +stored in decreasing order. If the number of points is not specified, a\n\ +value of 100 is used.\n\ \n\ -If the final argument is omitted, n = 100 is assumed.\n\ -\n\ -All three arguments must be scalars.\n\ -\n\ -See also: logspace") +The @code{linspace} function always returns a row vector, regardless of\n\ +the value of @code{prefer_column_vectors}.\n\ +@end deftypefn") { octave_value_list retval;
--- a/src/mappers.cc Sat Nov 20 17:23:01 1999 +0000 +++ b/src/mappers.cc Sun Nov 21 16:26:08 1999 +0000 @@ -303,7 +303,18 @@ @end deftypefn"); DEFUN_MAPPER (finite, 0, xfinite, xfinite, 0, 0, 0, 0.0, 0.0, 0, - "finite (X): return 1 for finite elements of X"); + "-*- texinfo -*-\n\ +@deftypefn {Mapping Function} {} finite (@var{x})\n\ +Return 1 for elements of @var{x} that are NaN values and zero\n\ +otherwise. For example,\n\ +\n\ +@example\n\ +@group\n\ +finite ([13, Inf, NaN])\n\ + @result{} [ 1, 0, 0 ]\n\ +@end group\n\ +@end example\n\ +@end deftypefn"); DEFUN_MAPPER (fix, 0, 0, 0, fix, 0, fix, 0.0, 0.0, 0, "-*- texinfo -*-\n\ @@ -385,7 +396,18 @@ @end deftypefn"); DEFUN_MAPPER (isinf, 0, xisinf, xisinf, 0, 0, 0, 0.0, 0.0, 0, - "isinf (X): return 1 for elements of X infinite"); + "-*- texinfo -*-\n\ +@deftypefn {Mapping Function} {} isinf (@var{x})\n\ +Return 1 for elements of @var{x} that are infinite and zero\n\ +otherwise. For example,\n\ +\n\ +@example\n\ +@group\n\ +isinf ([13, Inf, NaN])\n\ + @result{} [ 0, 1, 0 ]\n\ +@end group\n\ +@end example\n\ +@end deftypefn"); DEFUN_MAPPER (isgraph, xisgraph, 0, 0, 0, 0, 0, 0.0, 0.0, 0, "-*- texinfo -*-\n\ @@ -400,7 +422,18 @@ @end deftypefn"); DEFUN_MAPPER (isnan, 0, xisnan, xisnan, 0, 0, 0, 0.0, 0.0, 0, - "isnan (X): return 1 where elements of X are NaNs"); + "-*- texinfo -*-\n\ +@deftypefn {Mapping Function} {} isnan (@var{x})\n\ +Return 1 for elements of @var{x} that are NaN values and zero\n\ +otherwise. For example,\n\ +\n\ +@example\n\ +@group\n\ +isnan ([13, Inf, NaN])\n\ + @result{} [ 0, 0, 1 ]\n\ +@end group\n\ +@end example\n\ +@end deftypefn"); DEFUN_MAPPER (isprint, xisprint, 0, 0, 0, 0, 0, 0.0, 0.0, 0, "-*- texinfo -*-\n\
--- a/src/utils.cc Sat Nov 20 17:23:01 1999 +0000 +++ b/src/utils.cc Sun Nov 21 16:26:08 1999 +0000 @@ -680,7 +680,20 @@ symbols_of_utils (void) { DEFVAR (treat_neg_dim_as_zero, 0.0, treat_neg_dim_as_zero, - "convert negative dimensions to zero"); + "-*- texinfo -*-\n\ +@defvr {Built-in Variable} treat_neg_dim_as_zero\n\ +If the value of @code{treat_neg_dim_as_zero} is nonzero, expressions\n\ +like\n\ +\n\ +@example\n\ +eye (-1)\n\ +@end example\n\ +\n\ +@noindent\n\ +produce an empty matrix (i.e., row and column dimensions are zero).\n\ +Otherwise, an error message is printed and control is returned to the\n\ +top level. The default value is 0.\n\ +@end defvr"); }