mlfReturnValue (MATLAB C Math Library)

Mark an array as a return value from a function that uses automated memory management

C Prototype

mxArray *mlfReturnValue(mxArray *a);

Arguments

mxArray *a
Pointer to the array that will be the return value from the current function. The value is typically the result of an assignment made within the function or the value of an output argument set by a function call. These arrays are bound arrays at the time of the call.

If you want to return an array input argument, assign it to a variable first and then pass this bound variable to mlfReturnValue(). Do not pass an array that is an input argument to mlfReturnValue().

Return

Returns the argument passed to mlfReturnValue(), which allows you to nest a call to mlfReturnValue() within the return statement.

Description

mlfReturnValue(), along with mlfEnterNewContext(), mlfRestorePreviousContext(), and mlfAssign(), implement automated memory management in the MATLAB C Math Library. Each function in the library includes calls to these functions. The functions that you write can also use automated memory management by calling these functions.

mlfReturnValue() is used to return a temporary mxArray from a function.

The arrays that are returned from MATLAB C Math Library functions are always temporary. mlfReturnValue() sets the state of the array passed to it to temporary but does not delete the array. By calling it at the end of a function, you can then nest calls to your function and not worry about assigning the mxArray* return from your function to a variable.

You do not need to call mlfReturnValue() if you are writing a function that does not return a pointer to an array.

Example

For a function defined as follows

mxArray *ArrayMemory(mxArray **z_out, mxArray *x_in,
                    mxArray *y_in)

that contains the following assignment to a local variable,

mlfAssign(&result_local,
          mlfSqrt(mlfPlus(mlfSin(x_in), mlfCos(x_in))));

use the following call to mlfReturnValue() to return that local variable from the function as a temporary array.

return mlfReturnValue(result_local);