\section{DIAG Diagonal Matrix Construction/Extraction}

\subsection{Usage}

The \verb|diag| function is used to either construct a 
diagonal matrix from a vector, or return the diagonal
elements of a matrix as a vector.  The general syntax
for its use is
\begin{verbatim}
  y = diag(x,n)
\end{verbatim}
If \verb|x| is a matrix, then \verb|y| returns the \verb|n|-th 
diagonal.  If \verb|n| is omitted, it is assumed to be
zero.  Conversely, if \verb|x| is a vector, then \verb|y|
is a matrix with \verb|x| set to the \verb|n|-th diagonal.
\subsection{Examples}

Here is an example of \verb|diag| being used to extract
a diagonal from a matrix.
\begin{verbatim}
--> A = int32(10*rand(4,5))

A = 

 3 5 3 5 8 
 2 6 8 7 5 
 3 2 5 5 3 
 5 4 1 7 0 

--> diag(A)

ans = 

 3 
 6 
 5 
 7 

--> diag(A,1)

ans = 

 5 
 8 
 5 
 0 


\end{verbatim}
Here is an example of the second form of \verb|diag|, being
used to construct a diagonal matrix.
\begin{verbatim}
--> x = int32(10*rand(1,3))

x = 

 6 4 9 

--> diag(x)

ans = 

 6 0 0 
 0 4 0 
 0 0 9 

--> diag(x,-1)

ans = 

 0 0 0 0 
 6 0 0 0 
 0 4 0 0 
 0 0 9 0 


\end{verbatim}
