Working with MATLAB Arrays (Using the C++ Math Library)

Using the C++ Math Library

Creating Numeric Arrays

You can create a numeric array in a C++ program by:

Using an mwArray constructor

Using an array creation routine

Calling an arithmetic routine

Concatenating existing arrays

Assigning a value to an element in an array

The following sections provide more detail about using each of these mechanisms, highlighting areas where the C++ syntax is significantly different from the corresponding MATLAB syntax.

Creating Arrays with C++ Constructors

As a C++ class, the mwArray interface includes many useful constructors that allow you to create many different types of array. There is no MATLAB equivalent for a constructor.

When you declare a mwArray object, as in the following

mwArray A;

you invoke the default constructor which creates a uninitialized array.

Note Do not pass an uninitialized array to a MATLAB C++ Math Library routine. Assign it a value before passing it to a routine.

The mwArray object supports other constructors that accept various combination of arguments that allow you to create numerical scalar arrays or copy an existing array. (For a complete list of all mwArray constructors, see Constructors in Chapter 10.)

The following example uses the mwArray matrix constructor to create an 2-by-3 matrix, initialized to the values in a C++ array of double precision values. You can also use C++ arrays of integers or unsigned short values to initialize a MATLAB mwArray. This constructor can optionally take a second C++ array to initialize the imaginary part of an array of complex numbers. The example then uses the mwArray copy constructor to make a copy of the 2-by-3 array.

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

mwArray C(2, 3, data); // matrix constructor
mwArray D(C);          // make a copy of C

cout << "C =" << C << endl;
cout << "copy of C =" << D << endl;

This code produces the following output:

C = [
       1     2     3;
       4     5     6
  ]
Copy of C = [
       1     2     3;
       4     5     6
  ]

Creating Multidimensional Arrays with Constructors.

You cannot create an array of more than two dimensions using an mwArray constructor. Use an array creation routine or concatenation to create multidimensional arrays. Alternately, you can create a two-dimensional array using a constructor and then change it into a multidimensional array using the reshape() routine. For more information about the reshape() routine, see the online MATLAB C++ Math Library Reference.

Using Array Creation Routines

The MATLAB C++ Math Library provides routines that create commonly used MATLAB arrays, such as arrays of 0's or 1's.

Array filled with ones, ones()

Array filled with zeros, zeros()

An empty array, equivalent to the MATLAB [], empty()

Identity matrices, eye()

Random numbers, rand()

Normally distributed random numbers, randn()

Magic squares (limited to two-dimensions), magic()

When you call these routines, you define the number of dimensions of the array by the number of dimensions you specify as arguments. Given n arguments, the routines return a multidimensional array with the n dimensions. (The eye() routine and the magic() routine only support two dimensional arrays.)

For example, this code fragment creates a 2-by-3-by-2 array of normally distributed random numbers.

mwArray B;

B = randn(2,3,2); // Create 3-d array

cout << "B =" << B << endl;

This code produces the following array:

B =[
(:,:,1) =
   [
   -0.4326    0.1253   -1.1465 ;
   -1.6656    0.2877    1.1909
   ]
(:,:,2) =
   [
    1.1892    0.3273   -0.1867 ;
   -0.0376    0.1746    0.7258
   ]
]

Note You can specify a zero value for any dimension. MATLAB considers any array with a zero dimension an empty array.

Creating Integer Ramps.

In MATLAB, the : (colon) operator can be used as a fast way to create a vector of monotonically increasing numbers. This capability is often used as a wildcard in MATLAB array indexing expressions. The MATLAB C++ Math Library uses two routines to emulates the : operator:

ramp() to create vectors

colon() to specify a range of values in indexing expressions. Unlike the MATLAB colon operator, the colon() routine cannot be used to specify the bounds of a C++ for-loop. For more information about using the colon() routine in array indexing expressions, see Chapter 4.

When you use ramp(), the first argument represents the starting value and the second argument represents the end value. As an example, the following code fragment creates a vector of all the numbers between 1 and 10.

mwArray A = ramp(1,10);

The library also supports the three-argument form of ramp(), where the first argument represents the starting value, the second argument represents the size of the increment between values and the third argument.

Calling MATLAB Arithmetic Routines

As in MATLAB, most of the operators and functions in the MATLAB C++ Math Library create at least one new array as their result. For example, when you multiply two arrays, the result is a new array. This code demonstrates how multiplying a 4-by-4 array of 1's by the 4-by-4 identity matrix creates a new array, C.

mwArray A, B;

A = ones(4);
B = eye(4);

mwArray C = A * B;

C is a new array; the result of the multiplication.

Using Concatenation

Vertical and horizontal concatenation are useful ways to construct arrays of any size and shape. In MATLAB, the concatenation operator ([]) performs both operations. The MATLAB C++ Math Library uses two routines to emulate this operator:

horzcat() concatenates arrays horizontally.

vertcat() concatenates arrays vertically.

Concatenating Horizontally.

