mxGetPi (MATLAB Application Program Interface)

Get an mxArray's imaginary data elements

#include "matrix.h"
double *mxGetPi(const mxArray *array_ptr);

Arguments

array_ptr
Pointer to an mxArray.

Returns

The imaginary data elements of the specified mxArray, on success. Returns NULL if there is no imaginary data or if there is an error.

Description

The pi field points to an array containing the imaginary data of the mxArray. Call mxGetPi to get the contents of the pi field; that is, to get the starting address of this imaginary data.

The best way to determine if an mxArray is purely real is to call mxIsComplex.

The imaginary parts of all input matrices to a MATLAB function are allocated if any of the input matrices are complex.

Examples

Consider a MEX-file named MyImag that displays the contents of the imaginary component of the {3, 1, 2} element of a three-dimensional mxArray

#include "mex.h"

void
mexFunction(int nlhs,mxArray *plhs[],int nrhs,const mxArray 
*prhs[])
{
 double *imag_data_ptr, imag_value;
 int     nsubs=3, subs[]={3, 1, 2}, index;
  
 /* The input array must be mxDOUBLE_CLASS. */
   if (mxIsDouble(prhs[0]))  { 
     /* Get starting address of imaginary data in input array. */
       imag_data_ptr = (double *)mxGetPi(prhs[0]);
     
     /* Get index to {3, 1, 2}. */  
       index = mxCalcSingleSubscript(prhs[0], nsubs, subs);

     /* Get the imaginary component at {3, 1, 2} */
       imag_value = *(imag_data_ptr + index); 
       mexPrintf("%g\n", imag_value);
   } 
   else
      mexErrMsgTxt("First argument must be a double array.");
}

In MATLAB, create a three-dimensional mxArray named t containing imaginary data parts:

>> t=sqrt(randn(4, 4, 6));

Call MyImag, passing t as an argument

>> MyImag(t)
0.395875

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