Main Content

coder.ceval

Call C/C++ function from generated code

Description

example

out = coder.ceval(functionName,arg1,...,argN) calls the C/C++ function specified in functionName from the generated code. One or more input arguments can be passed to the called C/C++ function within the function call. The called C/C++ function can return a single scalar output. For example, to call the C standard function isalnum with input myChar and output isNum, use isnum = coder.ceval("isalnum",myChar).

Because the type of the output returned by the C/C++ function is not known by the code generator at code generation time, you must specify the type of out (for example, by assigning it a dummy value) before the coder.ceval call. Variables to hold nonscalar output can be passed by reference to the called C/C++ function by using coder.ref (MATLAB Coder) or coder.wref (MATLAB Coder).

To call C/C++ standard functions, you must specify the header file using coder.cinclude (MATLAB Coder) or the "-headerfile" argument to coder.ceval. To call custom C/C++ functions, in addition to specifying the header file, you must also specify the external source file or library using coder.updateBuildInfo (MATLAB Coder).

The coder.ceval function can only be used in the generated code. Calls to coder.ceval in MATLAB® execution produce an error. To determine if a MATLAB function is executing in MATLAB, use coder.target (MATLAB Coder).

example

out = coder.ceval(options,functionName,arg1,...,argN) calls the C/C++ function specified in functionName from the generated code using the options specified in the options argument. For example, use "-headerfile" to specify a C/C++ header file, and use "-global" to indicate that the called C/C++ function uses global variables.

Examples

collapse all

Use coder.ceval to call the C standard library function cosh() from the generated code.

Create a MATLAB function callCosh that takes an input of type double, representing an angle in radians, and calculates the hyperbolic cosine of that angle using the C function cosh(). Call cosh() using coder.ceval and use coder.cinclude to include the math.h header file in which cosh() is defined. Enclose math.h in angle brackets <> to identify math.h as a C standard header file.

Because the type of the output returned by the coder.ceval call is unknown at code generation time, you must convert the output of the coder.ceval call to a known type by assigning the output to a variable whose type is already defined by prior assignment. Without this prior assignment, code generation fails.

Calls to coder.ceval in MATLAB execution produce an error. Use coder.target (MATLAB Coder) to make sure that callCosh is executing in the generated code before the call to coder.ceval.

type callCosh.m
function out = callCosh(x)
arguments
    x (1,1) double
end
out = 0; % assign a dummy value to specify variable type
if coder.target("MATLAB")
    disp("This function not supported in MATLAB execution");
else
    coder.cinclude("<math.h>")
    out = coder.ceval("cosh",x);
end
end

Test callCosh in MATLAB. callCosh does not call coder.ceval.

x = callCosh(1);
This function not supported in MATLAB execution

Generate a MEX function for callCosh.

codegen callCosh
Code generation successful.

Test the generated MEX function callCosh_mex using an angle of π radians. Because callCosh executes in the generated code, the call to coder.ceval does not error.

callCosh_mex(pi)
ans = 11.5920

Generate C code for callCosh and inspect the generated code. The generated C function includes a call to cosh().

codegen -config:lib callCosh
Warning: Code generation is using a coder.EmbeddedCodeConfig object. Because
Embedded Coder is not installed, this might cause some Embedded Coder features
to fail.

Code generation successful (with warnings): To view the report, open('codegen/lib/callCosh/html/report.mldatx')
type(fullfile("codegen","lib","callCosh","callCosh.c"))
/*
 * File: callCosh.c
 *
 * MATLAB Coder version            : 24.1
 * C/C++ source code generated on  : 12-Feb-2024 20:57:41
 */

/* Include Files */
#include "callCosh.h"
#include <math.h>

/* Function Definitions */
/*
 * Arguments    : double x
 * Return Type  : double
 */
double callCosh(double x)
{
  /*  assign a dummy value to specify variable type */
  return cosh(x);
}

/*
 * File trailer for callCosh.c
 *
 * [EOF]
 */

Call the C functions fopen(), fclose(), and fscanf() from the generated code using coder.ceval, and use these functions to read the first line of a text file containing comma-separated values. The MATLAB equivalents of these C functions, fopen, fclose, and fscanf, are supported for code generation. This example shows how to call C file I/O functions directly.