In MATLAB, you can horizontally concatenate the scalar arrays 1, 2, 3, 4, 5, and 6 into a vector containing one row and six columns.

A = [ 1 2 3 4 5 6]

A = 

    1 2 3 4 5 6

You can create the same vector in C++ code using horzcat().

mwArray A;

A = horzcat( 1, 2, 3, 4, 5, 6 );

cout << "A = " << A << endl;

This code fragment produces this output:

A = [
        1    2    3    4    5    6
  ]

Concatenating Vertically..

To vertically concatenate the same scalar arrays into a 2-by-2 matrix in MATLAB, insert a semicolon in the list of arrays where you want to create rows:

A = [ 1 2 3; 4 5 6 ]

A =

    1 2 3
    4 5 6

To create this matrix in a C++ program, you must use vertcat(), using nested calls to horzcat() to create the rows.

mwArray A;

A = vertcat( horzcat(1, 2, 3), horzcat(4, 5, 6) );

This code fragment produces this output:

A = [
        1    2    3 ;
        4    5    6
  ]

horzcat() and vertcat() work on vectors and two-dimensional arrays as well as scalars. For example, the following code fragment concatenates the two dimensional arrays A and B to create the two-dimensional array C.

mwArray A = vertcat( horzcat(1, 2, 3), horzcat(4, 5, 6) );
mwArray B = vertcat( horzcat(1, 2, 3), horzcat(4, 5, 6) );
mwArray C = vertcat( A, B );

Horizontally concatenated arrays must have the same number of rows; vertically concatenated arrays must have the same number of columns.

Using Concatenation to Create Arrays of More Than Two Dimensions.

To create arrays of more than two-dimensions through concatenation, use the cat() routine. You cannot create arrays of more than two dimensions using horzcat() and vertcat().

In MATLAB, the cat function concatenates a group of arrays along a specified dimension using the following syntax

B = cat(dim,A1,A2...)

where A1, A2, and so on are the arrays to concatenate, and dim is the dimension along which to concatenate the arrays.

For example, this MATLAB code concatenates the two-dimensional arrays A and B into a three-dimensional array using the cat function.

A = [ 1 1 1; 2 2 2 ];
B = [ 3 3 3; 4 4 4 ];

C = cat(3, A, B)
C(:,:,1) =
     1     1     1
     2     2     2
C(:,:,2) =
     3     3     3
     4     4     4

This code fragment creates the same three-dimensional array in a C++ program:

mwArray A = vertcat( horzcat(1, 1, 1), horzcat(2, 2, 2) );
mwArray B = vertcat( horzcat(3, 3, 3), horzcat(4, 4, 4) );
mwArray C = cat( 3, A, B );

cout << "C =" << C << endl;

This code produces the following output:

C =[
(:,:,1) =
  [
     1     1     1;
     2     2     2
  ]
(:,:,2) =
  [
     3     3     3;
     4     4     4
  ]
]

If the number of dimensions you specify in dim is greater than the number of arrays you specify as arguments, cat automatically adds subscripts of 1 between dimensions, if necessary. For example, if you change cat(3,A,B) to cat(4,A,B), the code produces the following output. Note the added dimension in the index subscripts.

C =[
(:,:,1,1) =
  [
     1     1     1 ;
     2     2     2
  ]
(:,:,1,2) =
  [
     3     3     3 ;
     4     4     4
  ]
]

Using Assignment

You can create scalar arrays using the C++ assignment (=) operator. For example, the following C++ code creates an array named A and assigns the value 5 to A.

mwArray A = 5;

The result of this assignment is a 1-by-1 array (one row, one column) containing the single number 5.0 represented in double-precision floating-point format.

You can assign a nonscalar value to a variable that contains a scalar array, or a scalar value to a variable that contains a nonscalar array. In both cases, the MATLAB C++ Math Library manages the memory associated with each array to ensure that there are no memory leaks.

You can also create string arrays using the C++ assignment operator. The following C++ code creates an array named A and assigns the value "abcd" to A.

mwArray A = "abcd";

Creating Multidimensional Arrays By Assignment.

You can create multidimensional arrays using indexed assignment statements. You use MATLAB array indexing to specify a location in an array. MATLAB creates the array (or extends an existing array) to accommodate the location specified.

For example, the following assignment statement creates a new three dimensional array by assigning a single value to the location specified by row 2, column 2, page 2. MATLAB fills the elements of the array with zeros before making the assignment.

H(2,2,2) = 5

H(:,:,1) =
     0     0
     0     0
H(:,:,2) =
     0     0
     0     5

The MATLAB C++ Math Library supports this same syntax. You can create a multidimensional array by assigning a value to a location in the array. The library creates an array (or extends an existing array) to accommodate the location. The following C++ code fragment creates the same three dimensional array.

mwArray H;
H(2,2,2) = 5;

Note Do not declare an array and perform an indexed assignment in the same statement. The statement mwArray H(2,2,2)= 5 is not valid.

Numeric Arrays Initializing a Numeric Array with Data