MATLAB Application Program Interface Reference

Get a read-only pointer to a variable from another workspace

#include "mex.h"
const mxArray *mexGetArrayPtr(const char *name,
   const char *workspace);

Arguments

name

Name of a variable in another workspace. (Note that this is a variable name, not an mxArray pointer.)

workspace

Specifies which workspace you want mexGetArrayPtr to search. The three possible values are

"base" Search the current variables of MATLAB.
"caller"
Search the current variables of whatever entity (M-file, another MEX-file, MATLAB workspace) called this MEX-file.

"global"
Search the current global variables of MATLAB only.

`"base"`	`Search the current variables of MATLAB.`
`"caller"`	Search the current variables of whatever entity (M-file, another MEX-file, MATLAB workspace) called this MEX-file.
`"global"`	Search the current global variables of MATLAB only.

Returns

A read-only pointer to name on success. Returns NULL on failure.

Description

Call mexGetArrayPtr to get a read-only copy of the specified variable name into your MEX-file's workspace. This command is useful for examining an mxArray's data and characteristics, but useless for changing them. If you need to change data or characteristics, call mexGetArray instead of mexGetArrayPtr. If you simply need to examine data or characteristics, mexGetArrayPtr offers superior performance as the caller need pass only a pointer to the array. By contrast, mexGetArray passes back the entire array.

Examples

Consider a MEX-file named FrstLst that displays the value of the first and last elements of the Limes variable

void
mexFunction(int nlhs,mxArray *plhs[],int nrhs,const mxArray 
*prhs[])
{
 const mxArray  *array_ptr;
 double   *pr, value_of_first_element, 
value_of_last_element;
 int       dims[5];
 int       num_elements;
 
/* Get the array "Limes" from the MATLAB workspace. */ 
   array_ptr = mexGetArrayPtr("Limes", "base");
   if (array_ptr == NULL)
     mexErrMsgTxt("Could not get Limes from MATLAB 
workspace.");

/* Display the value of first and last element of Limes. */
   pr = (double *)mxGetPr(array_ptr);
   value_of_first_element = *pr;
   num_elements = mxGetM(array_ptr) * mxGetN(array_ptr);
   value_of_last_element = *(pr + (num_elements - 1));
   mexPrintf("First: %g\n", value_of_first_element);
   mexPrintf("Last:  %g\n", value_of_last_element); 
   
}

Create a Limes variable containing a lot of data. Then, call FrstLst

>> Limes=magic(499);
>> FrstLst 
First: 124752
Last:  124250

If FrstLst calls mexGetArray instead of mexGetArrayPtr, then all 249,001 elements of Limes are copied. By calling mexGetArrayPtr, the only thing that gets copied is the address of the start of the Limes array.

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