COLON Index Generation Operator

Section: Mathematical Operators

Usage

There are two distinct syntaxes for the colon : operator - the two argument form 
  y = a : c

and the three argument form 

  y = a : b : c

The two argument form is exactly equivalent to a:1:c. The output y is the vector

where a+nb <= c. There is a third form of the colon operator, the no-argument form used in indexing (see indexing for more details).

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 
   y = a : b : c

The first question that one might need to answer is: how many points in this vector? If you answered

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)

where

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

but one can readily verify for themselves that this may \emph{not} be the same as the vector

even for the case where

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:

  1. The value n is computed by taking the floor of the larger value in the interval defined above.
  2. If n falls inside the interval defined above, then it is assumed that the user intended c = a + n*b, and the symmetric algorithm is used. Otherwise, the nonsymmetric algorithm is used.
  3. 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.
  4. The real interval calculation is modified so that we get the exact same result with a:b:c and c:-b:a (which basically means that instead of moving towards infinity, we move towards the signed infinity where the sign is inherited from b).
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.

Examples

Some simple examples of index generation. 
--> y = 1:4

y = 
 1 2 3 4

Now by half-steps: 

--> y = 1:.5:4

y = 
    1.0000    1.5000    2.0000    2.5000    3.0000    3.5000    4.0000

Now going backwards (negative steps) 

--> y = 4:-.5:1

y = 
    4.0000    3.5000    3.0000    2.5000    2.0000    1.5000    1.0000

If the endpoints are the same, one point is generated, regardless of the step size (middle argument) 

--> y = 4:1:4

y = 
 4

If the endpoints define an empty interval, the output is an empty matrix: 

--> y = 5:4

y = 
  Empty array 1 0