\section{COLON Index Generation Operator}

\subsection{Usage}

There are two distinct syntaxes for the colon \verb|:| operator - the two argument form
\begin{verbatim}
  y = a : c
\end{verbatim}
and the three argument form
\begin{verbatim}
  y = a : b : c
\end{verbatim}
The two argument form is exactly equivalent to \verb|a:1:c|.  The output \verb|y| is the vector
\[
  y = [a,a+b,a+2b,\ldots,a+nb]
\]
where \verb|a+nb <= c|.  There is a third form of the colon operator, the 
no-argument form used in indexing (see \verb|indexing| for more details).
\subsection{Function Internals}

The colon operator turns out to be trickier to implement than one might 
believe at first, primarily because the floating point versions should
do the right thing, which is not the obvious behavior.  For example,
suppose the user issues a three point colon command
\begin{verbatim}
   y = a : b : c
\end{verbatim}
The first question that one might need to answer is: how many points
in this vector?  If you answered
\[
   n = \frac{c-a}{b}+1
\]
then you would be doing the straighforward, but not correct thing.
because a, b, and c are all floating point values, there are errors
associated with each of the quantities that can lead to n not being
an integer.  A better way (and the way FreeMat currently does the
calculation) is to compute the bounding values (for b positive)
\[
   n \in \left[\frac{(c-a) \rightarrow 0}{b \rightarrow \infty},
               \frac{(c-a) \rightarrow \infty}{b \rightarrow 0} \right] + 1
\]
where 
\[
  x \rightarrow y 
\]
means we replace x by the floating point number that is closest to it
in the direction of y.  Once we have determined the number of points
we have to compute the intermediate values
\[
  [a, a+b, a+2*b, \ldots, a+n*b]
\]
but one can readily verify for themselves that this may \emph{not} be
the same as the vector
\[
  \mathrm{fliplr} [c, c-b, c-2*b, \ldots, c-n*b]
\]
even for the case where
\[
   c = a + n*b
\]
for some n.  The reason is that the roundoff in the calculations may
be different depending on the nature of the sum.  FreeMat uses the
following strategy to compute the double-colon vector:
\begin{enumerate}
\item  The value \verb|n| is computed by taking the floor of the larger 
 value in the interval defined above.

\item  If \verb|n| falls inside the interval defined above, then it is 
assumed that the user intended \verb|c = a + n*b|, and the symmetric 
algorithm is used.  Otherwise, the nonsymmetric algorithm is used.

\item  The symmetric algorithm computes the vector via
\[
  [a, a+b, a+2b,\ldots,c-2b,c-b,c]
\]
working symmetrically from both ends of the vector 
(hence the nomenclature), while the nonsymmetric algorithm computes
\[
  [a, a+b ,a+2b,\ldots,a+nb]
\]
In practice, the entries are computed by repeated accumulation instead 
of multiplying the step size by an integer.

\item  The real interval calculation is modified so that we get the
exact same result with \verb|a:b:c| and \verb|c:-b:a| (which basically means
that instead of moving towards infinity, we move towards the signed 
infinity where the sign is inherited from \verb|b|).

\end{enumerate}
If you think this is all very obscure, it is.  But without it, you will
be confronted by mysterious vectors where the last entry is dropped,
or where the values show progressively larger amounts of accumulated
roundoff error.
\subsection{Examples}

Some simple examples of index generation.
\begin{verbatim}
--> y = 1:4
y = 
  <int32>  - size: [1 4]
 
Columns 1 to 4
 1  2  3  4  

\end{verbatim}
Now by half-steps:
\begin{verbatim}
--> y = 1:.5:4
y = 
  <double>  - size: [1 7]
 
Columns 1 to 7
 1.0  1.5  2.0  2.5  3.0  3.5  4.0  

\end{verbatim}
Now going backwards (negative steps)
\begin{verbatim}
--> y = 4:-.5:1
y = 
  <double>  - size: [1 7]
 
Columns 1 to 7
 4.0  3.5  3.0  2.5  2.0  1.5  1.0  

\end{verbatim}
If the endpoints are the same, one point is generated, regardless of the step size (middle argument)
\begin{verbatim}
--> y = 4:1:4
y = 
  <int32>  - size: [1 1]
 4  

\end{verbatim}
If the endpoints define an empty interval, the output is an empty matrix:
\begin{verbatim}
--> y = 5:4
y = 
  <int32>  - size: []
  []

\end{verbatim}