Create a MATLAB function useCFileIO that returns the first line of text file data.csv by using coder.ceval to call the C file I/O functions fopen(), fclose(), and fscanf(). Use coder.cinclude with angle brackets to include the C standard header file stdio.h, in which the C file I/O functions are defined, in the generated code. Use coder.opaque (MATLAB Coder) to initialize the variable that stores the file pointer as a variable with type FILE * and initial value NULL.

Because coder.ceval does not support array output, use coder.wref to pass the output variable out by reference to the C function fscanf(). Because the type of out is unknown at code generation time, initialize this variable using dummy values before the coder.ceval call. Without this assignment, code generation fails. To pass MATLAB character vectors to C/C++ functions called using coder.ceval, you must explicitly terminate each character vector with a null character (0). For more information, see Generate C/C++ Strings from MATLAB Strings and Character Row Vectors (MATLAB Coder).

Calls to coder.ceval in MATLAB execution produce an error. Use coder.target to make sure that useCFileIO is executing in the generated code. before the call to coder.ceval.

type useCFileIO.m
function out = useCFileIO %#codegen
fileName = 'data.csv';
if coder.target("MATLAB")
    fid = fopen(fileName);
    out = fscanf(fid, "%f,%f,%f",3);
    fclose(fid);
else
    coder.cinclude("<stdio.h>")
    fileName = [fileName 0];
    fileMode = ['r' 0];
    fileFormat = ['%lf,%lf,%lf' 0];
    fileHandle = coder.opaque("FILE*", "NULL");
    fileHandle = coder.ceval("fopen", fileName, fileMode);
    out = [0,0,0];
    coder.ceval("fscanf", fileHandle, fileFormat, ...
        coder.wref(out), coder.wref(out(2)), coder.wref(out(3)));
    coder.ceval("fclose", fileHandle);
end

Generate and test a MEX function for useCFileIO.

codegen useCFileIO
Code generation successful.
out = useCFileIO_mex
out = 1×3

    0.7071    0.6690    0.5985

Generate C code for useCFileIO and inspect the generated code. The generated C function calls fopen(), fclose(), and fscanf() directly.

codegen -config:lib -c useCFileIO
Warning: Code generation is using a coder.EmbeddedCodeConfig object. Because
Embedded Coder is not installed, this might cause some Embedded Coder features
to fail.

Code generation successful (with warnings): To view the report, open('codegen/lib/useCFileIO/html/report.mldatx')
type(fullfile("codegen","lib","useCFileIO","useCFileIO.c"))
/*
 * File: useCFileIO.c
 *
 * MATLAB Coder version            : 24.1
 * C/C++ source code generated on  : 12-Feb-2024 20:57:33
 */

/* Include Files */
#include "useCFileIO.h"
#include <stdio.h>

/* Function Definitions */
/*
 * Arguments    : double out[3]
 * Return Type  : void
 */
void useCFileIO(double out[3])
{
  static const char b_fileFormat[12] = "%lf,%lf,%lf";
  static const char b_fileName[9] = "data.csv";
  FILE *fileHandle;
  int i;
  char fileFormat[12];
  char fileName[9];
  for (i = 0; i < 9; i++) {
    fileName[i] = b_fileName[i];
  }
  char fileMode[2];
  fileMode[0] = 'r';
  fileMode[1] = '\x00';
  fileHandle = fopen(&fileName[0], &fileMode[0]);
  out[0] = 0.0;
  out[1] = 0.0;
  out[2] = 0.0;
  for (i = 0; i < 12; i++) {
    fileFormat[i] = b_fileFormat[i];
  }
  fscanf(fileHandle, &fileFormat[0], &out[0], &out[1], &out[2]);
  fclose(fileHandle);
}

/*
 * File trailer for useCFileIO.c
 *
 * [EOF]
 */

Call custom C function myAdd() from the MATLAB function addTwo.

Create a Custom C Function

Create the C header file myAdd.h. In this header file, declare the function myAdd(), which takes two input arguments of type double and returns a value of type double.

type myAdd.h
double myAdd(double a, double b);

Create a C function myAdd() that adds the two input arguments. Save the function in myAdd.c and include the header file myAdd.h.

type myAdd.c
#include <stdio.h>
#include <stdlib.h>
#include "myAdd.h"

double myAdd(double a, double b)
{
  return a + b;
}

Create a MATLAB Function That Calls the Custom C Function

