mwArray Class (MATLAB C++ Math Library)

The mwArray class public interface is relatively small, consisting of constructors and destructor, overloaded new and delete operators, one user-defined conversion, four indexing operators, the assignment operator, input and output operators, and array size query routines. The mwArray's public interface does not contain any mathematical operators or functions.

See "Extracting Data from an mwArray" in Chapter 10 of the MATLAB C++ Math Library User's Guide for documentation of the member functions GetData(), SetData(), ExtractScalar(), ExtractData(), and ToString().

Constructors

The mwArray interface provides many useful constructors. You can construct an mwArray object from the following types of data: a numerical scalar, an array of scalars, a string, an mxArray *, or another mwArray object.

mwArray()

Create an uninitialized array. An uninitialized array produces warnings when passed to MATLAB C++ Math Library functions. If an array is created using this default constructor, a value must be assigned to it before passing it to a MATLAB C++ Math Library function.

To create an empty double matrix that corresponds to [] in MATLAB, use the function empty().

mwArray(const char *str)

Create an array from a string. The constructor copies the string.

mwArray(int32 rows, int32 cols, double *real, double *imag = 0):
Create an mwArray from either one or two arrays of double-precision floating-point numbers. If two arrays are specified, the constructor creates a complex array; both input arrays must be the same size. The data in the input arrays must be in column-major order, the reverse of C++'s usual row-major order. This constructor copies the input arrays.

Note that the last argument, imag, is assigned a value of zero in the constructor. imag is an optional argument. When you call this constructor, you do not need to specify the optional argument. Refer to a C++ reference guide for a more complete explanation of default arguments.

mwArray(const mwArray &mtrx)

Copy an mwArray. This constructor is the familiar C++ copy constructor, which copies the input array. For efficiency, this routine does not actually copy the data until the data is modified. The data is referenced through a pointer until a modification occurs.

mwArray(const mxArray *mtrx)

Make an mwArray from an mxArray *, such as might be returned by any of the routines in the MATLAB C Math Library or the Application Program Interface Library. This routine does not copy its input array, yet the destructor frees it; therefore the input array must be allocated on the heap. In most cases, for example, with matrices returned from the Application Program Interface Library, this is the desired behavior.

mwArray(double start, double step, double stop)

Create a ramp. This constructor operates just like the MATLAB colon operator. For example, the call mwArray(1, 0.5, 3) creates the vector
[ 1, 1.5, 2, 2.5, 3 ].

mwArray(int32 start, int32 step, int32 stop)

Create an integer ramp.

mwArray(const mwSubArray & a)

Create an mwArray from an mwSubArray. When an indexing operation is applied to an array, the result is not another array, but an mwSubArray object. An mwSubArray object remembers the indexing operation. Evaluation of the operation is deferred until the result is assigned or used in another expression. This constructor evaluates the indexing operation encoded by the mwSubArray object and creates the appropriate array.

mwArray(double)

Create a 1-by-1 mwArray from a double-precision floating-point number.

mwArray(int)

Create an mwArray from an integer.

Operators

The three types of operators are indexing, stream I/O, and assignment.

Array Indexing

Indexing is implemented through the complex interaction of three classes: mwArray, mwSubArray, and mwIndex. The indexing operator is (), and its usual argument is an mwIndex, which can be made from a scalar or another array. When applied to an mwArray, operator() returns an mwSubArray. The mwSubArray ``remembers'' the indexing operation and defers evaluation until the result is either assigned or referred to.

The MATLAB C++ Math Library supports one- and two-dimensional indexing.

mwSubArray operator()(const mwIndex &a) const

This routine implements one-dimensional indexing with an mwIndex object providing the subscript.

mwSubArray operator()(const mwIndex &a)

This routine modifies the contents of an array using one-dimensional indexing. Because this routine is non-const, calls to it are valid targets for the assignment operator.

mwSubArray operator()(const mwIndex &a, const mwIndex &b) const

This is the most general form of two-dimensional indexing. Because mwIndex objects can be made from integers, double-precision floating-point numbers and even mwArrays, this routine can handle two-dimensional indexing of any type.

mwSubArray operator()(const mwIndex &a, const mwIndex &b)

Like its one-dimensional counterpart, this routine allows two-dimensional indexing expressions as the target of assignment statements.

Cell Content Indexing

These two versions of the cell() member function let you index into the contents of a cell. For example, A.cell(1,2) refers to the contents of the cell in the second column of the first row in an array A.

