\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 = 
  <uint32>  - size: [1 2]
 
Columns 1 to 2
 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 = 
  <int32>  - size: [3 3]
 
Columns 1 to 3
 1  0  3  
 0  2  1  
 3  0  0  
--> n = find(A==0)
n = 
  <uint32>  - size: [4 1]
 
Columns 1 to 1
 2  
 4  
 6  
 9  
--> A(n) = 5
A = 
  <int32>  - size: [3 3]
 
Columns 1 to 3
 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 = 
  <int32>  - size: [3 3]
 
Columns 1 to 3
 1  0  3  
 0  2  1  
 3  0  0  
--> A(A==0) = 5
A = 
  <int32>  - size: [3 3]
 
Columns 1 to 3
 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 = 
  <int32>  - size: [3 3]
 
Columns 1 to 3
 1  0  3  
 0  2  1  
 3  0  0  
--> [r,c] = find(A)
r = 
  <uint32>  - size: [5 1]
 
Columns 1 to 1
 1  
 3  
 2  
 1  
 2  
c = 
  <uint32>  - size: [5 1]
 
Columns 1 to 1
 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 = 
  <uint32>  - size: [5 1]
 
Columns 1 to 1
 1  
 3  
 2  
 1  
 2  
c = 
  <uint32>  - size: [5 1]
 
Columns 1 to 1
 1  
 1  
 2  
 3  
 3  
v = 
  <int32>  - size: [5 1]
 
Columns 1 to 1
 1  
 3  
 2  
 3  
 1  

\end{verbatim}
