Documentation

C Code Interface for Arrays

C Code Interface for Statically Allocated Arrays

In generated code, MATLAB® contains two pieces of information about statically allocated arrays: the maximum size of the array and its actual size.

For example, consider the MATLAB function uniquetol:

function B = uniquetol(A, tol) %#codegen
A = sort(A);
coder.varsize('B');
B = A(1);
k = 1;
for i = 2:length(A)
    if abs(A(k) - A(i)) > tol
        B = [B A(i)];
        k = i;
    end
end

Generate code for uniquetol specifying that input A is a variable-size real double vector whose first dimension is fixed at 1 and second dimension can vary up to 100 elements.

codegen -config:lib -report uniquetol -args {coder.typeof(0,[1 100],1),coder.typeof(0)}  

In the generated code, the function declaration is:

extern void uniquetol(const double A_data[100], const int A_size[2], double tol, emxArray_real_T *B);

There are two pieces of information about A:

  • double A_data[100]: the maximum size of input A (where 100 is the maximum size specified using coder.typeof).

  • int A_size[2]: the actual size of the input.

C Code Interface for Dynamically Allocated Arrays

In generated code, MATLAB represents dynamically allocated data as a structure type called emxArray. An embeddable version of the MATLAB mxArray, the emxArray is a family of data types, specialized for all base types.

emxArray Structure Definition

typedef struct emxArray_<baseTypedef>
{
    <baseType> *data;
    int *size;
    int allocatedSize;
    int numDimensions;
    boolean_T canFreeData;
} emxArray_<baseTypedef>;

baseTypedef is the predefined type in rtwtypes.h corresponding to baseType. For example, here is the definition for an emxArray of base type double with unknown upper bounds:

typedef struct emxArray_real_T
{
    double *data;
    int *size;
    int allocatedSize;
    int numDimensions;
    boolean_T canFreeData;
} emxArray_real_T;

The predefined type corresponding to double is real_T. For more information on the correspondence between built-in data types and predefined types in rtwtypes.h, see How MATLAB Coder Infers C/C++ Data Types.

To define two variables, in1 and in2, of this type, use this statement:

emxArray_real_T *in1, *in2;

C Code Interface for Structure Fields

FieldDescription
*dataPointer to data of type <baseType>.
*sizePointer to first element of size vector. Length of the vector equals the number of dimensions.
allocatedSizeNumber of elements currently allocated for the array. If the size changes, MATLAB reallocates memory based on the new size.
numDimensionsNumber of dimensions of the size vector, that is, the number of dimensions you can access without crossing into unallocated or unused memory.
canFreeDataBoolean flag indicating how to deallocate memory:
  • true – MATLAB deallocates memory automatically

  • false – Calling program determines when to deallocate memory

Utility Functions for Creating emxArray Data Structures

When you generate code that uses variable-size data, the code generation software exports a set of utility functions that you can use to create and interact with emxArrays in your generated code. To call these functions in your main C function, include the generated header file. For example, when you generate code for function foo, include foo_emxAPI.h in your main C function. .

    Note:   The code generation software exports emxArray utility functions only for variable-size arrays that are entry-point function arguments or that are used by functions called by coder.ceval.

FunctionArgumentsDescription
emxArray_<baseType> *emxCreateWrapper_<baseType> (...)*data
num_rows
num_cols
Creates a new 2-dimensional emxArray, but does not allocate it on the heap. Instead uses memory provided by the user and sets canFreeData to false so it does not inadvertently free user memory, such as the stack.
emxArray_<baseType> *emxCreateWrapperND_<baseType> (...)*data
numDimensions
*size
Same as emxCreateWrapper_<baseType>, except it creates a new N-dimensional emxArray.
emxArray_<baseType> *emxCreate_<baseType> (...)num_rows
num_cols
Creates a new two-dimensional emxArray on the heap, initialized to zero. All data elements have the data type specified by <baseType>.
emxArray_<baseType> *emxCreateND_<baseType> (...)numDimensions
*size
Same as emxCreate_<baseType>, except it creates a new N-dimensional emxArray on the heap.
void emxInitArray_<baseType> (...)**emxArray
numDimensions
Creates a new empty emxArray on the heap. All data elements have the data type specified by <baseType>.
void emxInitArray_<structType> (...)*structureCreates empty emxArrays in a structure.
void emxDestroyArray_<baseType> (...)*emxArrayFrees dynamic memory allocated by emxCreate_<baseType>, emxCreateND_<baseType>, and emxInitArray_baseType functions.
void emxDestroyArray_<structType> (...)*structureFrees dynamic memory allocated by emxInitArray_<structType> functions.

By default, when you generate C/C++ source code, static libraries, dynamic libraries, and executables, MATLAB Coder™ generates an example C/C++ main function. The example main function is a template that can help you to incorporate generated C/C++ code into your application. If you generate code that uses dynamically allocated data, the example main function includes calls to emxArray utility functions that create emxArrays required for this data. The example main function also initializes emxArray data to zero values. For more information, see Incorporate Generated Code Using an Example Main Function.

Was this topic helpful?