mxGetName (MATLAB Application Program Interface)

Get the name of the specified mxArray

#include "matrix.h"
const char *mxGetName(const mxArray *array_ptr);

Arguments

array_ptr
Pointer to an mxArray.

Returns

A pointer to the start of the name field. If the mxArray has no name, the first element in the name field is \0.

Description

Use mxGetName to determine the name of the mxArray that array_ptr points to.

The returned name is a NULL-terminated character string. MATLAB variable names are stored in fixed-length character arrays of length mxMAXNAM+1, where mxMAXNAM is defined in the file mxArray.h. Thus variable names can by any length up to mxMAXNAM. The actual length is determined by the NULL terminator.

mxGetName passes back a pointer to an existing section of memory; therefore, your application should not allocate space to hold the returned name string. Do not attempt to deallocate or free the returned string.

Examples

Consider a MEX-file named ret_name that returns the name of the first input mxArray

void
mexFunction(int nlhs,mxArray *plhs[],int nrhs,const mxArray 
*prhs[])
{
 const char *array_name; 

    array_name = mxGetName(prhs[0]); 
    if (*array_name == '\0') 
      mexPrintf("This mxArray is unnamed.");
    else
      mexPrintf("The name of this mxArray is %s.\n", array_name);
}

If you pass a named mxArray to ret_name, then ret_name prints the mxArray's name; for example:

>> crandon = rand(6, 1);
>> ret_name(myarray)
The name of this mxArray is crandon.

However, passing an unnamed mxArray

>> mxGetName(rand(6,1))
This mxArray is unnamed.

For an additional example, see mxgetname.c in the mx subdirectory of the examples directory.