\section{INDEXING Indexing Expressions}

\subsection{Usage}

There are three classes of indexing expressions available 
in FreeMat: \verb|()|, \verb|{}|, and \verb|.|  Each is explained below
in some detail, and with its own example section.
\subsection{Array Indexing}

We start with array indexing \verb|()|,
which is the most general indexing expression, and can be
used on any array.  There are two general forms for the 
indexing expression - the N-dimensional form, for which 
the general syntax is
\begin{verbatim}
  variable(index_1,index_2,...,index_n)
\end{verbatim}
and the vector form, for which the general syntax is
\begin{verbatim}
  variable(index)
\end{verbatim}
Here each index expression is either a scalar, a range
of integer values, or the special token \verb|:|, which is
shorthand for \verb|1:end|.  The keyword \verb|end|, when included
in an indexing expression, is assigned the length of the 
array in that dimension.  The concept is easier to demonstrate
than explain.  Consider the following examples:
\begin{verbatim}
--> A = zeros(4)
A = 
  <float>  - size: [4 4]
 
Columns 1 to 4
 0  0  0  0  
 0  0  0  0  
 0  0  0  0  
 0  0  0  0  
--> B = float(randn(2))
B = 
  <float>  - size: [2 2]
 
Columns 1 to 2
 -0.939406097  -0.053095356  
 -0.006488070  -0.164794579  
--> A(2:3,2:3) = B
A = 
  <float>  - size: [4 4]
 
Columns 1 to 4
  0.000000000   0.000000000   0.000000000   0.000000000  
  0.000000000  -0.939406097  -0.053095356   0.000000000  
  0.000000000  -0.006488070  -0.164794579   0.000000000  
  0.000000000   0.000000000   0.000000000   0.000000000  

\end{verbatim}
Here the array indexing was used on the left hand side only.
It can also be used for right hand side indexing, as in
\begin{verbatim}
--> C = A(2:3,1:end)
C = 
  <float>  - size: [2 4]
 
Columns 1 to 4
  0.000000000  -0.939406097  -0.053095356   0.000000000  
  0.000000000  -0.006488070  -0.164794579   0.000000000  

\end{verbatim}
Note that we used the \verb|end| keyword to avoid having to know
that \verb|A| has 4 columns.  Of course, we could also use the 
\verb|:| token instead:
\begin{verbatim}
--> C = A(2:3,:)
C = 
  <float>  - size: [2 4]
 
Columns 1 to 4
  0.000000000  -0.939406097  -0.053095356   0.000000000  
  0.000000000  -0.006488070  -0.164794579   0.000000000  

\end{verbatim}
An extremely useful example of \verb|:| with array indexing is for
slicing.  Suppose we have a 3-D array, that is \verb|2 x 2 x 3|,
and we want to set the middle slice:
\begin{verbatim}
--> D = zeros(2,2,3)
D = 
  <float>  - size: [2 2 3]
(:,:,1) = 
 
Columns 1 to 2
 0  0  
 0  0  
(:,:,2) = 
 
Columns 1 to 2
 0  0  
 0  0  
(:,:,3) = 
 
Columns 1 to 2
 0  0  
 0  0  
--> D(:,:,2) = int32(10*rand(2,2))
D = 
  <float>  - size: [2 2 3]
(:,:,1) = 
 
Columns 1 to 2
 0  0  
 0  0  
(:,:,2) = 
 
Columns 1 to 2
 5  2  
 9  4  
(:,:,3) = 
 
Columns 1 to 2
 0  0  
 0  0  

\end{verbatim}
In another level of nuance, the assignment expression will
automatically fill in the indexed rectangle on the left using
data from the right hand side, as long as the lengths match.
So we can take a vector and roll it into a matrix using this
approach:
\begin{verbatim}
--> A = zeros(4)
A = 
  <float>  - size: [4 4]
 
Columns 1 to 4
 0  0  0  0  
 0  0  0  0  
 0  0  0  0  
 0  0  0  0  
--> v = [1;2;3;4]
v = 
  <int32>  - size: [4 1]
 
Columns 1 to 1
 1  
 2  
 3  
 4  
--> A(2:3,2:3) = v
A = 
  <float>  - size: [4 4]
 
Columns 1 to 4
 0  0  0  0  
 0  1  3  0  
 0  2  4  0  
 0  0  0  0  

\end{verbatim}

The N-dimensional form of the variable index is limited
to accessing only (hyper-) rectangular regions of the 
array.  You cannot, for example, use it to access only
the diagonal elements of the array.  To do that, you use
the second form of the array access (or a loop).  The
vector form treats an arbitrary N-dimensional array as though
it were a column vector.  You can then access arbitrary 
subsets of the arrays elements (for example, through a \verb|find|
expression) efficiently.  Note that in vector form, the \verb|end|
keyword takes the meaning of the total length of the array
(defined as the product of its dimensions), as opposed to the
size along the first dimension.
\subsection{Cell Indexing}

The second form of indexing operates, to a large extent, in
the same manner as the array indexing, but it is by no means
interchangable.  As the name implies, \verb|cell|-indexing applies
only to \verb|cell| arrays.  For those familiar with \verb|C|, cell-
indexing is equivalent to pointer derefencing in \verb|C|.  First,
the syntax:
\begin{verbatim}
  variable{index_1,index_2,...,index_n}
