Using the C Math Library

Specifying the Index String

You pass an indexing string as the second argument to an indexing function. An indexing string is always surrounded by "". For example, the MATLAB indexing expression A(2,1) is written like this in the MATLAB C Math Library.

mlfIndexRef(A, "(?,?)", mlfScalar(2), mlfScalar(1))

"(?,?)" is the indexing string that specifies a two-dimensional index. The question mark, ?, is a placeholder for each index value.

• If you're indexing into a regular array, use parentheses,(), to enclose the subscript.
• If you're indexing into a cell array, use braces, {}, to enclose the subscript.

Some more sample indexing strings:

"(?,?,?,?)": standard indexing
"{?}": cell array indexing
"(?,?).y{?}": combined standard, structure, and cell array indexing

Table 5-1: Elements of Index String Syntax 

Syntax Element	Definition	Example
( )	Encloses an array subscript.	"(?,?)"
{ }	Encloses a cell array subscript.	"{?,?}"
,	Separates dimensions of the subscript	"(?,?,?)"
?	Placeholder for a single array index value.	"(?)"
.field	Indicates a field in a structure	("?.score")

What an Indexing String Specifies

When you specify an indexing string, you provide the following information to the indexing functions:

• Number of dimensions in the subscript

For example, the single ? in "(?)" indicates a one-dimensional subscript. The three ?'s in "(?,?,?)" indicates a three-dimensional subscript.

• Type of indexing

For example, the parentheses in "(?,?)" indicate array indexing. The braces in "{?,?}" indicate that you are accessing the contents of a cell in a cell array.

• Which field in a structure you're accessing

.field indicates you're accessing a field within a structure.

An indexing string does not specify:

• The values of the indices themselves

The ? is a placeholder for actual values. The values are specified as subsequent mxArray* arguments passed to the indexing functions.

• Nested subscripts

Each ? is a placeholder for a single array index.

Complex Indexing Expressions

In MATLAB, you can write complicated indexing expressions. For example, this MATLAB expression

B{3}(7).bfield(2,1)

combines cell array, standard, and structure indexing. The expression first selects the third element of cell array B; this third element must be an array. From this array it selects the seventh element, which must be a structure with at least one field, named bfield. From that structure it selects the array stored in the bfield field, and then the element at position (2,1) within that array.

In the MATLAB C Math Library, you can specify this entire indexing operation as a single string: "{?}(?).bfield(?,?)". Passing this string to any of the MATLAB C Math Library indexing functions selects that location for reading, writing, or deletion.

In the MATLAB C Math Library, the expression becomes

mlfIndexRef(B, "{?}(?).bfield(?,?)",
            mlfScalar(3), mlfScalar(7),
            mlfScalar(2), mlfScalar(1));

Nesting Indexing Operations

In MATLAB, you can nest indexing operations; when you do, the results of the inner indexing operation supply the index values for the outer index operation. Because the MATLAB C Math Library represents MATLAB indexing operations with calls to mlfIndexRef(), you can recreate the MATLAB behavior in the library by nesting calls to mlfIndexRef() inside one another.

For example, the MATLAB expression

x(y(4)) = 3

becomes

mlfIndexAssign(&x, "(?)", mlfIndexRef(y, "(?)", mlfScalar(4)),
                 mlfScalar(3));

The MATLAB expression

D = A(foo(1,B(2,3)), bar(4,C(:)))

becomes

mlfAssign(&D,
      mlfIndexRef(A,"(?,?)",
            foo(mlfScalar(1),
                mlfIndexRef(B,"(?,?)",mlfScalar(2),mlfScalar(3))),
            bar(mlfScalar(4),
                mlfIndexRef(C,"(?)",mlfCreateColonIndex()))));

Specifying the Target Array

Specifying the Values for Indices