Create the MATLAB function addTwo, which calls the custom C function myAdd() by using coder.ceval. Create a local MATLAB function myAddML that mimics the myAdd() C function. Use coder.target (MATLAB Coder) to make sure that addTwo calls the local MATLAB function myAddML when executing in MATLAB and calls the C function myAdd() when executing in the generated code. Use coder.updateBuildInfo (MATLAB Coder) to tell the compiler where to find the C file containing the myAdd() function, and use coder.ceval with the "-headerfile" option to instruct the code generator to include the myAdd.h header file.

type addTwo.m
function z = addTwo(x,y)  %#codegen
arguments
    x (1,1) double;
    y (1,1) double;
end
z = 0;
if coder.target("MATLAB")
    % Executing in MATLAB, call local MATLAB function
    z = myAddML(x,y);
else
    % Executing in generated code, call C function
    coder.updateBuildInfo("addSourceFiles","myAdd.c");
    z = coder.ceval("-headerfile","myAdd.h","myAdd",x,y);
end
end

function out = myAddML(a,b)
arguments
    a (1,1) double
    b (1,1) double
end
out = a + b;
end

Generate and Test MEX Function

Generate a MEX function for addTwo, and make sure that the output of addTwo_mex matches that of addTwo for the same inputs.

codegen addTwo
Code generation successful.
addTwo(4,5)
ans = 9
addTwo_mex(4,5)
ans = 9

Generate and Inspect C Code

Generate C code packaged as a standalone C library from addTwo at the command line using the codegen command with the -config:lib option. The generated C code includes a call to the myAdd() C function, as well as the directive #include "myAdd.h".

codegen -config:lib addTwo.m
Warning: Code generation is using a coder.EmbeddedCodeConfig object. Because
Embedded Coder is not installed, this might cause some Embedded Coder features
to fail.

Code generation successful (with warnings): To view the report, open('codegen/lib/addTwo/html/report.mldatx')
type(fullfile("codegen","lib","addTwo","addTwo.c"))
/*
 * File: addTwo.c
 *
 * MATLAB Coder version            : 24.1
 * C/C++ source code generated on  : 12-Feb-2024 20:58:09
 */

/* Include Files */
#include "addTwo.h"
#include "myAdd.h"

/* Function Definitions */
/*
 * Arguments    : double x
 *                double y
 * Return Type  : double
 */
double addTwo(double x, double y)
{
  /*  Executing in generated code, call C function */
  return myAdd(x, y);
}

/*
 * File trailer for addTwo.c
 *
 * [EOF]
 */

In C++, a member function, also known as a method, is a function that is associated with a specific class or object. Call a public method of a custom C++ class MyClass from the generated code using coder.ceval.

Create Simple C++ Class

For the purposes of this example, create the C++ class MyClass in the file MyClass.hpp. In this header file, define the function getValue(), which returns a constant value.

type MyClass.hpp
class MyClass {
   public:
    double getValue() const {
        return 3.14;
    }
};

Call Member Function from Generated Code

Create MATLAB function callGetValue, which calls the C++ member function getValue(). Use coder.opaque (MATLAB Coder) to declare the variable instanceOfMyClass as instance of the C++ class MyClass. Use the "HeaderFile" argument to indicate that MyClass is defined in the header file MyClass.hpp.

To call getValue() from the generated code using coder.ceval, use the C++ function template std:mem_fn to access getValue(). This function template is defined in the C++ standard header <functional>. Pass instanceOfMyClass to getValue() using coder.ref to force the code generator to pass this variable by reference instead of by value.

type callGetValue.m
function out = callGetValue
instanceOfMyClass = coder.opaque("MyClass", "MyClass{}", "HeaderFile", "MyClass.hpp");
out = 0;
out = coder.ceval("-headerfile", "<functional>", ...
    "std::mem_fn(&MyClass::getValue)", coder.ref(instanceOfMyClass));
end

Generate and Test MEX Function

Generate a MEX function for callGetValue, and make sure that the MEX function produces the expected output. To generate a C++ MEX function, specify -lang:C++ in the codegen command.

codegen -lang:c++ callGetValue
Code generation successful.
callGetValue_mex
ans = 3.1400

Generate and Inspect C++ Code

Generate C++ code packaged as a standalone C++ library from callGetValue at the command line using the codegen command with the -config:lib and -lang:c++ options. The generated C++ code creates an instance of MyClass and calls the member function getValue().

codegen -config:lib -lang:c++ callGetValue
Warning: Code generation is using a coder.EmbeddedCodeConfig object. Because
Embedded Coder is not installed, this might cause some Embedded Coder features
to fail.

