\section{SHIFTDIM Shift Array Dimensions Function}

\subsection{Usage}

The \verb|shiftdim| function is used to shift the dimensions of an array.
The general syntax for the \verb|shiftdim| function is
\begin{verbatim}
   y = shiftdim(x,n)
\end{verbatim}
where \verb|x| is a multidimensional array, and \verb|n| is an integer.  If
\verb|n| is a positive integer, then \verb|shiftdim| circularly shifts the 
dimensions of \verb|x| to the left, wrapping the dimensions around as 
necessary.  If \verb|n| is a negative integer, then \verb|shiftdim| shifts
the dimensions of \verb|x| to the right, introducing singleton dimensions
as necessary.  In its second form:
\begin{verbatim}
  [y,n] = shiftdim(x)
\end{verbatim}
the \verb|shiftdim| function will shift away (to the left) the leading
singleton dimensions of \verb|x| until the leading dimension is not
 a singleton dimension (recall that a singleton dimension \verb|p| is one for
which \verb|size(x,p) == 1|).
\subsection{Example}

Here are some simple examples of using \verb|shiftdim| to remove the singleton
dimensions of an array, and then restore them:
\begin{verbatim}
--> x = uint8(10*randn(1,1,1,3,2));
--> [y,n] = shiftdim(x);
--> n

ans = 

 3 

--> size(y)

ans = 

 3 2 

--> c = shiftdim(y,-n);
--> size(c)

ans = 

 1 1 1 3 2 

--> any(c~=x)

ans = 

 0 


\end{verbatim}
Note that these operations (where shifting involves only singleton dimensions)
do not actually cause data to be resorted, only the size of the arrays change.
This is not true for the following example, which triggers a call to \verb|permute|:
\begin{verbatim}
--> z = shiftdim(x,4);

\end{verbatim}
 Note that \verb|z| is now the transpose of \verb|x|
\begin{verbatim}
--> squeeze(x)

ans = 

 254   0 
  17   6 
 245   7 

--> squeeze(z)

ans = 

 254  17 245 
   0   6   7 


\end{verbatim}
