| C Math Library Reference | |
Assign an array value to a variable
C Prototype
mxArray *mlfAssign(mxArray *volatile *dest, mxArray *src);
Arguments
mxArray **dest
The address of a pointer to the target array (the left-hand side of an assignment statement). You must initialize *dest to NULL or to a valid array.
Return
Returns *dest, the pointer to the target array.
Description
By default, all the arrays returned by the MATLAB C Math Library routines are temporary arrays. This allows you to nest calls to library routines as arguments to other routines. You do not need to deallocate the arrays returned by the nested calls; the library routines delete them automatically. (Arrays that are returned by routines that you write, using mlfReturnValue(), are also temporary.)
To make an array persist, you must bind the array to a variable using the mlfAssign() routine. This routine replaces the standard C assignment operator (=). You must explicitly free arrays that are bound to variables.
mlfAssign() assigns src to *dest. src points to the source array. *dest is equivalent to the left-hand side of an assignment statement. src is equivalent to the right-and side of an assignment statement.
If *dest already points to a valid array, mlfAssign() destroys that array before assigning the source array to it. However, if *dest points to an input argument to the current function, different rules apply. If *dest points to a temporary array, it is destroyed; if it points to a bound array, the assignment does not take place.
Functions that take output arguments (mxArray** arguments), including the indexed assignment functions, follow the same rules as mlfAssign() when deleting existing valid arrays.
If src, the right-hand side of the assignment, points to a bound array, *dest, receives a copy of the array. The copy is a shared-data copy. The actual data associated with the array is not copied until a function modifies the data in the array, for example, a call to mlfIndexAssign() modifies two rows of an array. At that point the data itself is copied to the array before the modifications are made, and the array is no longer points to shared data.
mlfIndexAssign(&B, "(?,?)", mlfScalar(2), mlfScalar(2), mlfScalar(0));
modifies the value at position (2,2) in array B. At that point, the library copies the data to itself before the modifications are made, and the array no longer points to shared data.
Shared data itself is not freed until all arrays that use the data have been destroyed. The functions mxGetPr() and mxGetPi() that access data stored in an array directly handle shared data correctly; mxSetPr() and mxSetPi() modify the data correctly.
Example
This code assigns the matrix product of array Q and array R to *Z
mlfAssign(&Z, mlfMtimes(Q, R));
where Q, R, and Z are mxArray* variables. Z is initialized to NULL and Q and R point to existing arrays.
If you decide not to use the automated memory management features of the library, this code performs the same matrix multiplication.
Z = mlfMtimes(Q, R);
See Also
| | mlfArrayRef | mlfColon | |