The cell() member functions follow the library convention for varargin functions. You can pass up to 32 arguments to the functions. To index into more than 32 dimensions, you must construct an mwVarargin object and pass it as the first argument. That object allows you to reference an additional 32 arguments, the first of which can again be an mwVarargin object.

The second non-const signature supports calls that are targets of the assignment operator and modify the contents of a cell.

mwArray cell(const mwVarargin &RI1,
             const mwArray &OI2=mwArray::DIN,
             const mwArray &OI3=mwArray::DIN,
             .
             .
             .
             const mwArray &OI32=mwArray::DIN ) const;
mwSubArray cell(const mwVarargin &RI1,
             const mwArray &OI2=mwArray::DIN,
             const mwArray &OI3=mwArray::DIN,
             .
             .
             .
             const mwArray &OI32=mwArray::DIN );

Structure Field Indexing

The two versions of the field() member function let you reference the field of a structure. For example, A.field("name") accesses the contents of the field called name within the structure A.

The second non-const signature supports calls that are targets of the assignment operator and modify the contents of a field.

mwArray field(const char *fieldname) const;
mwSubArray field(const char *fieldname);

Stream I/O

The two operators, << and >>, are used for stream input and output. Technically, these stream operators are not member functions; they are friend functions.

friend inline ostream& operator<<(ostream &os, const mwArray&)

Calling this operator inserts an mwArray object into the given stream. If the stream is cout, the contents of the mwArray object appear on the terminal screen or elsewhere if standard output has been redirected on the command line. This function simply invokes Write() as described below.

friend inline istream& operator>>(istream &is, mwArray&)

This is the stream extraction operator, capable of extracting, or reading, an mwArray from a stream. The stream can be any C++ stream object, for example, standard input, a file, or a string. This function simply invokes Read() as described below.

The stream operators call Read() and Write(), mwArray public member functions.

void Read(istream&)

Reads an mwArray from an input stream. An array definition consists of an optional scale factor and asterisk, *, followed by a bracket [, one or more semicolon-separated rows of double-precision floating-point numbers, and a closing bracket ].

void Write(ostream&, int32 precision =5, int32 line_width =75) const

Formats mwArray objects using the given precision (number of digits) and line width, and then writes the objects into the given stream. operator<<() uses the default values shown above, which are appropriate for 80-character-wide terminals.

Note Write() writes arrays in exactly the format that Read() reads them. An array written by Write() can be read by Read().

Assignment

mwArray &operator=(const mwArray&);
The final operator, =, is the assignment operator. C++ requires that the assignment operator be a member function. Like the copy constructor, the assignment operator does not actually make a copy of the input array, but rather references (keeps a pointer to) the input array's data; this is an optimization made purely for efficiency, and has no effect on the semantics of assignment. If you write A = B and then modify B, the values in A will remain unchanged.

User-Defined Conversion

There is only one user-defined conversion: from an mwArray to a double-precision floating-point number. This conversion function only works if the mwArray is scalar (1-by-1) and noncomplex.

operator double() const;

Memory Management

Overloading the operators new and delete provides the necessary hooks for user-defined memory management. The MATLAB C++ Math Library has its own memory management scheme.

If this scheme is inappropriate for your application, you can modify it. However, you should not do so by overloading new and delete, because the mwArray class already contains overloaded versions of these operators.

void *operator new(size_t size)

void operator delete(void *ptr, size_t size)

Array Size

In MATLAB, the size() function returns the size of an array as an array. The MATLAB C++ Math Library provides a corresponding version of size() that also returns an array. Because this C++ version allocates an array to hold just two integers, it is not efficient. The mwArray Size member functions below return the size of an array more efficiently.

An array (a matrix is a special case) has two sizes: the number of its dimensions (for matrices, always two) and the actual size of each dimension. You can use these Size() functions to determine both the number of dimensions and the size of each dimension.

int32 Size() const

Return the number of dimensions. In this version of the library, this function always returns two.

int32 Size(int32 dim) const

Return the size (number of elements) of the indicated dimension. The integer argument to this function must be either 1 or 2.

int32 Size(int32* dims, int maxdims=2) const

Determine the sizes of all the dimensions of the array and return them via the given integer array, dims. maxdims is the maximum number of dimensions the function should return. The input integer array dims must contain enough space to store at least maxdims integers. If maxdims is less than the number of dimensions of the mwArray, the last dimension returned is the product of the remaining dimensions. This function's return value is the number of dimensions of the mwArray.

[ Previous | Help Desk | Next ]