| Using the C Math Library | |
Initializing a Numeric Array with Data
You can specify the value of elements in an array using mlfIndexAssign(). However, if you want to assign values to many elements in an array, this method can become tedious.
The fastest way to initialize a MATLAB array is to obtain a pointer to the data area in the mxArray data type and copy data to this location. You use the MATLAB API routine mxGetPr() to retrieve this pointer and copy your data to this location using the standard C memcpy() routine. The API also includes a routine, mxGetPi(), that lets you initialize the imaginary part of an array in the same way.
The following example illustrates this procedure, which is a common MATLAB C Math Library programming idiom. Note that MATLAB API routines accept integer arguments.
int ndim = 3;
int dims[3] = {3,3,2};
int bytes_to_copy = (3 * 3 * 2) * sizeof(double);
double data[] = { 1,4,7,2,5,8,3,6,9,10,13,16,11,14,17,12,15,18};
double *pr = NULL;
mxArray *A = NULL;
/* create the array */
mlfAssign(&A ,mxCreateNumericArray( ndim,
dims,
mxDOUBLE_CLASS,
mxREAL));
/* get pointer to data in array */
pr = mxGetPr(A);
/* copy data to pointer */
memcpy(pr, data, bytes_to_copy);
mlfPrintMatrix(A);
mxDestroyArray(A);
This program displays the following output.
(:,:,1) = 1 2 3 4 5 6 7 8 9 (:,:,2) = 10 11 12 13 14 15 16 17 18
Column-Major Storage versus Row-Major Storage
It is important to note in the previous example that the MATLAB C Math Library stores its arrays in column-major order, unlike C, which stores arrays in row-major order. Static arrays of data that are declared in C and that initialize MATLAB C Math Library arrays must store their data in column-major order. For this reason, we recommend not using two-dimensional C language arrays to initialize a MATLAB array because the mapping of array elements from C to MATLAB can become confusing.
As an example of the difference between C's row-major array storage and MATLAB's column-major array storage, consider a 3-by-3 matrix filled with the numbers from one to nine.
1 4 7 2 5 8 3 6 9
Notice how the numbers follow one another down the columns. If you join the end of each column to the beginning of the next, the numbers are arranged in counting order.
To recreate this structure in C, you need a two-dimensional array.
static double square[][3] = {{1, 4, 7}, {2, 5, 8}, {3, 6, 9}};
Notice how the numbers are specified in row-major order; the numbers in each row are contiguous. In memory, C lays each number down next to the last, so this array might have equivalently (in terms of memory layout) been declared.
static double square[] = {1, 4, 7, 2, 5, 8, 3, 6, 9};
To a C program, these arrays represent the matrix first presented: a 3-by-3 matrix in which the numbers from one to nine follow one another in counting order down the columns.
However, if you initialize a 3-by-3 MATLAB mxArray structure with either of these C arrays, the results will be quite different. MATLAB stores its arrays in column-major order. MATLAB treats the first three numbers in the array as the first column, the next three as the second column, and the last three as the third column. Each group of numbers that C considers to be a row, MATLAB treats as a column.
To MATLAB, the C array above represents this matrix.
1 2 3 4 5 6 7 8 9
Note how the rows and columns are transposed.
To construct a matrix where the counting order proceeds down the columns rather than across the rows, the numbers need to be stored in the C array in column-major order.
static double square[] = {1, 2, 3, 4, 5, 6, 7, 8, 9};
This C array, when used to initialize a MATLAB array, produces the desired result.
| | Creating Numeric Arrays | Example Program: Creating Numeric Arrays (ex1.c) | |