Code generation successful (with warnings): To view the report, open('codegen/lib/callGetValue/html/report.mldatx')
type(fullfile("codegen","lib","callGetValue","callGetValue.cpp"))
//
// File: callGetValue.cpp
//
// MATLAB Coder version            : 24.1
// C/C++ source code generated on  : 12-Feb-2024 20:58:16
//

// Include Files
#include "callGetValue.h"
#include "MyClass.hpp"
#include <functional>

// Function Definitions
//
// Arguments    : void
// Return Type  : double
//
double callGetValue()
{
  MyClass instanceOfMyClass;
  instanceOfMyClass = MyClass{};
  return std::mem_fn(&MyClass::getValue)(&instanceOfMyClass);
}

//
// File trailer for callGetValue.cpp
//
// [EOF]
//

You can use coder.ceval to call C/C++ functions that are defined in custom C/C++ libraries. These functions can have their own initialize and terminate functions.

Create Custom C Function and Library

For the purposes of this example, create a MATLAB function integrateSquare that calculates the definite integral of x2 over the interval [min, max]. Generate a standalone C library for integrateSquare.

type integrateSquare.m
function out = integrateSquare(min,max)
arguments
    min (1,1) double
    max (1,1) double
end
f = @(x) x.^2;
out = integral(f, min, max);
end
codegen -config:lib integrateSquare
Warning: Code generation is using a coder.EmbeddedCodeConfig object. Because
Embedded Coder is not installed, this might cause some Embedded Coder features
to fail.

Code generation successful (with warnings): To view the report, open('codegen/lib/integrateSquare/html/report.mldatx')

Inspect the generated C code, which is located in the directory codegen/lib/integrateSquare. The integrateSquare library and header files, as well as files containing definitions for the integrateSquare_initialize() and integrateSquare_terminate() functions, are located in the same directory.

type(fullfile("codegen","lib","integrateSquare","integrateSquare.c"))
/*
 * File: integrateSquare.c
 *
 * MATLAB Coder version            : 24.1
 * C/C++ source code generated on  : 12-Feb-2024 20:57:46
 */

/* Include Files */
#include "integrateSquare.h"
#include "integralCalc.h"
#include "integrateSquare_emxutil.h"
#include "integrateSquare_types.h"
#include "rt_nonfinite.h"
#include "rt_nonfinite.h"
#include <math.h>

/* Function Definitions */
/*
 * Arguments    : double b_min
 *                double b_max
 * Return Type  : double
 */
