Documentation Center

  • Trial Software
  • Product Updates

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>;

where baseTypedef is the predefined type in rtwtypes.h corresponding to baseType. For example, here's 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;

Note that 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. .

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, 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 baseTypeName.
emxArray_<baseType> *emxCreateND_<baseType> (...)numDimensions
*size
Same as emxCreate, except it creates a new N-dimensional emxArray on the heap.
emxArray_<baseType> *emxDestroyArray_<baseType> (...)*emxArrayFrees dynamic memory allocated by *emxCreate and *emxCreateND functions.

Was this topic helpful?