\section{SORT Sort }

\subsection{Usage}

Sorts an n-dimensional array along the specified dimensional.  The first
form sorts the array along the first non-singular dimension.
\begin{verbatim}
  B = sort(A)
\end{verbatim}
Alternately, the dimension along which to sort can be explicitly specified
\begin{verbatim}
  B = sort(A,dim)
\end{verbatim}
FreeMat does not support vector arguments for \verb|dim| - if you need \verb|A| to be
sorted along multiple dimensions (i.e., row first, then columns), make multiple
calls to \verb|sort|.  Also, the direction of the sort can be specified using the 
\verb|mode| argument
\begin{verbatim}
  B = sort(A,dim,mode)
\end{verbatim}
where \verb|mode = 'ascend'| means to sort the data in ascending order (the default),
and \verb|mode = 'descend'| means to sort the data into descending order.  

When two outputs are requested from \verb|sort|, the indexes are also returned.
Thus, for 
\begin{verbatim}
  [B,IX] = sort(A)
  [B,IX] = sort(A,dim)
  [B,IX] = sort(A,dim,mode)
\end{verbatim}
an array \verb|IX| of the same size as \verb|A|, where \verb|IX| records the indices of \verb|A|
(along the sorting dimension) corresponding to the output array \verb|B|. 

Two additional issues worth noting.  First, a cell array can be sorted if each 
cell contains a \verb|string|, in which case the strings are sorted by lexical order.
The second issue is that FreeMat uses the same method as MATLAB to sort complex
numbers.  In particular, a complex number \verb|a| is less than another complex
number \verb|b| if \verb|abs(a) < abs(b)|.  If the magnitudes are the same then we 
test the angle of \verb|a|, i.e. \verb|angle(a) < angle(b)|, where \verb|angle(a)| is the
phase of \verb|a| between \verb|-pi,pi|.
\subsection{Example}

Here are some examples of sorting on numerical arrays.
\begin{verbatim}
--> A = int32(10*rand(4,3))
A = 
  <int32>  - size: [4 3]
 
Columns 1 to 3
 8  3  7  
 5  3  8  
 6  5  1  
 7  3  5  
--> [B,IX] = sort(A)
B = 
  <int32>  - size: [4 3]
 
Columns 1 to 3
 5  3  1  
 6  3  5  
 7  3  7  
 8  5  8  
IX = 
  <int32>  - size: [4 3]
 
Columns 1 to 3
 2  1  3  
 3  2  4  
 4  4  1  
 1  3  2  
--> [B,IX] = sort(A,2)
B = 
  <int32>  - size: [4 3]
 
Columns 1 to 3
 3  7  8  
 3  5  8  
 1  5  6  
 3  5  7  
IX = 
  <int32>  - size: [4 3]
 
Columns 1 to 3
 2  3  1  
 2  1  3  
 3  2  1  
 2  3  1  
--> [B,IX] = sort(A,1,'descend')
B = 
  <int32>  - size: [4 3]
 
Columns 1 to 3
 8  5  8  
 7  3  7  
 6  3  5  
 5  3  1  
IX = 
  <int32>  - size: [4 3]
 
Columns 1 to 3
 1  3  2  
 4  1  1  
 3  2  4  
 2  4  3  

\end{verbatim}
Here we sort a cell array of strings.
\begin{verbatim}
--> a = {'hello','abba','goodbye','jockey','cake'}
a = 
  <cell array> - size: [1 5]
 
Columns 1 to 3
 hello    abba    goodbye    
 
Columns 4 to 5
 jockey    cake    
--> b = sort(a)
b = 
  <cell array> - size: [1 5]
 
Columns 1 to 3
 abba    cake    goodbye    
 
Columns 4 to 5
 hello    jockey    

\end{verbatim}
