MATLAB Application Program Interface Reference

Get the real component of an mxArray's first data element

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

Arguments

array_ptr

Pointer to an mxArray other than a cell mxArray or a structure mxArray.

Returns

The value of the first real (nonimaginary) element of the mxArray. Notice that mxGetScalar returns a double. Therefore, if real elements in the mxArray are stored as something other than doubles, mxGetScalar automatically converts the scalar value into a double. To preserve the original data representation of the scalar, you must cast the return value to the desired data type.

If array_ptr points to a structure mxArray or a cell mxArray, mxGetScalar returns 0.0.

If array_ptr points to a sparse mxArray, mxGetScalar returns the value of the first nonzero real element in the mxArray.

If array_ptr points to an empty mxArray, mxGetScalar returns an indeterminate value.

Description

Call mxGetScalar to get the value of the first real (nonimaginary) element of the mxArray.

In most cases, you call mxGetScalar when array_ptr points to an mxArray containing only one element (a scalar). However, array_ptr can point to an mxArray containing many elements. If array_ptr points to an mxArray containing multiple elements, mxGetScalar returns the value of the first real element. If array_ptr points to a two-dimensional mxArray, mxGetScalar returns the value of the (1,1) element; if array_ptr points to a three-dimensional mxArray, mxGetScalar returns the value of the (1,1,1) element; and so on.

Examples

Get the first real element of the first two input arguments to a MEX-file:

void
mexFunction(int nlhs,mxArray *plhs[],int nrhs,const mxArray 
*prhs[])
{
 double interest_rate, starting_principal; 

      interest_rate = mxGetScalar(prhs[0]);
      starting_principal = mxGetScalar(prhs[1]);
   ...

mxGetScalar does not return imaginary data. The easiest way to get an imaginary scalar is to dereference the pointer returned by mxGetPi. For example, consider the MEX-file entitled ImagScal:

void
mexFunction(int nlhs,mxArray *plhs[],int nrhs,const mxArray 
*prhs[])
{
 double  imag_scalar; 
 double *ptr_to_start_of_imag_data;

    ptr_to_start_of_imag_data = mxGetPi(prhs[0]); 
    imag_scalar = *ptr_to_start_of_imag_data;
    mexPrintf("The first imag element is %g\n", imag_scalar);
   ...

Given an mxArray named b containing some imaginary elements

>> b = sqrt([-5 -3; 7 -8]);
>> ImagScal(b)
The first imaginary element is 2.23607

For additional examples, see mxGetScalar.c and mxGetScalar2.c in the mx subdirectory of the examples directory.