double integrateSquare(double b_min, double b_max)
{
  emxArray_real_T *interval;
  double A;
  double B;
  double delta;
  double out;
  double *interval_data;
  int MaxIntervalCount;
  int i;
  int nx;
  int y;
  signed char problemType;
  boolean_T guard1;
  boolean_T isinfA;
  boolean_T isinfB;
  boolean_T reversedir;
  MaxIntervalCount = 16384;
  emxInit_real_T(&interval);
  i = interval->size[0] * interval->size[1];
  interval->size[0] = 1;
  interval->size[1] = 2;
  emxEnsureCapacity_real_T(interval, i);
  interval_data = interval->data;
  if (b_max < b_min) {
    A = b_max;
    B = b_min;
    reversedir = true;
  } else {
    A = b_min;
    B = b_max;
    reversedir = false;
  }
  interval_data[0] = A;
  interval_data[1] = B;
  isinfA = rtIsInf(A);
  isinfB = rtIsInf(B);
  if (A == B) {
    problemType = 0;
  } else if (isinfA || isinfB) {
    if ((!isinfA) && isinfB) {
      interval_data[0] = 0.0;
      interval_data[1] = 1.0;
      problemType = 2;
    } else if (isinfA && (!isinfB)) {
      interval_data[0] = -1.0;
      interval_data[1] = 0.0;
      problemType = 3;
    } else if (isinfA && isinfB) {
      interval_data[0] = -1.0;
      interval_data[1] = 1.0;
      problemType = 4;
    } else {
      problemType = 0;
    }
  } else {
    interval_data[0] = -1.0;
    interval_data[1] = 1.0;
    problemType = 1;
  }
  i = interval->size[0] * interval->size[1];
  interval->size[0] = 1;
  interval->size[1] = 2;
  emxEnsureCapacity_real_T(interval, i);
  interval_data = interval->data;
  guard1 = false;
  if (problemType == 0) {
    guard1 = true;
  } else {
    double pathlen_tmp;
    int n_data;
    int nt;
    nx = 2;
    pathlen_tmp = interval_data[1] - interval_data[0];
    if (pathlen_tmp > 0.0) {
      n_data = (int)(ceil(pathlen_tmp * (10.0 / pathlen_tmp)) - 1.0);
      if (n_data <= 0) {
        y = 0;
      } else {
        y = n_data;
      }
      nt = y + 2;
      if (y >= 0) {
        nx = y;
      } else {
        nx = 0;
      }
      i = interval->size[0] * interval->size[1];
      interval->size[1] = nx + 2;
      emxEnsureCapacity_real_T(interval, i);
      interval_data = interval->data;
      for (i = 0; i < nx; i++) {
        interval_data[i + 2] = 0.0;
      }
      if (y + 2 > 2) {
        interval_data[y + 1] = interval_data[1];
        delta = (interval_data[1] - interval_data[0]) / (double)(n_data + 1);
        for (nx = n_data; nx >= 1; nx--) {
          interval_data[(y + nx) - n_data] =
              interval_data[0] + (double)nx * delta;
        }
      }
      nx = y + 2;
    } else {
      nt = 2;
    }
    n_data = 0;
    for (y = 2; y <= nx; y++) {
      delta = interval_data[y - 1];
      if (fabs(delta - interval_data[n_data]) > 0.0) {
        n_data++;
        interval_data[n_data] = delta;
      } else {
        nt--;
      }
    }
    if (nt < 2) {
      double b_interval;
      delta = interval_data[0];
      b_interval = interval_data[0];
      i = interval->size[0] * interval->size[1];
      interval->size[0] = 1;
      interval->size[1] = 2;
      emxEnsureCapacity_real_T(interval, i);
      interval_data = interval->data;
      interval_data[0] = delta;
      interval_data[1] = b_interval;
      nt = 2;
    } else {
      i = interval->size[0] * interval->size[1];
      interval->size[1] = nt;
      emxEnsureCapacity_real_T(interval, i);
    }
    nx = (nt - 1) << 1;
    if (nx > 16384) {
      MaxIntervalCount = nx;
    }
    if (!(pathlen_tmp > 0.0)) {
      guard1 = true;
    } else {
      out = scalarValuedIntegral(A, B, interval, nt, pathlen_tmp, problemType,
                                 MaxIntervalCount, &delta, &isinfA);
    }
  }
  if (guard1) {
    delta = (b_min + b_max) / 2.0;
    if ((!rtIsInf(b_min)) && (!rtIsNaN(b_min)) &&
        ((!rtIsInf(b_max)) && (!rtIsNaN(b_max))) &&
        (rtIsInf(delta) || rtIsNaN(delta))) {
      delta = b_min / 2.0 + b_max / 2.0;
    }
    out = (b_max - b_min) * (delta * delta);
  }
  emxFree_real_T(&interval);
  if (reversedir) {
    out = -out;
  }
  return out;
}

/*
 * File trailer for integrateSquare.c
 *
 * [EOF]
 */

Create MATLAB Function to Call Custom C Function

Create a MATLAB function callIntegrateSquare that calls the custom C function integrateSquare() using coder.ceval. For the purposes of this example, call the integrateSquare_initialize() function before the integrateSquare() call, and call the integrateSquare_terminate() function after.

Use coder.updateBuildInfo (MATLAB Coder) to add the directory containing the integrateSquare() library and other files to the include path. In the call to the coder.updateBuildInfo function, you can use the START_DIR macro to reference the current working folder. This macro can only be used in MATLAB code for code generation. Because MATLAB coder generates static library files with platform-specific extensions, use ispc to make sure that you use the correct extension for your platform.

type callIntegrateSquare.m
function out = callIntegrateSquare(x,y) %#codegen
arguments
    x (1,1) double
    y (1,1) double
end
if coder.target("MATLAB")
    disp("Calling MATLAB function");
    out = integrateSquare(x,y);
else
    disp("Calling custom C function");
    out = 0;
    coder.updateBuildInfo("addIncludePaths", ...
        "$(START_DIR)/codegen/lib/integrateSquare");
    if ispc
        coder.updateBuildInfo("addLinkObjects","integrateSquare.lib", ...
            "$(START_DIR)/codegen/lib/integrateSquare","",true,true); 
    else
        coder.updateBuildInfo("addLinkObjects","integrateSquare.a", ...
            "$(START_DIR)/codegen/lib/integrateSquare","",true,true); 
    end  
    coder.ceval("-headerfile","integrateSquare_initialize.h", ...
        "integrateSquare_initialize");
    out = coder.ceval("-headerfile","integrateSquare.h","integrateSquare", ...
        x,y);
    coder.ceval("-headerfile","integrateSquare_terminate.h", ...
        "integrateSquare_terminate");
