Using the C Math Library

Creating Numeric Arrays

To create a numeric array, use any of the following mechanisms:

• Using an array creation routine
• Calling an arithmetic routine
• Concatenating existing arrays
• Assigning a value to an element in an array

Using Numeric Array Creation Routines

The MATLAB C Math Library contains many routines that create various types of numeric arrays, including scalar arrays, vectors, matrices, multidimensional arrays and some commonly useful arrays.

Creating Scalar Arrays.   The simplest way to create an array is to use the mlfScalar() routine. When you pass this routine a numeric value, it creates an 1-by-1 numeric array containing the value, stored in double precision format. Whenever you have to pass a numeric value to a library routine, you can use mlfScalar().

Creating Two-Dimensional Arrays (Matrices).   Because two-dimensional arrays of double precision values are used so often in MATLAB, the library includes the routine mlfDoubleMatrix() that allows you to create a matrix of double precision values and initialize it with data. Note that you can use integers to specify the array dimensions; you do not need to convert these to arrays.

static double data[] = { 1, 4, 2, 5, 3, 6 };

mxArray *A = NULL;

mlfAssign(&A, mlfDoubleMatrix(2,     /*  Rows  */
                              3,     /*  Columns */
                              data,  
                              NULL));/* No imaginary part */

mlfPrintMatrix(A);

mxDestroyArray(A);

This code produces the following output.

1    2    3
4    5    6

In this code fragment, note that the values in the C array used to initialize the MATLAB array are not specified in numeric order because MATLAB stores arrays in column major order and C arrays are stored in row-major order. For more information about this, see Initializing a Numeric Array with Data.

You can also use the MATLAB API routine, mxCreateDoubleMatrix(), to create a matrix of doubles.

Creating Multidimensional Numeric Arrays.   To create a multidimensional numeric array, use the MATLAB API routine mxCreateNumericArray(). The arguments to this routine are:

• The number of dimensions of the array
• The size of each dimension
• The type of data the array will contain
• Whether the data is real or complex

For example, the following code fragment creates a three-dimensional array, with dimensions 3-by-3-by-2. The mxDOUBLE_CLASS argument specifies that the array should contain double precision values. For a complete list of these class specifiers, use the MATLAB Help Desk to view the mxClass_ID online reference page.

Note in the example that the arguments specifying the number of dimensions, ndim, and the size of these dimensions, dims, do not need to be converted into a MATLAB array. The MATLAB API routines accept integer arguments.

int ndim    = 3;         /* Number of dimensions */
int dims[3] = { 3,3,2 }; /* Size of dimensions   */

mxArray *A = NULL;       /* declare pointer to mxArray */

mlfAssign(&A, mxCreateNumericArray( ndim,  
                                    dims,
                                    mxDOUBLE_CLASS,
                                    mxREAL));

mlfPrintMatrix(A);

mxDestroyArray(A);

This code creates the following 3-by-3-by-2 array.

(:,:,1) =
     0    0    0
     0    0    0
     0    0    0

(:,:,2) =
     0    0    0
     0    0    0
     0    0    0

For information about initializing this array with data, see Initializing a Numeric Array with Data.

Creating Commonly Used Numeric Arrays.   The MATLAB C Math Library includes several routines that create commonly used multidimensional arrays:

• Array of ones, mlfOnes()
• Array of zeros, mlfZeros()
• Identity matrices, mlfEye()
• Random numbers, mlfRand()
• Normally distributed random numbers, mlfRandn()
• Magic squares (limited to two-dimensions), mlfMagic()

With all these routines, the number of dimensions in the resulting array equals the number of non-NULL arguments passed to the routine. To illustrate, the following example passes three arguments to mlfOnes() to create a three dimensional array. Because these routines allow you to create arrays of any number of dimensions, you must signify the end of the argument list by specifying a NULL.

mxArray *A = NULL;    

mlfAssign(&A, mlfOnes( mlfScalar(2),
                       mlfScalar(3),
                       mlfScalar(2),
                       NULL));    

mlfPrintMatrix(A);

mxDestroyArray(A);

This code fragment creates the following array:

(:,:,1) =
     1    1    1
     1    1    1

(:,:,2) =
     1    1    1
     1    1    1

