MATLAB Application Program Interface Reference

Copy an mxArray from your MEX-file into another workspace

#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. 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.

.

`"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.

Examples

Consider a MEX-file named Cre8Fibs that creates a vector named Fibs containing the first 10 Fibonacci numbers. Cre8Fibs calls mexPutArray to place Fibs into the MATLAB workspace.

void
mexFunction(int nlhs,mxArray *plhs[],int nrhs,const mxArray 
*prhs[])
{
 double    pr[10];
 mxArray  *array_ptr;
 int       c; 
 int       status;
/* Generate the first 10 Fibonacci numbers. */ 
   pr[0]=1; pr[1]=1; 
   for (c=2; c<10; c++) 
      pr[c] = pr[c-1] + pr[c-2]; 
/* Create an mxArray named Fibs seeded to pr. */
   array_ptr = mxCreateDoubleMatrix(0, 0, pr, NULL);
   mxSetM(array_ptr, 1);
   mxSetN(array_ptr, 10);
   mxSetPr(array_ptr, pr);
   mxSetPi(array_ptr, NULL);
/*   mxSetName(array_ptr, "Fibs"); */
/* Put "Fibs" into the MATLAB workspace. */
   status = mexPutArray(array_ptr, "base");
   printf("status = %d\n", status);
}

Running Cre8Fibs from MATLAB places Fibs into the MATLAB workspace, for example:

>> Cre8Fibs
>> Fibs
1     1     2     3     5     8    13    21    34    55

For an additional example, see mexPutArray.c in the mex subdirectory of the examples directory.