Mercurial > hg > octave-max
changeset 12640:88b82e1b54ac
maint: Periodic merge of stable branch to default branch
| author | Rik <octave@nomad.inbox5.com> |
|---|---|
| date | Sun, 01 May 2011 08:57:37 -0700 |
| parents | fd367312095a (current diff) 4d777e05d47c (diff) |
| children | 9bfc37e699da |
| files | |
| diffstat | 46 files changed, 410 insertions(+), 283 deletions(-) [+] |
line wrap: on
line diff
--- a/doc/interpreter/debug.txi +++ b/doc/interpreter/debug.txi @@ -89,7 +89,7 @@ @example @group dbstop ("asind", 1) -@result{} 27 +@result{} 28 @end group @end example @@ -102,7 +102,7 @@ @noindent Taking the above as an example, @code{dbstatus ("asind")} should return -27. The breakpoints can then be cleared with the @code{dbclear} function +28. The breakpoints can then be cleared with the @code{dbclear} function @DOCSTRING(dbclear)
--- a/doc/interpreter/func.txi +++ b/doc/interpreter/func.txi @@ -338,6 +338,24 @@ @DOCSTRING(nargout) +It is good practice at the head of a function to verify that it has been called +correctly. In Octave the following idiom is seen frequently + +@example +@group +if (nargin < min_#_inputs || nargin > max_#_inputs) + print_usage (); +endif +@end group +@end example + +@noindent +which stops the function execution and prints a message about the correct +way to call the function whenever the number of inputs is wrong. + +For compatability with @sc{matlab}, @code{nargchk} and @code{nargoutchk} are +available which provide similar error checking. + @DOCSTRING(nargchk) @DOCSTRING(nargoutchk) @@ -1277,21 +1295,26 @@ @item audio Functions for playing and recording sounds. -@item control -Functions for design and simulation of automatic control systems. +@item deprecated +Out-of-date functions which will eventually be removed from Octave. @item elfun -Elementary functions. +Elementary functions, principally trigonometric. -@item finance -Functions for computing interest payments, investment values, and rates -of return. +@item @@ftp +Class functions for the FTP object. @item general Miscellaneous matrix manipulations, like @code{flipud}, @code{rot90}, and @code{triu}, as well as other basic functions, like @code{ismatrix}, @code{nargchk}, etc. +@item geometry +Functions related to Delaunay triangulation. + +@item help +Functions for Octave's built-in help system. + @item image Image processing tools. These functions require the X Window System. @@ -1305,13 +1328,13 @@ Functions that don't really belong anywhere else. @item optimization -Minimization of functions. +Functions related to minimzation, optimization, and root finding. @item path Functions to manage the directory path Octave uses to find functions. @item pkg -Install external packages of functions in Octave. +Package manager for installing external packages of functions in Octave. @item plot Functions for displaying and printing two- and three-dimensional graphs. @@ -1329,10 +1352,11 @@ Functions for handling sparse matrices. @item specfun -Special functions. +Special functions such as @code{bessel} or @code{factor}. @item special-matrix -Functions that create special matrix forms. +Functions that create special matrix forms such as Hilbert or Vandermonde +matrices. @item startup Octave's system-wide startup file. @@ -1344,8 +1368,8 @@ Miscellaneous string-handling functions. @item testfun -Perform unit tests on other functions. +Functions for performing unit tests on other functions. @item time -Functions related to time keeping. +Functions related to time and date processing. @end table
--- a/doc/interpreter/matrix.txi +++ b/doc/interpreter/matrix.txi @@ -75,11 +75,11 @@ @DOCSTRING(isfinite) +@DOCSTRING(common_size) + @DOCSTRING(find) @DOCSTRING(lookup) - -@DOCSTRING(common_size) @node Rearranging Matrices @section Rearranging Matrices @@ -110,9 +110,9 @@ @DOCSTRING(circshift) -@DOCSTRING(shiftdim) +@DOCSTRING(shift) -@DOCSTRING(shift) +@DOCSTRING(shiftdim) @DOCSTRING(sort) @@ -120,27 +120,6 @@ @DOCSTRING(issorted) -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 -of the elements in various columns@footnote{For example, to first sort -based on the values in column 1, and then, for any values that are -repeated in column 1, sort based on the values found in column 2, etc.} -in a single call. Using the second output, however, it is possible to -sort all rows based on the values in a given column. Here's an example -that sorts the rows of a matrix based on the values in the second -column. - -@example -@group -a = [1, 2; 2, 3; 3, 1]; -[s, i] = sort (a (:, 2)); -a (i, :) - @result{} 3 1 - 1 2 - 2 3 -@end group -@end example - @DOCSTRING(nth_element) @anchor{doc-triu} @@ -178,6 +157,14 @@ @DOCSTRING(repelems) +The functions @code{linspace} and @code{logspace} make it very easy to +create vectors with evenly or logarithmically spaced elements. +@xref{Ranges}. + +@DOCSTRING(linspace) + +@DOCSTRING(logspace) + @DOCSTRING(rand) @DOCSTRING(randi) @@ -248,14 +235,6 @@ @DOCSTRING(randperm) -The functions @code{linspace} and @code{logspace} make it very easy to -create vectors with evenly or logarithmically spaced elements. -@xref{Ranges}. - -@DOCSTRING(linspace) - -@DOCSTRING(logspace) - @node Famous Matrices @section Famous Matrices
--- a/scripts/general/arrayfun.m +++ b/scripts/general/arrayfun.m @@ -30,9 +30,9 @@ ## accept array arguments it is better to call the function directly. ## ## The first input argument @var{func} can be a string, a function -## handle, an inline function or an anonymous function. The input +## handle, an inline function, or an anonymous function. The input ## argument @var{A} can be a logic array, a numeric array, a string -## array, a structure array or a cell array. By a call of the function +## array, a structure array, or a cell array. By a call of the function ## @command{arrayfun} all elements of @var{A} are passed on to the named ## function @var{func} individually. ## @@ -96,7 +96,7 @@ ## ## If the parameter @var{errfunc} after a further string input argument ## "ErrorHandler" is another string, a function handle, an inline -## function or an anonymous function, then @var{errfunc} defines a +## function, or an anonymous function, then @var{errfunc} defines a ## function to call in the case that @var{func} generates an error. ## The definition of the function must be of the form ## @@ -107,8 +107,8 @@ ## @noindent ## where there is an additional input argument to @var{errfunc} ## relative to @var{func}, given by @var{s}. This is a structure with -## the elements "identifier", "message" and "index", giving -## respectively the error identifier, the error message and the index of +## the elements "identifier", "message", and "index" giving, +## respectively, the error identifier, the error message, and the index of ## the array elements that caused the error. The size of the output ## argument of @var{errfunc} must have the same size as the output ## argument of @var{func}, otherwise a real error is thrown. For
--- a/scripts/general/blkdiag.m +++ b/scripts/general/blkdiag.m @@ -18,7 +18,7 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {} blkdiag (@var{A}, @var{B}, @var{C}, @dots{}) -## Build a block diagonal matrix from @var{A}, @var{B}, @var{C}, @dots{}. +## Build a block diagonal matrix from @var{A}, @var{B}, @var{C}, @dots{} ## All the arguments must be numeric and are two-dimensional matrices or ## scalars. ## @seealso{diag, horzcat, vertcat}
--- a/scripts/general/fliplr.m +++ b/scripts/general/fliplr.m @@ -18,7 +18,8 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {} fliplr (@var{x}) -## Return a copy of @var{x} with the order of the columns reversed. For +## Return a copy of @var{x} with the order of the columns reversed. In +## other words, @var{x} is flipped left-to-right about a vertical axis. For ## example: ## ## @example @@ -29,7 +30,7 @@ ## @end group ## @end example ## -## Note that @code{fliplr} only work with 2-D arrays. To flip N-d arrays +## Note that @code{fliplr} only works with 2-D arrays. To flip N-D arrays ## use @code{flipdim} instead. ## @seealso{flipud, flipdim, rot90, rotdim} ## @end deftypefn
--- a/scripts/general/flipud.m +++ b/scripts/general/flipud.m @@ -18,7 +18,8 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {} flipud (@var{x}) -## Return a copy of @var{x} with the order of the rows reversed. For +## Return a copy of @var{x} with the order of the rows reversed. In +## other words, @var{x} is flipped upside-down about a horizontal axis. For ## example: ## ## @example @@ -29,8 +30,7 @@ ## @end group ## @end example ## -## Due to the difficulty of defining which axis about which to flip the -## matrix @code{flipud} only work with 2-d arrays. To flip N-d arrays +## Note that @code{flipud} only works with 2-D arrays. To flip N-D arrays ## use @code{flipdim} instead. ## @seealso{fliplr, flipdim, rot90, rotdim} ## @end deftypefn
--- a/scripts/general/logspace.m +++ b/scripts/general/logspace.m @@ -17,18 +17,19 @@ ## <http://www.gnu.org/licenses/>. ## -*- texinfo -*- -## @deftypefn {Function File} {} logspace (@var{base}, @var{limit}) -## @deftypefnx {Function File} {} logspace (@var{base}, @var{limit}, @var{n}) -## Similar to @code{linspace} except that the values are logarithmically -## spaced from +## @deftypefn {Function File} {} logspace (@var{a}, @var{b}) +## @deftypefnx {Function File} {} logspace (@var{b}, @var{b}, @var{n}) +## @deftypefnx {Function File} {} logspace (@var{a}, pi, @var{n}) +## Return a row vector with @var{n} elements logarithmically spaced from ## @tex -## $10^{base}$ to $10^{limit}$. +## $10^{a}$ to $10^{b}$. ## @end tex ## @ifnottex -## 10^base to 10^limit. +## 10^@var{a} to 10^@var{b}. ## @end ifnottex +## If @var{n} is unspecified it defaults to 50. ## -## If @var{limit} is equal to +## If @var{b} is equal to ## @tex ## $\pi$, ## @end tex @@ -37,24 +38,22 @@ ## @end ifnottex ## the points are between ## @tex -## $10^{base}$ and $\pi$, +## $10^{a}$ and $\pi$, ## @end tex ## @ifnottex -## 10^base and pi, +## 10^@var{a} and pi, ## @end ifnottex ## @emph{not} ## @tex -## $10^{base}$ and $10^{\pi}$, +## $10^{a}$ and $10^{\pi}$, ## @end tex ## @ifnottex -## 10^base and 10^pi, +## 10^@var{a} and 10^pi, ## @end ifnottex -## in order to be compatible with the corresponding @sc{matlab} -## function. -## If @var{n} is unspecified it defaults to 50. +## in order to be compatible with the corresponding @sc{matlab} function. ## -## Also for compatibility with @sc{matlab}, return the second argument if -## fewer than two values are requested. +## Also for compatibility with @sc{matlab}, return the second argument @var{b} +## if fewer than two values are requested. ## @seealso{linspace} ## @end deftypefn
--- a/scripts/general/postpad.m +++ b/scripts/general/postpad.m @@ -20,9 +20,8 @@ ## @deftypefn {Function File} {} postpad (@var{x}, @var{l}) ## @deftypefnx {Function File} {} postpad (@var{x}, @var{l}, @var{c}) ## @deftypefnx {Function File} {} postpad (@var{x}, @var{l}, @var{c}, @var{dim}) -## Append the scalar value @var{c} to the vector @var{x} -## until it is of length @var{l}. If the third argument is not -## supplied, a value of 0 is used. +## Append the scalar value @var{c} to the vector @var{x} until it is of length +## @var{l}. If @var{c} is not given, a value of 0 is used. ## ## If @code{length (@var{x}) > @var{l}}, elements from the end of ## @var{x} are removed until a vector of length @var{l} is obtained.
--- a/scripts/general/prepad.m +++ b/scripts/general/prepad.m @@ -20,9 +20,8 @@ ## @deftypefn {Function File} {} prepad (@var{x}, @var{l}) ## @deftypefnx {Function File} {} prepad (@var{x}, @var{l}, @var{c}) ## @deftypefnx {Function File} {} prepad (@var{x}, @var{l}, @var{c}, @var{dim}) -## Prepend the scalar value @var{c} to the vector @var{x} -## until it is of length @var{l}. If the third argument is not -## supplied, a value of 0 is used. +## Prepend the scalar value @var{c} to the vector @var{x} until it is of length +## @var{l}. If @var{c} is not given, a value of 0 is used. ## ## If @code{length (@var{x}) > @var{l}}, elements from the beginning of ## @var{x} are removed until a vector of length @var{l} is obtained.
--- a/scripts/general/randi.m +++ b/scripts/general/randi.m @@ -20,7 +20,7 @@ ## @deftypefn {Function File} {} randi (@var{imax}) ## @deftypefnx {Function File} {} randi (@var{imax}, @var{n}) ## @deftypefnx {Function File} {} randi (@var{imax}, @var{m}, @var{n}, @dots{}) -## @deftypefnx {Function File} {} randi ([@var{imin}, @var{imax}], @dots{}) +## @deftypefnx {Function File} {} randi ([@var{imin} @var{imax}], @dots{}) ## @deftypefnx {Function File} {} randi (@dots{}, "@var{class}") ## Return random integers in the range 1:@var{imax}. ## @@ -47,7 +47,7 @@ ## uses class "double" to represent numbers. This limits the maximum ## integer (@var{imax}) and range (@var{imax} - @var{imin}) to the value ## returned by the @code{bitmax} function. For IEEE floating point numbers -## this value is @w{@code{2^53 - 1}}. +## this value is @w{@math{2^{53} - 1}}. ## ## @seealso{rand} ## @end deftypefn
--- a/scripts/general/repmat.m +++ b/scripts/general/repmat.m @@ -18,7 +18,9 @@ ## <http://www.gnu.org/licenses/>. ## -*- texinfo -*- -## @deftypefn {Function File} {} repmat (@var{A}, @var{m}, @var{n}) +## @deftypefn {Function File} {} repmat (@var{A}, @var{m}) +## @deftypefnx {Function File} {} repmat (@var{A}, @var{m}, @var{n}) +## @deftypefnx {Function File} {} repmat (@var{A}, @var{m}, @var{n}, @var{p}, @dots{}) ## @deftypefnx {Function File} {} repmat (@var{A}, [@var{m} @var{n}]) ## @deftypefnx {Function File} {} repmat (@var{A}, [@var{m} @var{n} @var{p} @dots{}]) ## Form a block matrix of size @var{m} by @var{n}, with a copy of matrix
--- a/scripts/general/rot90.m +++ b/scripts/general/rot90.m @@ -17,7 +17,8 @@ ## <http://www.gnu.org/licenses/>. ## -*- texinfo -*- -## @deftypefn {Function File} {} rot90 (@var{A}, @var{k}) +## @deftypefn {Function File} {} rot90 (@var{A}) +## @deftypefnx {Function File} {} rot90 (@var{A}, @var{k}) ## Return a copy of @var{A} 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). @@ -44,8 +45,7 @@ ## @end group ## @end example ## -## Due to the difficulty of defining an axis about which to rotate the -## matrix @code{rot90} only work with 2-D arrays. To rotate N-d arrays +## Note that @code{rot90} only works with 2-D arrays. To rotate N-D arrays ## use @code{rotdim} instead. ## @seealso{rotdim, flipud, fliplr, flipdim} ## @end deftypefn
--- a/scripts/general/rotdim.m +++ b/scripts/general/rotdim.m @@ -17,14 +17,17 @@ ## <http://www.gnu.org/licenses/>. ## -*- texinfo -*- -## @deftypefn {Function File} {} rotdim (@var{x}, @var{n}, @var{plane}) +## @deftypefn {Function File} {} rotdim (@var{x}) +## @deftypefnx {Function File} {} rotdim (@var{x}, @var{n}) +## @deftypefnx {Function File} {} rotdim (@var{x}, @var{n}, @var{plane}) ## 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). +## 90-degree increments. +## The second argument @var{n} is optional, and specifies how many 90-degree +## rotations are to be applied (the default value is 1). ## The third argument is also optional and defines the plane of the -## rotation. As such @var{plane} is a two element vector containing two -## different valid dimensions of the matrix. If @var{plane} is not given -## Then the first two non-singleton dimensions are used. +## rotation. If present, @var{plane} is a two element vector containing two +## different valid dimensions of the matrix. When @var{plane} is not given +## the first two non-singleton dimensions are used. ## ## Negative values of @var{n} rotate the matrix in a clockwise direction. ## For example,
--- a/scripts/general/shiftdim.m +++ b/scripts/general/shiftdim.m @@ -19,7 +19,7 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {@var{y} =} shiftdim (@var{x}, @var{n}) ## @deftypefnx {Function File} {[@var{y}, @var{ns}] =} shiftdim (@var{x}) -## Shift the dimension of @var{x} by @var{n}, where @var{n} must be +## Shift the dimensions of @var{x} by @var{n}, where @var{n} must be ## an integer scalar. When @var{n} is positive, the dimensions of ## @var{x} are shifted to the left, with the leading dimensions ## circulated to the end. If @var{n} is negative, then the dimensions
--- a/scripts/general/sortrows.m +++ b/scripts/general/sortrows.m @@ -18,7 +18,8 @@ ## <http://www.gnu.org/licenses/>. ## -*- texinfo -*- -## @deftypefn {Function File} {} sortrows (@var{A}, @var{c}) +## @deftypefn {Function File} {[@var{s}, @var{i}] =} sortrows (@var{A}) +## @deftypefnx {Function File} {[@var{s}, @var{i}] =} sortrows (@var{A}, @var{c}) ## Sort the rows of the matrix @var{A} according to the order of the ## columns specified in @var{c}. If @var{c} is omitted, a ## lexicographical sort is used. By default ascending order is used
--- a/scripts/linear-algebra/vech.m +++ b/scripts/linear-algebra/vech.m @@ -21,7 +21,10 @@ ## @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. +## other. This has uses in matrix calculus where the underlying matrix +## is symmetric and it would be pointless to keep values above the main +## diagonal. +## @seealso{vec} ## @end deftypefn ## See Magnus and Neudecker (1988), Matrix differential calculus with
--- a/scripts/miscellaneous/edit.m +++ b/scripts/miscellaneous/edit.m @@ -76,7 +76,7 @@ ## In place of the function name. For example, ## @table @samp ## @item [EDITOR, " %s"] -## Use the editor which Octave uses for @code{bug_report}. +## Use the editor which Octave uses for @code{edit_history}. ## ## @item "xedit %s &" ## pop up simple X11 editor in a separate window
--- a/scripts/miscellaneous/xor.m +++ b/scripts/miscellaneous/xor.m @@ -17,11 +17,24 @@ ## <http://www.gnu.org/licenses/>. ## -*- texinfo -*- -## @deftypefn {Mapping Function} {} xor (@var{x}, @var{y}) +## @deftypefn {Mapping Function} {@var{z} =} xor (@var{x}, @var{y}) ## Return the `exclusive or' of the entries of @var{x} and @var{y}. ## For boolean expressions @var{x} and @var{y}, -## @code{xor (@var{x}, @var{y})} is true if and only if @var{x} or @var{y} -## is true, but not if both @var{x} and @var{y} are true. +## @code{xor (@var{x}, @var{y})} is true if and only if one of @var{x} or +## @var{y} is true. Otherwise, for @var{x} and @var{y} both true or both +## false, @code{xor} returns false. +## +## The truth table for the xor operation is +## +## @multitable @columnfractions 0.44 .03 .05 .03 0.44 +## @item @tab @var{x} @tab @var{y} @tab @var{z} @tab +## @item @tab 0 @tab 0 @tab 0 @tab +## @item @tab 1 @tab 0 @tab 1 @tab +## @item @tab 0 @tab 1 @tab 1 @tab +## @item @tab 1 @tab 1 @tab 0 @tab +## @end multitable +## +## @seealso{and, or, not} ## @end deftypefn ## Author: KH <Kurt.Hornik@wu-wien.ac.at>
--- a/scripts/optimization/fzero.m +++ b/scripts/optimization/fzero.m @@ -24,10 +24,12 @@ ## @deftypefnx {Function File} {[@var{x}, @var{fval}, @var{info}, @var{output}] =} fzero (@dots{}) ## Find a zero of a univariate function. ## -## @var{fun} should be a function handle or name. @var{x0} should be a -## two-element vector specifying two points which bracket a zero. In -## other words, there must be a change in sign of the function between -## @var{x0}(1) and @var{x0}(2). More mathematically, the following must hold +## @var{fun} is a function handle, inline function, or string +## containing the name of the function to evaluate. +## @var{x0} should be a two-element vector specifying two points which +## bracket a zero. In other words, there must be a change in sign of the +## function between @var{x0}(1) and @var{x0}(2). More mathematically, the +## following must hold ## ## @example ## sign (@var{fun}(@var{x0}(1))) * sign (@var{fun}(@var{x0}(2))) <= 0
--- a/scripts/plot/fplot.m +++ b/scripts/plot/fplot.m @@ -21,8 +21,9 @@ ## @deftypefnx {Function File} {} fplot (@var{fn}, @var{limits}, @var{tol}) ## @deftypefnx {Function File} {} fplot (@var{fn}, @var{limits}, @var{n}) ## @deftypefnx {Function File} {} fplot (@dots{}, @var{fmt}) -## Plot a function @var{fn}, within the defined limits. @var{fn} -## an be either a string, a function handle or an inline function. +## Plot a function @var{fn} within defined limits. +## @var{fn} is a function handle, inline function, or string +## containing the name of the function to evaluate. ## The limits of the plot are given by @var{limits} of the form ## @code{[@var{xlo}, @var{xhi}]} or @code{[@var{xlo}, @var{xhi}, ## @var{ylo}, @var{yhi}]}. @var{tol} is the default tolerance to use for the
--- a/scripts/special-matrix/hadamard.m +++ b/scripts/special-matrix/hadamard.m @@ -21,32 +21,32 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {} hadamard (@var{n}) -## Construct a Hadamard matrix @var{Hn} of size @var{n}-by-@var{n}. The -## size @var{n} must be of the form @code{2 ^ @var{k} * @var{p}} in which -## @var{p} is one of 1, 12, 20 or 28. The returned matrix is normalized, -## meaning @code{Hn(:,1) == 1} and @code{Hn(1,:) == 1}. +## Construct a Hadamard matrix (@nospell{Hn}) of size @var{n}-by-@var{n}. The +## size @var{n} must be of the form @math{2^k * p} in which +## p is one of 1, 12, 20 or 28. The returned matrix is normalized, +## meaning @w{@code{Hn(:,1) == 1}} and @w{@code{Hn(1,:) == 1}}. ## ## Some of the properties of Hadamard matrices are: ## ## @itemize @bullet ## @item -## @code{kron (@var{Hm}, @var{Hn})} is a Hadamard matrix of size -## @var{m}-by-@var{n}. +## @code{kron (Hm, Hn)} is a Hadamard matrix of size @var{m}-by-@var{n}. ## ## @item -## @code{Hn * Hn' == @var{n} * eye (@var{n})}. +## @code{Hn * Hn' = @var{n} * eye (@var{n})}. +## +## @item +## The rows of @nospell{Hn} are orthogonal. ## ## @item -## The rows of @var{Hn} are orthogonal. +## @code{det (@var{A}) <= abs (det (Hn))} for all @var{A} with +## @w{@code{abs (@var{A}(i, j)) <= 1}}. ## ## @item -## @code{det (@var{A}) <= abs(det (@var{Hn}))} for all @var{A} with -## @code{abs (@var{A} (@var{i}, @var{j})) <= 1}. -## -## @item -## Multiply any row or column by -1 and still have a Hadamard matrix. +## Multiplying any row or column by -1 and the matrix will remain a Hadamard +## matrix. ## @end itemize -## +## @seealso{compan, hankel, toeplitz} ## @end deftypefn
--- a/scripts/special-matrix/hankel.m +++ b/scripts/special-matrix/hankel.m @@ -19,7 +19,7 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {} hankel (@var{c}) ## @deftypefnx {Function File} {} hankel (@var{c}, @var{r}) -## Return the Hankel matrix constructed given the first column @var{c}, and +## Return the Hankel matrix constructed from 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, it is assumed to @@ -42,7 +42,7 @@ ## @end example ## ## @end ifnottex -## @seealso{vander, sylvester_matrix, hilb, invhilb, toeplitz} +## @seealso{hadamard, toeplitz} ## @end deftypefn ## Author: jwe
--- a/scripts/special-matrix/hilb.m +++ b/scripts/special-matrix/hilb.m @@ -18,14 +18,8 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {} hilb (@var{n}) -## Return the Hilbert matrix of order @var{n}. The -## @tex -## $i,\,j$ -## @end tex -## @ifnottex -## i, j -## @end ifnottex -## element of a Hilbert matrix is defined as +## Return the Hilbert matrix of order @var{n}. The @math{i,j} element +## of a Hilbert matrix is defined as ## @tex ## $$ ## H (i, j) = {1 \over (i + j - 1)} @@ -38,7 +32,22 @@ ## @end example ## ## @end ifnottex -## @seealso{hankel, vander, sylvester_matrix, invhilb, toeplitz} +## +## Hilbert matrices are close to being singular which make them difficult to +## invert with numerical routines. +## Comparing the condition number of a random matrix 5x5 matrix with that of +## a Hilbert matrix of order 5 reveals just how difficult the problem is. +## +## @example +## @group +## cond (rand (5)) +## @result{} 14.392 +## cond (hilb (5)) +## @result{} 4.7661e+05 +## @end group +## @end example +## +## @seealso{invhilb} ## @end deftypefn ## Author: jwe
--- a/scripts/special-matrix/invhilb.m +++ b/scripts/special-matrix/invhilb.m @@ -68,7 +68,7 @@ ## Compare this 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. -## @seealso{hilb, hankel, vander, sylvester_matrix, toeplitz} +## @seealso{hilb} ## @end deftypefn ## Author: Dirk Laurie <dlaurie@na-net.ornl.gov>
--- a/scripts/special-matrix/magic.m +++ b/scripts/special-matrix/magic.m @@ -19,9 +19,11 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {} magic (@var{n}) ## -## Create an @var{n}-by-@var{n} magic square. Note that @code{magic -## (@var{2})} is undefined since there is no 2-by-2 magic square. +## Create an @var{n}-by-@var{n} magic square. A magic square is an arrangement +## of the integers @code{1:n^2} such that the row sums, column sums, and +## diagonal sums are all equal to the same value. ## +## Note: @var{n} must be greater than 2 for the magic square to exist. ## @end deftypefn function A = magic(n)
--- a/scripts/special-matrix/pascal.m +++ b/scripts/special-matrix/pascal.m @@ -20,19 +20,17 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {} pascal (@var{n}) ## @deftypefnx {Function File} {} pascal (@var{n}, @var{t}) -## Return the Pascal matrix of order @var{n} if @code{@var{t} = 0}. -## @var{t} defaults to 0. Return the pseudo-lower triangular -## Cholesky@tie{}factor of the Pascal matrix if @code{@var{t} = 1} (The sign -## of some columns may be negative). This matrix is its own -## inverse, that is @code{pascal (@var{n}, 1) ^ 2 == eye (@var{n})}. -## If @code{@var{t} = -1}, return the true Cholesky@tie{}factor with strictly -## positive values on the diagonal. -## If @code{@var{t} = 2}, return a transposed and permuted version of -## @code{pascal (@var{n}, 1)}, which is the cube root of the identity -## matrix. That is, @code{pascal (@var{n}, 2) ^ 3 == eye (@var{n})}. +## Return the Pascal matrix of order @var{n} if @code{@var{t} = 0}. @var{t} +## defaults to 0. Return the pseudo-lower triangular Cholesky@tie{}factor of +## the Pascal matrix if @code{@var{t} = 1} (The sign of some columns may be +## negative). This matrix is its own inverse, that is @code{pascal (@var{n}, +## 1) ^ 2 == eye (@var{n})}. If @code{@var{t} = -1}, return the true +## Cholesky@tie{}factor with strictly positive values on the diagonal. If +## @code{@var{t} = 2}, return a transposed and permuted version of @code{pascal +## (@var{n}, 1)}, which is the cube root of the identity matrix. That is, +## @code{pascal (@var{n}, 2) ^ 3 == eye (@var{n})}. ## -## @seealso{hankel, vander, sylvester_matrix, hilb, invhilb, toeplitz, -## hadamard, wilkinson, compan, rosser} +## @seealso{chol} ## @end deftypefn ## Author: Peter Ekberg
--- a/scripts/special-matrix/rosser.m +++ b/scripts/special-matrix/rosser.m @@ -21,8 +21,7 @@ ## Return the Rosser matrix. This is a difficult test case used to evaluate ## eigenvalue algorithms. ## -## @seealso{hankel, vander, sylvester_matrix, hilb, invhilb, toeplitz, -## hadamard, wilkinson, compan, pascal} +## @seealso{wilkinson, eig} ## @end deftypefn ## Author: Peter Ekberg @@ -42,6 +41,7 @@ -52, -43, 49, 44, -599, 411, 208, 208; -49, -8, 8, 59, 208, 208, 99, -911; 29, -44, 52, -23, 208, 208, -911, 99]; + endfunction %!assert (size(rosser()), [8,8])
--- a/scripts/special-matrix/sylvester_matrix.m +++ b/scripts/special-matrix/sylvester_matrix.m @@ -23,9 +23,10 @@ ## $n = 2^k$. ## @end tex ## @ifnottex -## n = 2^k. +## n = 2^@var{k}. ## @end ifnottex -## @seealso{hankel, vander, hilb, invhilb, toeplitz} +## +## @seealso{toeplitz, hankel} ## @end deftypefn ## Author: jwe
--- a/scripts/special-matrix/toeplitz.m +++ b/scripts/special-matrix/toeplitz.m @@ -20,9 +20,9 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {} toeplitz (@var{c}) ## @deftypefnx {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 +## Return the Toeplitz matrix constructed from the first column @var{c}, +## and (optionally) the first row @var{r}. If the first element of @var{r} +## is not the same as the first element of @var{c}, 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. ## @@ -51,7 +51,7 @@ ## @end example ## ## @end ifnottex -## @seealso{hankel, vander, sylvester_matrix, hilb, invhilb} +## @seealso{hankel} ## @end deftypefn ## Author: jwe && jh
--- a/scripts/special-matrix/vander.m +++ b/scripts/special-matrix/vander.m @@ -47,7 +47,7 @@ ## @end example ## ## @end ifnottex -## @seealso{hankel, sylvester_matrix, hilb, invhilb, toeplitz} +## @seealso{polyfit} ## @end deftypefn ## Author: jwe
--- a/scripts/special-matrix/wilkinson.m +++ b/scripts/special-matrix/wilkinson.m @@ -20,10 +20,10 @@ ## @deftypefn {Function File} {} wilkinson (@var{n}) ## Return the Wilkinson matrix of order @var{n}. Wilkinson matrices are ## symmetric and tridiagonal with pairs of nearly, but not exactly, equal -## eigenvalues. +## eigenvalues. They are useful in testing the behavior and performance +## of eigenvalue solvers. ## -## @seealso{hankel, vander, sylvester_matrix, hilb, invhilb, toeplitz, -## hadamard, rosser, compan, pascal} +## @seealso{rosser, eig} ## @end deftypefn ## Author: Peter Ekberg
--- a/scripts/statistics/base/qqplot.m +++ b/scripts/statistics/base/qqplot.m @@ -20,6 +20,7 @@ ## @deftypefn {Function File} {[@var{q}, @var{s}] =} qqplot (@var{x}) ## @deftypefnx {Function File} {[@var{q}, @var{s}] =} qqplot (@var{x}, @var{dist}) ## @deftypefnx {Function File} {[@var{q}, @var{s}] =} qqplot (@var{x}, @var{dist}, @var{params}) +## @deftypefnx {Function File} {} qqplot (@dots{}) ## Perform a QQ-plot (quantile plot). ## ## If F is the CDF of the distribution @var{dist} with parameters @@ -37,7 +38,7 @@ ## distribution on [2,4] and @var{x}, use ## ## @example -## qqplot (x, "uniform", 2, 4) +## qqplot (x, "unif", 2, 4) ## @end example ## ## @noindent
--- a/scripts/testfun/assert.m +++ b/scripts/testfun/assert.m @@ -51,7 +51,7 @@ ## @var{expected})}. If @var{expected} is zero @var{tol} will always be used as ## an absolute tolerance. ## @end table -## @seealso{test} +## @seealso{test, fail} ## @end deftypefn ## FIXME: Output throttling: don't print out the entire 100x100 matrix,
--- a/scripts/testfun/fail.m +++ b/scripts/testfun/fail.m @@ -20,7 +20,8 @@ ## public domain. ## -*- texinfo -*- -## @deftypefn {Function File} {} fail (@var{code}, @var{pattern}) +## @deftypefn {Function File} {} fail (@var{code}) +## @deftypefnx {Function File} {} fail (@var{code}, @var{pattern}) ## @deftypefnx {Function File} {} fail (@var{code}, 'warning', @var{pattern}) ## ## Return true if @var{code} fails with an error message matching @@ -45,7 +46,7 @@ ## Called with three arguments, the behavior is similar to ## @code{fail(@var{code}, @var{pattern})}, but produces an error if no ## warning is given during code execution or if the code fails. -## +## @seealso{assert} ## @end deftypefn ## Author: Paul Kienzle <pkienzle@users.sf.net>
--- a/src/DLD-FUNCTIONS/bsxfun.cc +++ b/src/DLD-FUNCTIONS/bsxfun.cc @@ -313,9 +313,10 @@ "-*- texinfo -*-\n\ @deftypefn {Loadable Function} {} bsxfun (@var{f}, @var{A}, @var{B})\n\ Apply a binary function @var{f} element-by-element to two matrix arguments\n\ -@var{A} and @var{B}. The function @var{f} must be capable of accepting\n\ -two column-vector arguments of equal length, or one column vector\n\ -argument and a scalar.\n\ +@var{A} and @var{B}. @var{f} is a function handle, inline function, or\n\ +string containing the name of the function to evaluate.\n\ +The function @var{f} must be capable of accepting two column-vector\n\ +arguments of equal length, or one column vector argument and a scalar.\n\ \n\ The dimensions of @var{A} and @var{B} must be equal or singleton. The\n\ singleton dimensions of the matrices will be expanded to the same\n\
--- a/src/DLD-FUNCTIONS/filter.cc +++ b/src/DLD-FUNCTIONS/filter.cc @@ -64,6 +64,14 @@ octave_idx_type ab_len = a_len > b_len ? a_len : b_len; + // FIXME: The two lines below should be unecessary because + // this template is called with a and b as column vectors + // already. However the a.resize line is currently (2011/04/26) + // necessary to stop bug #33164. + b.resize (dim_vector (ab_len, 1), 0.0); + if (a_len > 1) + a.resize (dim_vector (ab_len, 1), 0.0); + T norm = a (0); if (norm == static_cast<T>(0.0))
--- a/src/DLD-FUNCTIONS/find.cc +++ b/src/DLD-FUNCTIONS/find.cc @@ -341,11 +341,11 @@ @deftypefnx {Loadable Function} {@var{idx} =} find (@var{x}, @var{n})\n\ @deftypefnx {Loadable Function} {@var{idx} =} find (@var{x}, @var{n}, @var{direction})\n\ @deftypefnx {Loadable Function} {[i, j] =} find (@dots{})\n\ -@deftypefnx {Loadable Function} {[i, j, v]] =} find (@dots{})\n\ +@deftypefnx {Loadable Function} {[i, j, v] =} find (@dots{})\n\ Return a vector of indices of nonzero elements of a matrix, as a row if\n\ -@var{x} is a row or as a column otherwise. To obtain a single index for\n\ -each matrix element, Octave pretends that the columns of a matrix form one\n\ -long vector (like Fortran arrays are stored). For example:\n\ +@var{x} is a row vector or as a column otherwise. To obtain a single index\n\ +for each matrix element, Octave pretends that the columns of a matrix form\n\ +one long vector (like Fortran arrays are stored). For example:\n\ \n\ @example\n\ @group\n\ @@ -390,9 +390,9 @@ \n\ @example\n\ @group\n\ -sz = size(a);\n\ +sz = size (a);\n\ [i, j, v] = find (a);\n\ -b = sparse(i, j, v, sz(1), sz(2));\n\ +b = sparse (i, j, v, sz(1), sz(2));\n\ @end group\n\ @end example\n\ @seealso{nonzeros}\n\
--- a/src/DLD-FUNCTIONS/lookup.cc +++ b/src/DLD-FUNCTIONS/lookup.cc @@ -188,13 +188,14 @@ DEFUN_DLD (lookup, args, , "-*- texinfo -*-\n\ -@deftypefn {Loadable Function} {@var{idx} =} lookup (@var{table}, @var{y}, @var{opt})\n\ +@deftypefn {Loadable Function} {@var{idx} =} lookup (@var{table}, @var{y})\n\ +@deftypefnx {Loadable Function} {@var{idx} =} lookup (@var{table}, @var{y}, @var{opt})\n\ Lookup values in a sorted table. Usually used as a prelude to\n\ interpolation.\n\ \n\ If table is increasing and @code{idx = lookup (table, y)}, then\n\ @code{table(idx(i)) <= y(i) < table(idx(i+1))} for all @code{y(i)}\n\ -within the table. If @code{y(i) < table (1)} then\n\ +within the table. If @code{y(i) < table(1)} then\n\ @code{idx(i)} is 0. If @code{y(i) >= table(end)} or @code{isnan (y(i))} then\n\ @code{idx(i)} is @code{n}.\n\ \n\ @@ -211,7 +212,7 @@ (or @var{y} can be a single string). In this case, string lookup\n\ is performed using lexicographical comparison.\n\ \n\ -If @var{opts} is specified, it shall be a string with letters indicating\n\ +If @var{opts} is specified, it must be a string with letters indicating\n\ additional options.\n\ \n\ @table @code\n\
--- a/src/DLD-FUNCTIONS/rand.cc +++ b/src/DLD-FUNCTIONS/rand.cc @@ -326,8 +326,9 @@ DEFUN_DLD (rand, args, , "-*- texinfo -*-\n\ -@deftypefn {Loadable Function} {} rand (@var{x})\n\ -@deftypefnx {Loadable Function} {} rand (@var{n}, @var{m})\n\ +@deftypefn {Loadable Function} {} rand (@var{n})\n\ +@deftypefnx {Loadable Function} {} rand (@var{n}, @var{m}, @dots{})\n\ +@deftypefnx {Loadable Function} {} rand ([@var{n} @var{m} @dots{}])\n\ @deftypefnx {Loadable Function} {@var{v} =} rand (\"state\")\n\ @deftypefnx {Loadable Function} {} rand (\"state\", @var{v})\n\ @deftypefnx {Loadable Function} {} rand (\"state\", \"reset\")\n\ @@ -359,13 +360,13 @@ value of @var{v}, not @var{v} itself.\n\ \n\ By default, the generator is initialized from @code{/dev/urandom} if it is\n\ -available, otherwise from CPU time, wall clock time and the current\n\ +available, otherwise from CPU time, wall clock time, and the current\n\ fraction of a second.\n\ \n\ To compute the pseudo-random sequence, @code{rand} uses the Mersenne\n\ Twister with a period of @math{2^{19937}-1} (See M. Matsumoto and\n\ T. Nishimura,\n\ -@cite{Mersenne Twister: A 623-dimensionally equidistributed uniform \n\ +@cite{Mersenne Twister: A 623-dimensionally equidistributed uniform\n\ pseudorandom number generator}, ACM Trans. on\n\ Modeling and Computer Simulation Vol. 8, No. 1, pp. 3-30, January 1998,\n\ @url{http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html}).\n\ @@ -490,8 +491,9 @@ DEFUN_DLD (randn, args, , "-*- texinfo -*-\n\ -@deftypefn {Loadable Function} {} randn (@var{x})\n\ -@deftypefnx {Loadable Function} {} randn (@var{n}, @var{m})\n\ +@deftypefn {Loadable Function} {} randn (@var{n})\n\ +@deftypefnx {Loadable Function} {} randn (@var{n}, @var{m}, @dots{})\n\ +@deftypefnx {Loadable Function} {} randn ([@var{n} @var{m} @dots{}])\n\ @deftypefnx {Loadable Function} {@var{v} =} randn (\"state\")\n\ @deftypefnx {Loadable Function} {} randn (\"state\", @var{v})\n\ @deftypefnx {Loadable Function} {} randn (\"state\", \"reset\")\n\ @@ -555,8 +557,9 @@ DEFUN_DLD (rande, args, , "-*- texinfo -*-\n\ -@deftypefn {Loadable Function} {} rande (@var{x})\n\ -@deftypefnx {Loadable Function} {} rande (@var{n}, @var{m})\n\ +@deftypefn {Loadable Function} {} rande (@var{n})\n\ +@deftypefnx {Loadable Function} {} rande (@var{n}, @var{m}, @dots{})\n\ +@deftypefnx {Loadable Function} {} rande ([@var{n} @var{m} @dots{}])\n\ @deftypefnx {Loadable Function} {@var{v} =} rande (\"state\")\n\ @deftypefnx {Loadable Function} {} rande (\"state\", @var{v})\n\ @deftypefnx {Loadable Function} {} rande (\"state\", \"reset\")\n\ @@ -621,8 +624,9 @@ DEFUN_DLD (randg, args, , "-*- texinfo -*-\n\ -@deftypefn {Loadable Function} {} randg (@var{a}, @var{x})\n\ -@deftypefnx {Loadable Function} {} randg (@var{a}, @var{n}, @var{m})\n\ +@deftypefn {Loadable Function} {} randg (@var{n})\n\ +@deftypefnx {Loadable Function} {} randg (@var{n}, @var{m}, @dots{})\n\ +@deftypefnx {Loadable Function} {} randg ([@var{n} @var{m} @dots{}])\n\ @deftypefnx {Loadable Function} {@var{v} =} randg (\"state\")\n\ @deftypefnx {Loadable Function} {} randg (\"state\", @var{v})\n\ @deftypefnx {Loadable Function} {} randg (\"state\", \"reset\")\n\ @@ -663,7 +667,7 @@ r = 2 * randg (df / 2)\n\ @end example\n\ \n\ -@item @code{t(df)} for @code{0 < df < inf} (use randn if df is infinite)\n\ +@item @code{t (df)} for @code{0 < df < inf} (use randn if df is infinite)\n\ \n\ @example\n\ r = randn () / sqrt (2 * randg (df / 2) / df)\n\ @@ -877,8 +881,9 @@ DEFUN_DLD (randp, args, , "-*- texinfo -*-\n\ -@deftypefn {Loadable Function} {} randp (@var{l}, @var{x})\n\ -@deftypefnx {Loadable Function} {} randp (@var{l}, @var{n}, @var{m})\n\ +@deftypefn {Loadable Function} {} randp (@var{l}, @var{n})\n\ +@deftypefnx {Loadable Function} {} randp (@var{l}, @var{n}, @var{m}, @dots{})\n\ +@deftypefnx {Loadable Function} {} randp (@var{l}, [@var{n} @var{m} @dots{}])\n\ @deftypefnx {Loadable Function} {@var{v} =} randp (\"state\")\n\ @deftypefnx {Loadable Function} {} randp (\"state\", @var{v})\n\ @deftypefnx {Loadable Function} {} randp (\"state\", \"reset\")\n\ @@ -1022,7 +1027,7 @@ @deftypefnx {Loadable Function} {} randperm (@var{n}, @var{m})\n\ Return a row vector containing a random permutation of @code{1:@var{n}}.\n\ If @var{m} is supplied, return @var{m} permutations,\n\ -one in each row of an @nospell{NxM} matrix. The complexity is O(M*N) in both\n\ +one in each row of an @nospell{MxN} matrix. The complexity is O(M*N) in both\n\ time and memory. The randomization is performed using rand().\n\ All permutations are equally likely.\n\ @seealso{perms}\n\
--- a/src/DLD-FUNCTIONS/tril.cc +++ b/src/DLD-FUNCTIONS/tril.cc @@ -389,7 +389,7 @@ If the option \"pack\" is given as third argument, the extracted elements\n\ are not inserted into a matrix, but rather stacked column-wise one above\n\ other.\n\ -@seealso{triu, diag}\n\ +@seealso{diag}\n\ @end deftypefn") { return do_trilu ("tril", args);
--- a/src/data.cc +++ b/src/data.cc @@ -106,10 +106,25 @@ DEFUN (all, args, , "-*- texinfo -*-\n\ -@deftypefn {Built-in Function} {} all (@var{x}, @var{dim})\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 along dimension @var{dim} of a matrix, are nonzero.\n\ +@deftypefn {Built-in Function} {} all (@var{x})\n\ +@deftypefnx {Built-in Function} {} all (@var{x}, @var{dim})\n\ +For a vector argument, return true (logical 1) if all elements of the vector\n\ +are nonzero.\n\ +\n\ +For a matrix argument, return a row vector of logical ones and\n\ +zeros with each element indicating whether all of the elements of the\n\ +corresponding column of the matrix are nonzero. For example:\n\ +\n\ +@example\n\ +@group\n\ +all ([2, 3; 1, 0]))\n\ + @result{} [ 1, 0 ]\n\ +@end group\n\ +@end example\n\ +\n\ +If the optional argument @var{dim} is supplied, work along dimension\n\ +@var{dim}.\n\ +@seealso{any}\n\ @end deftypefn") { ANY_ALL (all); @@ -140,11 +155,12 @@ DEFUN (any, args, , "-*- texinfo -*-\n\ -@deftypefn {Built-in Function} {} any (@var{x}, @var{dim})\n\ -For a vector argument, return 1 if any element of the vector is\n\ -nonzero.\n\ +@deftypefn {Built-in Function} {} any (@var{x})\n\ +@deftypefnx {Built-in Function} {} any (@var{x}, @var{dim})\n\ +For a vector argument, return true (logical 1) if any element of the vector\n\ +is nonzero.\n\ \n\ -For a matrix argument, return a row vector of ones and\n\ +For a matrix argument, return a row vector of logical 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\ @@ -164,6 +180,7 @@ @result{} [ 1; 1 ]\n\ @end group\n\ @end example\n\ +@seealso{all}\n\ @end deftypefn") { ANY_ALL (any); @@ -1686,8 +1703,15 @@ DEFUN (horzcat, args, , "-*- texinfo -*-\n\ @deftypefn {Built-in Function} {} horzcat (@var{array1}, @var{array2}, @dots{}, @var{arrayN})\n\ -Return the horizontal concatenation of N-d array objects, @var{array1},\n\ +Return the horizontal concatenation of N-D array objects, @var{array1},\n\ @var{array2}, @dots{}, @var{arrayN} along dimension 2.\n\ +\n\ +Arrays may also be concatenated horizontally using the syntax for creating\n\ +new matrices. For example:\n\ +\n\ +@example\n\ +@var{hcat} = [ @var{array1}, @var{array2}, @dots{} ];\n\ +@end example\n\ @seealso{cat, vertcat}\n\ @end deftypefn") { @@ -1697,8 +1721,15 @@ DEFUN (vertcat, args, , "-*- texinfo -*-\n\ @deftypefn {Built-in Function} {} vertcat (@var{array1}, @var{array2}, @dots{}, @var{arrayN})\n\ -Return the vertical concatenation of N-d array objects, @var{array1},\n\ +Return the vertical concatenation of N-D array objects, @var{array1},\n\ @var{array2}, @dots{}, @var{arrayN} along dimension 1.\n\ +\n\ +Arrays may also be concatenated vertically using the syntax for creating\n\ +new matrices. For example:\n\ +\n\ +@example\n\ +@var{vcat} = [ @var{array1}; @var{array2}; @dots{} ];\n\ +@end example\n\ @seealso{cat, horzcat}\n\ @end deftypefn") { @@ -1708,7 +1739,7 @@ DEFUN (cat, args, , "-*- texinfo -*-\n\ @deftypefn {Built-in Function} {} cat (@var{dim}, @var{array1}, @var{array2}, @dots{}, @var{arrayN})\n\ -Return the concatenation of N-d array objects, @var{array1},\n\ +Return the concatenation of N-D array objects, @var{array1},\n\ @var{array2}, @dots{}, @var{arrayN} along dimension @var{dim}.\n\ \n\ @example\n\ @@ -1716,10 +1747,8 @@ A = ones (2, 2);\n\ B = zeros (2, 2);\n\ cat (2, A, B)\n\ -@result{} ans =\n\ -\n\ - 1 1 0 0\n\ - 1 1 0 0\n\ + @result{} 1 1 0 0\n\ + 1 1 0 0\n\ @end group\n\ @end example\n\ \n\ @@ -1732,23 +1761,23 @@ @end group\n\ @end example\n\ \n\ -@var{dim} can be larger than the dimensions of the N-d array objects\n\ +@var{dim} can be larger than the dimensions of the N-D array objects\n\ and the result will thus have @var{dim} dimensions as the\n\ following example shows:\n\ \n\ @example\n\ @group\n\ -cat (4, ones(2, 2), zeros (2, 2))\n\ -@result{} ans =\n\ +cat (4, ones (2, 2), zeros (2, 2))\n\ + @result{} ans =\n\ \n\ - ans(:,:,1,1) =\n\ + ans(:,:,1,1) =\n\ \n\ - 1 1\n\ - 1 1\n\ + 1 1\n\ + 1 1\n\ \n\ - ans(:,:,1,2) =\n\ - 0 0\n\ - 0 0\n\ + ans(:,:,1,2) =\n\ + 0 0\n\ + 0 0\n\ @end group\n\ @end example\n\ @seealso{horzcat, vertcat}\n\ @@ -1946,10 +1975,10 @@ DEFUN (permute, args, , "-*- texinfo -*-\n\ -@deftypefn {Built-in Function} {} permute (@var{a}, @var{perm})\n\ -Return the generalized transpose for an N-d array object @var{a}.\n\ +@deftypefn {Built-in Function} {} permute (@var{A}, @var{perm})\n\ +Return the generalized transpose for an N-D array object @var{A}.\n\ The permutation vector @var{perm} must contain the elements\n\ -@code{1:ndims(a)} (in any order, but each element must appear just once).\n\ +@code{1:ndims(A)} (in any order, but each element must appear only once).\n\ @seealso{ipermute}\n\ @end deftypefn") { @@ -1958,15 +1987,15 @@ DEFUN (ipermute, args, , "-*- texinfo -*-\n\ -@deftypefn {Built-in Function} {} ipermute (@var{a}, @var{iperm})\n\ +@deftypefn {Built-in Function} {} ipermute (@var{A}, @var{iperm})\n\ The inverse of the @code{permute} function. The expression\n\ \n\ @example\n\ -ipermute (permute (a, perm), perm)\n\ +ipermute (permute (A, perm), perm)\n\ @end example\n\ \n\ @noindent\n\ -returns the original array @var{a}.\n\ +returns the original array @var{A}.\n\ @seealso{permute}\n\ @end deftypefn") { @@ -3433,28 +3462,29 @@ DEFUN (ones, args, , "-*- texinfo -*-\n\ -@deftypefn {Built-in Function} {} ones (@var{x})\n\ -@deftypefnx {Built-in Function} {} ones (@var{n}, @var{m})\n\ -@deftypefnx {Built-in Function} {} ones (@var{n}, @var{m}, @var{k}, @dots{})\n\ +@deftypefn {Built-in Function} {} ones (@var{n})\n\ +@deftypefnx {Built-in Function} {} ones (@var{m}, @var{n})\n\ +@deftypefnx {Built-in Function} {} ones (@var{m}, @var{n}, @var{k}, @dots{})\n\ +@deftypefnx {Built-in Function} {} ones ([@var{m} @var{n} @dots{}])\n\ @deftypefnx {Built-in Function} {} ones (@dots{}, @var{class})\n\ Return a matrix or N-dimensional array whose elements are all 1.\n\ -If invoked with a single scalar integer argument, return a square\n\ -matrix of the specified size. If invoked with two or more scalar\n\ +If invoked with a single scalar integer argument @var{n}, return a square\n\ +@nospell{NxN} matrix. If invoked with two or more scalar\n\ integer arguments, or a vector of integer values, return an array with\n\ -given dimensions.\n\ +the given dimensions.\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\ +val_matrix = val * ones (m, n)\n\ @end example\n\ \n\ The optional argument @var{class} specifies the class of the return array\n\ and defaults to double. For example:\n\ \n\ @example\n\ -val = ones (n,m, \"uint8\")\n\ +val = ones (m,n, \"uint8\")\n\ @end example\n\ @seealso{zeros}\n\ @end deftypefn") @@ -3483,21 +3513,22 @@ DEFUN (zeros, args, , "-*- texinfo -*-\n\ -@deftypefn {Built-in Function} {} zeros (@var{x})\n\ -@deftypefnx {Built-in Function} {} zeros (@var{n}, @var{m})\n\ -@deftypefnx {Built-in Function} {} zeros (@var{n}, @var{m}, @var{k}, @dots{})\n\ +@deftypefn {Built-in Function} {} zeros (@var{n})\n\ +@deftypefnx {Built-in Function} {} zeros (@var{m}, @var{n})\n\ +@deftypefnx {Built-in Function} {} zeros (@var{m}, @var{n}, @var{k}, @dots{})\n\ +@deftypefnx {Built-in Function} {} zeros ([@var{m} @var{n} @dots{}])\n\ @deftypefnx {Built-in Function} {} zeros (@dots{}, @var{class})\n\ Return a matrix or N-dimensional array whose elements are all 0.\n\ If invoked with a single scalar integer argument, return a square\n\ -matrix of the specified size. If invoked with two or more scalar\n\ +@nospell{NxN} matrix. If invoked with two or more scalar\n\ integer arguments, or a vector of integer values, return an array with\n\ -given dimensions.\n\ +the given dimensions.\n\ \n\ The optional argument @var{class} specifies the class of the return array\n\ and defaults to double. For example:\n\ \n\ @example\n\ -val = zeros (n,m, \"uint8\")\n\ +val = zeros (m,n, \"uint8\")\n\ @end example\n\ @seealso{ones}\n\ @end deftypefn") @@ -4113,14 +4144,15 @@ DEFUN (eye, args, , "-*- texinfo -*-\n\ -@deftypefn {Built-in Function} {} eye (@var{x})\n\ -@deftypefnx {Built-in Function} {} eye (@var{n}, @var{m})\n\ +@deftypefn {Built-in Function} {} eye (@var{n})\n\ +@deftypefnx {Built-in Function} {} eye (@var{m}, @var{n})\n\ +@deftypefnx {Built-in Function} {} eye ([@var{m} @var{n}])\n\ @deftypefnx {Built-in Function} {} eye (@dots{}, @var{class})\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\ +Return an identity matrix. If invoked with a single scalar argument @var{n},\n\ +return a square @nospell{NxN} identity matrix. If\n\ +supplied two scalar arguments (@var{m}, @var{n}), @code{eye} takes them to be\n\ +the number of rows and columns. If given a vector with two elements,\n\ +@code{eye} uses the values of the elements as the number of rows and columns,\n\ respectively. For example:\n\ \n\ @example\n\ @@ -4154,6 +4186,7 @@ Calling @code{eye} with no arguments is equivalent to calling it\n\ with an argument of 1. This odd definition is for compatibility\n\ with @sc{matlab}.\n\ +@seealso{speye}\n\ @end deftypefn") { octave_value retval; @@ -4271,20 +4304,21 @@ DEFUN (linspace, args, , "-*- texinfo -*-\n\ -@deftypefn {Built-in Function} {} linspace (@var{base}, @var{limit}, @var{n})\n\ +@deftypefn {Built-in Function} {} linspace (@var{base}, @var{limit})\n\ +@deftypefnx {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}. If the number of elements is greater than one,\n\ -then the @var{base} and @var{limit} are always included in\n\ +then the endpoints @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\ The @code{linspace} function always returns a row vector if both\n\ -@var{base} and @var{limit} are scalars. If one of them or both are column\n\ +@var{base} and @var{limit} are scalars. If one, or both, of them are column\n\ vectors, @code{linspace} returns a matrix.\n\ \n\ -For compatibility with @sc{matlab}, return the second argument if\n\ -fewer than two values are requested.\n\ +For compatibility with @sc{matlab}, return the second argument (@var{limit})\n\ +if fewer than two values are requested.\n\ @end deftypefn") { octave_value retval; @@ -4357,8 +4391,8 @@ DEFUN (resize, args, , "-*- texinfo -*-\n\ @deftypefn {Built-in Function} {} resize (@var{x}, @var{m})\n\ -@deftypefnx {Built-in Function} {} resize (@var{x}, @var{m}, @var{n})\n\ @deftypefnx {Built-in Function} {} resize (@var{x}, @var{m}, @var{n}, @dots{})\n\ +@deftypefnx {Built-in Function} {} resize (@var{x}, [@var{m} @var{n} @dots{}])\n\ Resize @var{x} cutting off elements as necessary.\n\ \n\ In the result, element with certain indices is equal to the corresponding\n\ @@ -4386,11 +4420,12 @@ @noindent\n\ but is performed more efficiently.\n\ \n\ -If only @var{m} is supplied and it is a scalar, the dimension of the\n\ -result is @var{m}-by-@var{m}. If @var{m} is a vector, then the\n\ -dimensions of the result are given by the elements of @var{m}.\n\ -If both @var{m} and @var{n} are scalars, then the dimensions of\n\ -the result are @var{m}-by-@var{n}.\n\ +If only @var{m} is supplied, and it is a scalar, the dimension of the\n\ +result is @var{m}-by-@var{m}.\n\ +If @var{m}, @var{n}, @dots{} are all scalars, then the dimensions of\n\ +the result are @var{m}-by-@var{n}-by-@dots{}.\n\ +If given a vector as input, then the\n\ +dimensions of the result are given by the elements of that vector.\n\ \n\ An object can be resized to more dimensions than it has;\n\ in such case the missing dimensions are assumed to be 1.\n\ @@ -4443,13 +4478,16 @@ DEFUN (reshape, args, , "-*- texinfo -*-\n\ -@deftypefn {Built-in Function} {} reshape (@var{a}, @var{m}, @var{n}, @dots{})\n\ -@deftypefnx {Built-in Function} {} reshape (@var{a}, @var{size})\n\ -Return a matrix with the given dimensions whose elements are taken\n\ -from the matrix @var{a}. The elements of the matrix are accessed in\n\ -column-major order (like Fortran arrays are stored).\n\ +@deftypefn {Built-in Function} {} reshape (@var{A}, @var{m}, @var{n}, @dots{})\n\ +@deftypefnx {Built-in Function} {} reshape (@var{A}, [@var{m} @var{n} @dots{}])\n\ +@deftypefnx {Built-in Function} {} reshape (@var{A}, @dots{}, [], @dots{})\n\ +@deftypefnx {Built-in Function} {} reshape (@var{A}, @var{size})\n\ +Return a matrix with the specified dimensions (@var{m}, @var{n}, @dots{})\n\ +whose elements are taken from the matrix @var{A}. The elements of the\n\ +matrix are accessed in column-major order (like Fortran arrays are stored).\n\ \n\ -For example:\n\ +The following code demonstrates reshaping a 1x4 row vector into a 2x2 square\n\ +matrix.\n\ \n\ @example\n\ @group\n\ @@ -4461,10 +4499,13 @@ \n\ @noindent\n\ Note that the total number of elements in the original\n\ -matrix must match the total number of elements in the new matrix.\n\ +matrix (@code{prod (size (@var{A}))}) must match the total number of elements\n\ +in the new matrix (@code{prod ([@var{m} @var{n} @dots{}])}).\n\ \n\ -A single dimension of the return matrix can be unknown and is flagged\n\ -by an empty argument.\n\ +A single dimension of the return matrix may be left unspecified and Octave\n\ +will determine its size automatically. An empty matrix ([]) is used to flag\n\ +the unspecified dimension.\n\ +@seealso{resize}\n\ @end deftypefn") { octave_value retval; @@ -4584,6 +4625,7 @@ @code{@var{x}(:)}. If @var{dim} is supplied, the dimensions of @var{v}\n\ are set to @var{dim} with all elements along the last dimension.\n\ This is equivalent to @code{shiftdim (@var{x}(:), 1-@var{dim})}.\n\ +@seealso{vech}\n\ @end deftypefn") { octave_value retval; @@ -4871,7 +4913,7 @@ @deftypefn {Built-in Function} {} not (@var{x})\n\ Return the logical NOT of @var{x}. This function is equivalent to\n\ @code{! x}.\n\ -@seealso{and, or}\n\ +@seealso{and, or, xor}\n\ @end deftypefn") { return unary_op_defun_body (octave_value::op_not, args); @@ -5214,7 +5256,7 @@ @end example\n\ \n\ At least one argument is required.\n\ -@seealso{or, not}\n\ +@seealso{or, not, xor}\n\ @end deftypefn") { return binary_assoc_op_defun_body (octave_value::op_el_and, @@ -5235,7 +5277,7 @@ @end example\n\ \n\ At least one argument is required.\n\ -@seealso{and, not}\n\ +@seealso{and, not, xor}\n\ @end deftypefn") { return binary_assoc_op_defun_body (octave_value::op_el_or, @@ -5425,7 +5467,7 @@ @deftypefnx {Loadable Function} {[@var{s}, @var{i}] =} sort (@var{x}, @var{mode})\n\ @deftypefnx {Loadable Function} {[@var{s}, @var{i}] =} sort (@var{x}, @var{dim}, @var{mode})\n\ Return a copy of @var{x} with the elements arranged in increasing\n\ -order. For matrices, @code{sort} orders the elements in each column.\n\ +order. For matrices, @code{sort} orders the elements within columns\n\ \n\ For example:\n\ \n\ @@ -5438,6 +5480,11 @@ @end group\n\ @end example\n\ \n\ +If the optional argument @var{dim} is given, then the matrix is sorted\n\ +along the dimension defined by @var{dim}. The optional argument @code{mode}\n\ +defines the order in which the values will be sorted. Valid values of\n\ +@code{mode} are `ascend' or `descend'.\n\ +\n\ 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\ @@ -5454,16 +5501,27 @@ @end group\n\ @end example\n\ \n\ -If the optional argument @var{dim} is given, then the matrix is sorted\n\ -along the dimension defined by @var{dim}. The optional argument @code{mode}\n\ -defines the order in which the values will be sorted. Valid values of\n\ -@code{mode} are `ascend' or `descend'.\n\ +For equal elements, the indices are such that equal elements are listed\n\ +in the order in which they appeared in the original list.\n\ +\n\ +Sorting of complex entries is done first by magnitude (@code{abs (@var{z})})\n\ +and for any ties by phase angle (@code{angle (z)}). For example:\n\ \n\ -For equal elements, the indices are such that the equal elements are listed\n\ -in the order that appeared in the original list.\n\ +@example\n\ +@group\n\ +sort ([1+i; 1; 1-i])\n\ + @result{} 1 + 0i\n\ + 1 - 1i\n\ + 1 + 1i\n\ +@end group\n\ +@end example\n\ +\n\ +NaN values are treated as being greater than any other value and are sorted\n\ +to the end of the list.\n\ \n\ The @code{sort} function may also be used to sort strings and cell arrays\n\ -of strings, in which case the dictionary order of the strings is used.\n\ +of strings, in which case ASCII dictionary order (uppercase 'A' precedes\n\ +lowercase 'a') of the strings is used.\n\ \n\ The algorithm used in @code{sort} is optimized for the sorting of partially\n\ ordered lists.\n\ @@ -5813,7 +5871,8 @@ DEFUN (issorted, args, , "-*- texinfo -*-\n\ -@deftypefn {Built-in Function} {} issorted (@var{a}, @var{mode})\n\ +@deftypefn {Built-in Function} {} issorted (@var{a})\n\ +@deftypefnx {Built-in Function} {} issorted (@var{a}, @var{mode})\n\ @deftypefnx {Built-in Function} {} issorted (@var{a}, @code{\"rows\"}, @var{mode})\n\ Return true if the array is sorted according to @var{mode}, which\n\ may be either \"ascending\", \"descending\", or \"either\". By default,\n\ @@ -5936,7 +5995,8 @@ \n\ nth_element encapsulates the C++ standard library algorithms nth_element and\n\ partial_sort. On average, the complexity of the operation is O(M*log(K)),\n\ -where @code{M = size(@var{x}, @var{dim})} and @code{K = length (@var{n})}.\n\ +where @w{@code{M = size (@var{x}, @var{dim})}} and\n\ +@w{@code{K = length (@var{n})}}.\n\ This function is intended for cases where the ratio K/M is small; otherwise,\n\ it may be better to use @code{sort}.\n\ @seealso{sort, min, max}\n\ @@ -6550,8 +6610,10 @@ DEFUN (diff, args, , "-*- texinfo -*-\n\ -@deftypefn {Built-in Function} {} diff (@var{x}, @var{k}, @var{dim})\n\ -If @var{x} is a vector of length @var{n}, @code{diff (@var{x})} is the\n\ +@deftypefn {Built-in Function} {} diff (@var{x})\n\ +@deftypefnx {Built-in Function} {} diff (@var{x}, @var{k})\n\ +@deftypefnx {Built-in Function} {} diff (@var{x}, @var{k}, @var{dim})\n\ +If @var{x} is a vector of length @math{n}, @code{diff (@var{x})} is the\n\ vector of first differences\n\ @tex\n\ $x_2 - x_1, \\ldots{}, x_n - x_{n-1}$.\n\ @@ -6566,15 +6628,15 @@ The second argument is optional. If supplied, @code{diff (@var{x},\n\ @var{k})}, where @var{k} is a non-negative integer, returns the\n\ @var{k}-th differences. It is possible that @var{k} is larger than\n\ -then first non-singleton dimension of the matrix. In this case,\n\ +the first non-singleton dimension of the matrix. In this case,\n\ @code{diff} continues to take the differences along the next\n\ non-singleton dimension.\n\ \n\ The dimension along which to take the difference can be explicitly\n\ -stated with the optional variable @var{dim}. In this case the \n\ +stated with the optional variable @var{dim}. In this case the\n\ @var{k}-th order differences are calculated along this dimension.\n\ In the case where @var{k} exceeds @code{size (@var{x}, @var{dim})}\n\ -then an empty matrix is returned.\n\ +an empty matrix is returned.\n\ @end deftypefn") { int nargin = args.length ();
--- a/src/load-path.cc +++ b/src/load-path.cc @@ -2122,8 +2122,8 @@ @deftypefn {Built-in Function} {} addpath (@var{dir1}, @dots{})\n\ @deftypefnx {Built-in Function} {} addpath (@var{dir1}, @dots{}, @var{option})\n\ Add @var{dir1}, @dots{} to the current function search path. If\n\ -@var{option} is @samp{\"-begin\"} or 0 (the default), prepend the\n\ -directory name to the current path. If @var{option} is @samp{\"-end\"}\n\ +@var{option} is \"-begin\" or 0 (the default), prepend the\n\ +directory name to the current path. If @var{option} is \"-end\"\n\ or 1, append the directory name to the current path.\n\ Directories added to the path must exist.\n\ \n\
--- a/src/mappers.cc +++ b/src/mappers.cc @@ -879,11 +879,11 @@ \n\ @example\n\ @group\n\ - infinity\n\ - /\n\ + infinity\n\ + /\n\ gamma (z) = | t^(z-1) exp (-t) dt.\n\ - /\n\ - t=0\n\ + /\n\ + t=0\n\ @end group\n\ @end example\n\ \n\
--- a/src/ov-fcn-inline.cc +++ b/src/ov-fcn-inline.cc @@ -879,6 +879,17 @@ Create a vectorized version of the inline function @var{fun}\n\ by replacing all occurrences of @code{*}, @code{/}, etc., with\n\ @code{.*}, @code{./}, etc.\n\ +\n\ +This may be useful, for example, when using inline functions with\n\ +numerical integration or optimization where a vector-valued function\n\ +is expected.\n\ +\n\ +@example\n\ +fcn = vectorize (inline (\"x^2 - 1\"))\n\ + @result{} fcn = f(x) = x.^2 - 1\n\ +quadv (fcn, 0, 3)\n\ + @result{} 6\n\ +@end example\n\ @end deftypefn") { octave_value retval;