end
end

Generate and Test MEX Function

Generate a MEX function for callIntegrateSquare. Make sure that the MATLAB and MEX function results match.

codegen callIntegrateSquare
Code generation successful.
callIntegrateSquare(-2,2)
Calling MATLAB function
ans = 5.3333
callIntegrateSquare_mex(-2,2)
Calling custom C function
ans = 5.3333

Generate and Inspect C Code

Generate a standalone C library for callIntegrateSquare and inspect the call to integrateSquare_initialize(), integrateSquare(), and integrateSquare_terminate() in the generated code.

codegen -config:lib callIntegrateSquare
Warning: Code generation is using a coder.EmbeddedCodeConfig object. Because
Embedded Coder is not installed, this might cause some Embedded Coder features
to fail.

Code generation successful (with warnings): To view the report, open('codegen/lib/callIntegrateSquare/html/report.mldatx')
type(fullfile("codegen","lib","callIntegrateSquare","callIntegrateSquare.c"))
/*
 * File: callIntegrateSquare.c
 *
 * MATLAB Coder version            : 24.1
 * C/C++ source code generated on  : 12-Feb-2024 20:58:01
 */

/* Include Files */
#include "callIntegrateSquare.h"
#include "coder_platform.h"
#include "integrateSquare.h"
#include "integrateSquare_initialize.h"
#include "integrateSquare_terminate.h"
#include <stdio.h>

/* Function Definitions */
/*
 * Arguments    : double x
 *                double y
 * Return Type  : double
 */
double callIntegrateSquare(double x, double y)
{
  double out;
  printf("%s\n", "Calling custom C function");
  fflush(stdout);
  coderIsPC();
  integrateSquare_initialize();
  out = integrateSquare(x, y);
  integrateSquare_terminate();
  return out;
}

/*
 * File trailer for callIntegrateSquare.c
 *
 * [EOF]
 */

Suppose you have a MATLAB function that calls custom C code that takes complex number inputs. You must define your C code input parameters so that the complex number inputs from your MATLAB function can map to your C code.

In generated code, complex numbers are defined as a struct that has two fields, re and im, which are the real and imaginary part of a complex number respectively. This struct is defined in the header file rtwtypes.h, which you can find in the codegen\lib\functionName folder of your current path. The struct is defined as follows:

typedef struct {
    real32_T re; /*Real Component*/
    real32_T im; /*Imaginary Component*/
} creal_T;

For more information, see Mapping MATLAB Types to Types in Generated Code (MATLAB Coder).

The C code that you want to integrate must include the rtwtypes.h header file. An example C code foo.c is shown below:

#include "foo.h"
#include<stdio.h>
#include<stdlib.h>
#include "rtwtypes.h"

double foo(creal_T x) {
    double z = 0.0;
    z = x.re*x.re + x.im*x.im;
    return (z);
}

The struct is named creal_T. A header file foo.h must also be defined as:

#include "rtwtypes.h"
double foo(creal_T x);

The MATLAB code executes foo.c by using the coder.ceval function that has a complex numbers input:

function y = complexCeval  %#codegen
y = 0.0;
coder.updateBuildInfo("addSourceFiles","foo.c");
coder.cinclude("foo.h");
y = coder.ceval("foo", 10+20i);
end
The coder.ceval command takes the complex number input. The code generator maps the complex number to the struct creal_T variable x and its fields re and im.

Generate code for the function complexCeval by running this command:

codegen -config:lib -report complexCeval

Input Arguments

collapse all

Name of C/C++ function to be executed in the generated code, specified as a string scalar or character vector. functionName must be a constant at code generation time.

Example: x = coder.ceval("myFunction")

Example: coder.ceval("myFunction")

Data Types: char | string

Arguments to the called C/C++ function, specified as a comma-separated list of character vectors, arrays, elements of an array, structures, structure fields, or object properties, in the order required by the function. String scalars and string arrays are not supported.

