Main Content

mxMakeArrayReal (C)

Convert complex mxArray to real, preserving real data

expand all in page

C Syntax

#include "matrix.h"
int mxMakeArrayReal(mxArray *pa);

Description

Use mxMakeArrayReal to convert a complex mxArray to a real mxArray. The array contains the data from the real part of the original array. If the original mxArray is real, then the function does nothing.

Input Arguments

expand all

Pointer to a numeric mxArray array.

Output Arguments

expand all

Function status, returned as int. If successful, then the function returns 1.

Returns 0 if unsuccessful. The function is unsuccessful if pa is NULL, nonnumeric, or read-only.

Examples

Suppose that your application determines that real numbers are the only meaningful result. If complex results occur because of noise in the data, then the program drops small imaginary parts. However, if the imaginary part exceeds a threshold, then the program throws an error.

In the following example dropComplexIfUnderThreshold.c, the threshold limit is set to .2.

#include "mex.h"

/* dropComplexIfUnderThreshold converts input to a real double scalar 
 * with eihter no imaginary data or imaginary data less than
 * the value of LIMIT.
 *
 * Use this function for data with imaginary values less than some LIMIT 
 * that can be dropped, and then revert the results to a real array. 
 *
 * Usage: B = dropComplexIfUnderThreshold(A); 
 * Where:
 *    A is a mxDOUBLE_CLASS scalar complex or real.
 *    B is a real scalar which is a copy of the real value of A.
 *
 * Errors if:
 *    nlhs != 1
 *    nrhs != 1
 *    prhs[0] is not a mxDOUBLE_CLASS scalar
 *    imaginary data value is equal or greater than LIMIT
 *
 * Build:
 *   mex -R2018a dropComplexIfUnderThreshold.c     - interleaved complex API
 *   mex [-R2017b] dropComplexIfUnderThreshold.c   - separate complex API
 *
 * Run:
 * >> dropComplexIfUnderThreshold(3)           
 * ans = 3
 *
 * >> dropComplexIfUnderThreshold(complex(3,.1)) 
 * ans = 3
 *
 * >> dropComplexIfUnderThreshold(complex(1,.2)) 
 * Error using dropComplexIfUnderThreshold
 * Data error.
 * >>
 */
void mexFunction( int nlhs, mxArray *plhs[],
                  int nrhs, const mxArray *prhs[] )
{
#define LIMIT .2
    
    /* check for the proper number of arguments */
    if(nrhs != 1) {
        mexErrMsgIdAndTxt("MATLAB:dropComplexIfUnderThreshold:checkrhs","1 input required.");
    }

    if(nlhs > 1) {
        mexErrMsgIdAndTxt("MATLAB:dropComplexIfUnderThreshold:checklhs","Too many output arguments.");
    }

    if( !(mxIsDouble(prhs[0]) && mxIsScalar(prhs[0])) ) {
        mexErrMsgIdAndTxt("MATLAB:dropComplexIfUnderThreshold:checkdouble","rhs[0] must be double scalar.");
    }
    
    plhs[0] = mxDuplicateArray(prhs[0]);
    
    if(mxIsComplex(prhs[0])) {
#if MX_HAS_INTERLEAVED_COMPLEX
        mxComplexDouble *dt = mxGetComplexDoubles(prhs[0]);

        /* test imaginary data for significance */
        if( dt[0].imag < LIMIT) {
            mxMakeArrayReal(plhs[0]);
        }
        else {
            mexErrMsgIdAndTxt("MATLAB:dropComplexIfUnderThreshold:outOfBounds","Data error.");
        }
#else
        mxDouble *dt = mxGetPi(plhs[0]);

        /* test imaginary data for significance */
        if (dt[0] < LIMIT) {
            mxFree(mxGetPi(plhs[0]));
            mxSetPi(plhs[0], 0);
        } else {
            mexErrMsgIdAndTxt("MATLAB:dropComplexIfUnderThreshold:outOfBounds","Data error.");
        }
#endif
    }
}

To build the MEX file, type:

mex -R2018a dropComplexIfUnderThreshold.c

To test the function, type:

dropComplexIfUnderThreshold(3)
ans = 3
dropComplexIfUnderThreshold(complex(3,.1))
ans = 3
dropComplexIfUnderThreshold(complex(1,.2))
Error using dropComplexIfUnderThreshold
Data error.

Version History

Introduced in R2018a

See Also