Creating Vectors of Number Sequences..   To create a one dimensional array (vector) that contains a number sequence, use the mlfColon() routine. This routine performs the same function as the MATLAB colon (:) operator.

For example, the following code fragment creates a vector of all the numbers between 1 and 10.

mxArray *A = NULL;

mlfAssign(&A, mlfColon(mlfScalar(1),mlfScalar(10),NULL));

mlfPrintMatrix(A);
mxDestroyArray(A);

This code creates the following output.

1 2 3 4 5 6 7 8 9 10

You can optionally specify an increment between the values in the vector. For more information, see the mlfColon() reference page in the MATLAB C Math Library Reference online documentation.

Creating Numeric Arrays by Calling Arithmetic Routines

The MATLAB C Math Library arithmetic routines create numeric arrays as their output. For example, the sample application in Chapter 2 creates arrays by calling the library arithmetic routines, mlfFactor() and mlfIntersect().

Creating Numeric Arrays by Concatenation

You can create arrays by grouping together existing MATLAB arrays using concatenation. In MATLAB, you use the [] (brackets) operator to concatenate arrays vertically or horizontally. For example, you can use the following syntax in MATLAB to concatenate arrays. In this MATLAB example, the numeric values being concatenated are scalar arrays. The semicolon indicates that you want to create rows for vertical as well as horizontal concatenation.

» A = [ 1 2 3; 4 5 6 ]
A =
   1   2   3
   4   5   6   

The MATLAB C Math Library uses the mlfHorzcat() and mlfVertcat() routines to perform horizontal and vertical concatenation. You nest calls to mlfHorzcat() inside mlfVertcat() to create the same two-dimensional array in a C program.

Note    This code fragment duplicates the preceding MATLAB syntax; however, it is more efficient to create a two dimensional array of constants using mlfDoubleMatrix(), rather than with mlfHorzcat() and mlfVertcat().

mxArray *A = NULL;    
mlfAssign(&A, mlfVertcat(mlfHorzcat(mlfScalar(1),
                                    mlfScalar(2),
                                    mlfScalar(3),
                                    NULL),
                         mlfHorzcat(mlfScalar(4),
                                    mlfScalar(5),
                                    mlfScalar(6),
                                    NULL),
                         NULL ));

mlfPrintMatrix(A);

mxDestroyArray(A);

Creating Multidimensional Numeric Arrays by Concatenation.   Using mlfVertcat() and mlfHorzcat(), you can only create two-dimensional arrays. To create a multidimensional numeric array through concatenation, you must use the mlfCat() routine. As arguments to mlfCat(), you specify the dimensions along which to concatenate the arrays.

For example, the following code fragment creates two matrices, and then concatenates them to create a three-dimensional array.

mxArray *A = NULL;
mxArray *B = NULL;
mxArray *C = NULL;

static double data1[] = { 1, 4, 2, 5, 3, 6 };
static double data2[] = { 7, 10, 8, 11, 9, 12 };

mlfAssign(&A, mlfDoubleMatrix(2, 3, data1, NULL));
mlfAssign(&B, mlfDoubleMatrix(2, 3, data2, NULL));

mlfAssign(&C, mlfCat(mlfScalar(3), A, B, NULL));

mlfPrintMatrix(C);

mxDestroyArray(A);
mxDestroyArray(B);
mxDestroyArray(C);

This program displays the following output.

(:,:,1) =
   1   2   3
   4   5   6   

(:,:,2) =
   7   8   9
  10  11  12

Creating Numeric Arrays by Assignment

You can also create a numeric array by assigning a value to a location in the array, using the mlfIndexAssign() routine. The MATLAB C Math Library creates a numeric array large enough to accommodate the specified location or expands an existing array.

The following example is equivalent to the MATLAB statement,
A(2,2) = 17. The C character string "(?,?)" specifies the format of the index subscript. For more information about array indexing, see Chapter 5.

mxArray *A = NULL;

mlfIndexAssign(&A,
               "(?,?)",            /* Index subscript format */
                mlfScalar(2),mlfScalar(2), /* subscripts     */
                mlfScalar(17));    /* value to be assigned   */

mxDestroyArray(A);

This call creates the array A and fills it with zeros before performing the assignment. The following output shows the array created by this code fragment.

    0    0
    0    17

Numeric Arrays

Initializing a Numeric Array with Data