By default, coder.ceval passes arguments by value to the called C/C++ function whenever C/C++ supports passing arguments by value. To force coder.ceval to pass arguments by reference, use the constructs coder.ref (MATLAB Coder), coder.rref (MATLAB Coder), and coder.wref (MATLAB Coder). In situations where C/C++ does not support passing arguments by value, such as when the argument is an array, coder.ceval passes arguments by reference. If you do not use coder.ref, coder.rref or coder.wref, copies of C/C++ function arguments can appear in the generated code to enforce MATLAB semantics for arrays.

Example: x = coder.ceval("tolower",myChar)

Example: coder.ceval("myFunction",coder.ref(x))

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical | char | struct
Complex Number Support: Yes

Options for the C/C++ function call evaluated by coder.ceval, specified as an option value or a comma-separated list of option values. Multiple options can be specified for the coder.ceval function, and options can appear in any order. All options (including headerfile) must be constants at code generation time. This table shows the options available for coder.ceval.

optionDescription
"-global"Specify that the C/C++ function to be called by coder.ceval uses one or more global variables. The -global option inhibits certain code generation optimizations that can interfere with global variable use in the called C/C++ function.
"-gpudevicefcn"Specify that the C/C++ function to be called by coder.ceval is located on a GPU device. This option allows you to call CUDA® GPU __device__ functions from within kernels. This option requires a GPU Coder™ license.
"-headerfile","headerfile"

Specify that the C/C++ function to be called by coder.ceval is declared in the header file headerfile. The code generator adds an #include statement for the specified header file in the generated code. You can use the "-headerfile" argument to coder.ceval instead of a separate call to the coder.cinclude (MATLAB Coder) function. You can specify only one header file by using the "-headerfile" option.

To include a C/C++ standard header file, enclose the name of the header file name in angle brackets <>. The generated #include statement has the format #include <headerfile>. A standard header file must be in a standard location or on the include path.

coder.ceval("-headerfile","<math.h>","atan",45)

To include a nonstandard header file, omit the angle brackets. The generated #include statement has the format #include "headerfile". The nonstandard header file must be in the current folder or on the include path.

coder.ceval("-headerfile","myHeader","myFun")

To specify the include path, use addIncludePaths (MATLAB Coder).

"-layout:any"Pass input and output data between the generated code and the called C/C++ function without changing the data layout, even when array layouts do not match. This behavior is the default.
"-layout:rowMajor" or "-row"Pass input and output data between the generated code and the called C/C++ function in a row-major layout. When called from a MATLAB function or a MATLAB Function block that uses the column-major layout, the code generator converts inputs to a row-major layout and converts outputs back to a column-major layout.
"-layout:columnMajor" or "-col"Pass input and output data between the generated code and the called C/C++ function in a column-major layout. When called from a MATLAB function or a MATLAB Function block that uses the row-major layout, the code generator converts inputs to a column-major layout and converts outputs back to a row-major layout.

Example: coder.ceval("-headerfile","myHeader.h","-layout:rowMajor","-global","myFunction",coder.rref(in),coder.wref(out));

Limitations

  • You cannot use coder.ceval on functions that you declare as extrinsic by using coder.extrinsic (MATLAB Coder).

  • If a property has a get method, a set method, or validators, or if the property is a System object™ property with an attribute that constrains or modifies the property value, then you cannot pass the property by reference to an external function. See Passing By Reference Not Supported for Some Properties.

  • Variable-size matrices as entry-point parameters are not supported for row-major code generation.

Tips

  • To use coder.ceval to a call a C/C++ function that accepts or returns types of variables that do not exist in MATLAB code, such as pointers, FILE types for file I/O, and C/C++ macros, use the coder.opaque function.

  • External code called using coder.ceval and the generated code run within the same process and share memory. If external code erroneously writes to the memory that contains data structures used by the generated code, it can cause unexpected behavior or a crash. For example, if the external code attempts to write data to an array after its end point, the generated code might behave unexpectedly or crash.

  • MATLAB uses UTF-8 as its system encoding on the Windows® platform. As a result, system calls made from within a generated MEX function accept and return UTF-8-encoded strings. By contrast, the code generated by MATLAB Coder™ encodes text data by using the encoding specified by the Windows locale. So, if your MATLAB entry-point function uses coder.ceval (MATLAB Coder) to call an external C/C++ function that assumes a different system encoding, then the generated MEX function might produce garbled text. If this happens, you must update the external C/C++ function.

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

GPU Code Generation
Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Version History

Introduced in R2011a