\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 = 
  <int32>  - size: [4 5]
 
Columns 1 to 5
 7  3  9  9  0  
 4  4  3  9  5  
 2  4  9  2  7  
 2  6  1  9  8  
--> diag(A)
ans = 
  <int32>  - size: [4 1]
 
Columns 1 to 1
 7  
 4  
 9  
 9  
--> diag(A,1)
ans = 
  <int32>  - size: [4 1]
 
Columns 1 to 1
 3  
 3  
 2  
 8  

\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 = 
  <int32>  - size: [1 3]
 
Columns 1 to 3
 8  7  9  
--> diag(x)
ans = 
  <int32>  - size: [3 3]
 
Columns 1 to 3
 8  0  0  
 0  7  0  
 0  0  9  
--> diag(x,-1)
ans = 
  <int32>  - size: [4 4]
 
Columns 1 to 4
 0  0  0  0  
 8  0  0  0  
 0  7  0  0  
 0  0  9  0  

\end{verbatim}