\end{verbatim}
and the vector form, for which the general syntax is
\begin{verbatim}
  variable{index}
\end{verbatim}
The rules and interpretation for N-dimensional and vector indexing
are identical to \verb|()|, so we will describe only the differences.
In simple terms, applying \verb|()| to a cell-array returns another
cell array that is a subset of the original array.  On the other
hand, applying \verb|{}| to a cell-array returns the contents of that
cell array.  A simple example makes the difference quite clear:
\begin{verbatim}
--> A = {1, 'hello', [1:4]}
A = 
  <cell array> - size: [1 3]
 
Columns 1 to 3
 [1]    hello    [[1 4] int32]    
--> A(1:2)
ans = 
  <cell array> - size: [1 2]
 
Columns 1 to 2
 [1]    hello    
--> A{1:2}
ans = 

1 of 2:
  <int32>  - size: [1 1]
 1  

2 of 2:
  <string>  - size: [1 5]
 hello

\end{verbatim}
You may be surprised by the response to the last line.  The output
is multiple assignments to \verb|ans|!.  The output of a cell-array
dereference can be used anywhere a list of expressions is required.
This includes arguments and returns for function calls, matrix
construction, etc.  Here is an example of using cell-arrays to pass
parameters to a function:
\begin{verbatim}
--> A = {[1,3,0],[5,2,7]}
A = 
  <cell array> - size: [1 2]
 
Columns 1 to 2
 [[1 3] int32]    [[1 3] int32]    
--> max(A{1:end})
ans = 
  <int32>  - size: [1 3]
 
Columns 1 to 3
 5  3  7  

\end{verbatim}
And here, cell-arrays are used to capture the return.
\begin{verbatim}
--> [K{1:2}] = max(randn(1,4))
K = 
  <cell array> - size: [1 2]
 
Columns 1 to 2
 [1.182465]    [1]    

\end{verbatim}
Here, cell-arrays are used in the matrix construction process:
\begin{verbatim}
--> C = [A{1};A{2}]
C = 
  <int32>  - size: [2 3]
 
Columns 1 to 3
 1  3  0  
 5  2  7  

\end{verbatim}
Note that this form of indexing is used to implement variable
length arguments to function.  See \verb|varargin| and \verb|varargout|
for more details.
\subsection{Structure Indexing}

The third form of indexing is structure indexing.  It can only
be applied to structure arrays, and has the general syntax
\begin{verbatim}
  variable.fieldname
\end{verbatim}
where \verb|fieldname| is one of the fields on the structure.  Note that
in FreeMat, fields are allocated dynamically, so if you reference
a field that does not exist in an assignment, it is created automatically
for you.  If variable is an array, then the result of the \verb|.| 
reference is an expression list, exactly like the \verb|{}| operator.  Hence,
we can use structure indexing in a simple fashion:
\begin{verbatim}
--> clear A
--> A.color = 'blue'
A = 
  <structure array> - size: [1 1]
    color: blue
--> B = A.color
B = 
  <string>  - size: [1 4]
 blue

\end{verbatim}
Or in more complicated ways using expression lists for function arguments
\begin{verbatim}
--> clear A
--> A(1).maxargs = [1,6,7,3]
A = 
  <structure array> - size: [1 1]
    maxargs: [[1 4] int32]
--> A(2).maxargs = [5,2,9,0]
A = 
  <structure array> - size: [1 2]
  Fields
    maxargs
--> max(A.maxargs)
ans = 
  <int32>  - size: [1 4]
 
Columns 1 to 4
 5  6  9  3  

\end{verbatim}
or to store function outputs
\begin{verbatim}
--> clear A
--> A(1).maxreturn = [];
--> A(2).maxreturn = [];
--> [A.maxreturn] = max(randn(1,4))
A = 
  <structure array> - size: [1 2]
  Fields
    maxreturn

\end{verbatim}
FreeMat now also supports the so called dynamic-field indexing 
expressions.  In this mode, the fieldname is supplied through 
an expression instead of being explicitly provided.  For example,
suppose we have a set of structure indexed by color,
\begin{verbatim}
--> x.red = 430;
--> x.green = 240;
--> x.blue = 53;
--> x.yello = 105
x = 
  <structure array> - size: [1 1]
    red: [430]
    green: [240]
    blue: [53]
    yello: [105]

\end{verbatim}
Then we can index into the structure \verb|x| using a dynamic field
reference:
\begin{verbatim}
--> y = 'green'
y = 
  <string>  - size: [1 5]
 green
--> a = x.(y)
a = 
  <int32>  - size: [1 1]
 240  

\end{verbatim}
Note that the indexing expression has to resolve to a string for
dynamic field indexing to work.
\subsection{Complex Indexing}

The indexing expressions described above can be freely combined
to affect complicated indexing expressions.  Here is an example
that exercises all three indexing expressions in one assignment.
\begin{verbatim}
--> Z{3}.foo(2) = pi
Z = 
  <cell array> - size: [1 3]
 
Columns 1 to 3
 []    []     [1 1] struct array    

\end{verbatim}
From this statement, FreeMat infers that Z is a cell-array of 
length 3, that the third element is a structure array (with one
element), and that this structure array contains a field named
'foo' with two double elements, the second of which is assigned
a value of pi.
