mexPutArray (MATLAB Application Program Interface)

Copy an mxArray from your MEX-file into another workspace

C Syntax

#include "mex.h"
int mexPutArray(mxArray *array_ptr, const char *workspace);

Arguments

array_ptr
Pointer to an mxArray.

workspace
Specifies the scope of the array that you are copying. The possible values are


`"base"`	Copy `name` to the current MATLAB workspace.
`"caller"`	Copy `name` to the workspace of whatever entity (M-file, another MEX-file, MATLAB workspace) actually called this MEX-file.
`"global"`	Copy `name` to the list of global variables.

Returns

0 on success; 1 on failure. A possible cause of failure is that array_ptr is NULL. Another possibility is that array_ptr points to an mxArray that does not have an associated name. (Call mxSetName to associate a name with array_ptr.)

Description

Call mexPutArray to copy the specified mxArray from your MEX-file into another workspace. mexPutArray makes the specified array accessible to other entities, such as MATLAB, M-files or other MEX-files.

It is easy to confuse array_ptr with a variable name. You manipulate variable names in the MATLAB workspace; you manipulate array_ptrs in a MEX-file. When you call mexPutArray, you specify an array_ptr; however, the recipient workspace appears to receive a variable name. MATLAB determines the variable name by looking at the name field of the received mxArray.

If a variable of the same name already exists in the specified workspace, mexPutArray overwrites the previous contents of the variable with the contents of the new mxArray. For example, suppose the MATLAB workspace defines variable Peaches as

Peaches
1     2     3     4

and you call mexPutArray to copy Peaches into the MATLAB workspace:

mxSetName(array_ptr, "Peaches")
mexPutArray(array_ptr, "base")

Then, the old value of Peaches disappears and is replaced by the value passed in by mexPutArray.

Example

See mexgetarray.c in the mex subdirectory of the examples directory.