| DEFUN_DLD (find, args, nargout,"-*- texinfo -*-\n\
@deftypefn {Loadable Function} {@var{idx} =} find (@var{x})\n\
@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\
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\
\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\
\n\
If two inputs are given, @var{n} indicates the maximum number of\n\
elements to find from the beginning of the matrix or vector.\n\
\n\
If three inputs are given, @var{direction} should be one of \"first\" or\n\
\"last\", requesting only the first or last @var{n} indices, respectively.\n\
However, the indices are always returned in ascending order.\n\
\n\
Note that this function is particularly useful for sparse matrices, as\n\
it extracts the non-zero elements as vectors, which can then be used to\n\
create the original matrix. For example:\n\
\n\
@example\n\
@group\n\
sz = size(a);\n\
[i, j, v] = find (a);\n\
b = sparse(i, j, v, sz(1), sz(2));\n\
@end group\n\
@end example\n\
@seealso{nonzeros}\n\
@end deftypefn") |