\section{FIND Find Non-zero Elements of An Array}

\subsection{Usage}

Returns a vector that contains the indicies of all non-zero elements 
in an array.  The usage is
\begin{verbatim}
   y = find(x)
\end{verbatim}
The indices returned are generalized column indices, meaning that if 
the array \verb|x| is of size \verb|[d1,d2,...,dn]|, and the
element \verb|x(i1,i2,...,in)| is nonzero, then \verb|y|
will contain the integer
\[
   i_1 + (i_2-1) d_1 + (i_3-1) d_1 d_2 + \dots
\]
The second syntax for the \verb|find| command is
\begin{verbatim}
   [r,c] = find(x)
\end{verbatim}
which returns the row and column index of the nonzero entries of \verb|x|.
The third syntax for the \verb|find| command also returns the values
\begin{verbatim}
   [r,c,v] = find(x).
\end{verbatim}
Note that if the argument is a row vector, then the returned vectors
are also row vectors. This form is particularly useful for converting 
sparse matrices into IJV form.

The \verb|find| command also supports some additional arguments.  Each of the
above forms can be combined with an integer indicating how many results
to return:
\begin{verbatim}
   y = find(x,k)
\end{verbatim}
where \verb|k| is the maximum number of results to return.  This form will return
the first \verb|k| results.  You can also specify an optional flag indicating 
whether to take the first or last \verb|k| values:
\begin{verbatim}
   y = find(x,k,'first')
   y = find(x,k,'last')
\end{verbatim}
in the case of the \verb|'last'| argument, the last \verb|k| values are returned.
\subsection{Example}

Some simple examples of its usage, and some common uses of \verb|find| in FreeMat programs.
\begin{verbatim}
--> a = [1,2,5,2,4];
--> find(a==2)

ans = 

 2 4 


\end{verbatim}
Here is an example of using find to replace elements of \verb|A| that are \verb|0| with the number \verb|5|.
\begin{verbatim}
--> A = [1,0,3;0,2,1;3,0,0]

A = 

 1 0 3 
 0 2 1 
 3 0 0 

--> n = find(A==0)

n = 

 2 
 4 
 6 
 9 

--> A(n) = 5

A = 

 1 5 3 
 5 2 1 
 3 5 5 


\end{verbatim}
Incidentally, a better way to achieve the same concept is:
\begin{verbatim}
--> A = [1,0,3;0,2,1;3,0,0]

A = 

 1 0 3 
 0 2 1 
 3 0 0 

--> A(A==0) = 5

A = 

 1 5 3 
 5 2 1 
 3 5 5 


\end{verbatim}
Now, we can also return the indices as row and column indices using the two argument
form of \verb|find|:
\begin{verbatim}
--> A = [1,0,3;0,2,1;3,0,0]

A = 

 1 0 3 
 0 2 1 
 3 0 0 

--> [r,c] = find(A)
r = 

 1 
 3 
 2 
 1 
 2 

c = 

 1 
 1 
 2 
 3 
 3 


\end{verbatim}
Or the three argument form of \verb|find|, which returns the value also:
\begin{verbatim}
--> [r,c,v] = find(A)
r = 

 1 
 3 
 2 
 1 
 2 

c = 

 1 
 1 
 2 
 3 
 3 

v = 

 1 
 3 
 2 
 3 
 1 


\end{verbatim}
