MATLAB Application Program Interface Reference Help Desk

mexGetArrayPtr

Purpose

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

C Syntax

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.

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

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

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.

See Also

mexGetArray



[ Previous | Help Desk | Next ]