Main Content

Code Generation for Enumerations

Enumerations represent a fixed set of named values. Enumerations help make your MATLAB® code and generated C/C++ code more readable. For example, the generated code can test equality with code such as if (x == Red) instead of using strcmp.

For code generation, when you use enumerations, adhere to these restrictions:

  • Calls to methods of enumeration classes are not supported.

  • Passing strings or character vectors to constructors of enumerations is not supported.

  • The enumeration class must derive from one of these base types: int8, uint8, int16, uint16, int32, or uint32. See Define Enumerations for Code Generation.

  • For members of uint32 enumerations, code generation supports values that are less than or equal to intmax("int32").

  • You can use only a limited set of operations on enumerations. See Allowed Operations on Enumerations.

  • Use enumerations with functions that support enumerated types for code generation. See MATLAB Toolbox Functions That Support Enumerations.

Define Enumerations for Code Generation

For code generation, the enumeration class must derive from one of these base types: int8, uint8, int16, uint16, int32, or uint32. For example:

classdef PrimaryColors < int32
    enumeration
        Red(1),
        Blue(2),
        Yellow(4)
    end
end

You can use the base type to control the size of an enumerated type in generated C/C++ code. You can:

  • Represent an enumerated type as a fixed-size integer that is portable to different targets.

  • Reduce memory usage.

  • Interface with legacy code.

  • Match company standards.

Representation of Enumerated Type in Generated Code

The representation of the enumerated type in generated C/C++ code depends on the following:

  • The base type of the MATLAB enumeration

  • The target language (C or C++)

  • If the target language is C++, the target language standard (C++03 or C++11)

Base Type is Native Integer Type.  If the base type is the native integer type for the target platform (for example, int32), the code generator produces a C/C++ enumerated type. Consider this MATLAB enumerated type definition:

classdef LEDcolor < int32
    enumeration
        GREEN(1),
        RED(2)
    end
end

If you generate C code or C++03 code, the generated enumeration is:

enum LEDcolor
{
    GREEN = 1,
    RED
};

If you generate C++11 code, the generated code contains an enumeration class (by default) that explicitly defines the underlying type:

enum class LEDcolor : int
{
  GREEN = 1, 
  RED
};

Base Type is Different from the Native Integer Type.  Suppose that built-in integer base type for the enumeration is different from the native integer type for the target platform. For example, consider this MATLAB enumerated type definition:

classdef LEDcolor < int16
    enumeration
        GREEN(1),
        RED(2)
    end    
end

  • If you generate C code, the code generator produces a typedef statement for the enumerated type and #define statements for the enumerated values. For example, the enumerated type definition LEDcolor produces this C code:

    typedef short LEDcolor;
#define GREEN ((LEDcolor)1)
#define RED ((LEDcolor)2)

  • If you generate C++03 code, the enumeration members are converted to constants. These constants belong to the namespace that contains the enumeration type definition in the generated C++ code.

    For example, suppose that you place the enumerated type definition LEDcolor inside the package pkg. The default behavior of the code generator is to convert MATLAB packages to C++ namespaces. The generated C++ code is placed inside the namespace pkg:

    namespace pkg {
typedef short LEDcolor;

// enum pkg_LEDcolor
const LEDcolor GREEN{1};
const LEDcolor RED{2};

}

  • C++11 allows you to specify the underlying type of an enumeration, just like MATLAB does. If you generate C++11 code, the MATLAB enumeration class is converted to a C++ enumeration class (by default) that explicitly defines the underlying type.

    For example, suppose that you place the enumerated type definition LEDcolor inside the package pkg. The default behavior of the code generator is to convert MATLAB packages to C++ namespaces. The generated C++11 code is placed inside the namespace pkg:

    namespace pkg {
enum class LEDcolor : short
{
  GREEN = 1, // Default value
  RED
};

}

The C/C++ type in the typedef statement or the underlying type of the C++11 enumeration depends on:

Generate C++11 Code That Contains Ordinary C Enumerations.  You can change the default behavior of the code generator to produce ordinary C enumerations in the generated C++11 code. Do one of the following:

  • In the code generation configuration object, set the CppGenerateEnumClass property to false.

  • In the MATLAB Coder™ app, in the Generate step, on the Code Appearance tab, clear the Generate C++ enum class from MATLAB enumeration check box.

To instruct the code generator to produce ordinary C enumeration for a particular MATLAB enumeration class in your code, include the static method generateEnumClass that returns false in the implementation of that MATLAB enumeration class. See Customize Enumerated Types in Generated Code.

Allowed Operations on Enumerations

For code generation, you are restricted to the operations on enumerations listed in this table.

OperationExampleNotes

assignment operator: =

 

xon = LEDcolor.GREEN
xoff = LEDcolor.RED

—

relational operators: < > <= >= == ~=

 

xon == xoff

Code generation does not support using == or ~= to test equality between an enumeration member and a string array, a character array, or a cell array of character arrays.

cast operation

 

double(LEDcolor.RED)

—

conversion to character array or string

 

y = char(LEDcolor.RED);
y1 = cast(LEDcolor.RED,'char');
y2 = string(LEDcolor.RED);

  • You can convert only compile-time scalar valued enumerations. For example, this code runs in MATLAB, but produces an error in code generation:

    y2 = string(repmat(LEDcolor.RED,1,2));

  • The code generator preserves enumeration names when the conversion inputs are constants. For example, consider this enumerated type definition:

    classdef AnEnum < int32
    enumeration
        zero(0),
        two(2),
        otherTwo(2)
    end
end

    Generated code produces "two" for 

    y = string(AnEnum.two)
    and "otherTwo" for 
    y = string(AnEnum.otherTwo)

indexing operation

 

m = [1 2]
n = LEDcolor(m)
p = n(LEDcolor.GREEN)

—

control flow statements: if, switch, while

 

if state == sysMode.ON
    led = LEDcolor.GREEN;
else
    led = LEDcolor.RED;
end

—

MATLAB Toolbox Functions That Support Enumerations

For code generation, you can use enumerations with these MATLAB toolbox functions:

Related Topics