Customize Enumerated Types in Generated Code
To customize an enumeration in the generated code, in the static methods section of the MATLAB® enumeration class definition, provide customized versions of the methods listed in this table. The table also lists:
The default value returned by a method, if you do not explicitly implement the method in your MATLAB enumeration class definition. If you do not provide an implementation, the code generator assumes that the method returns this default value.
All possible values a method can return and their effects on the generated code.
Method | Description | Return values |
---|---|---|
generateEnumClass | Specifies whether to generate enumeration classes. See Generate C++ Code That Contains Ordinary C Enumeration. |
|
| Specifies whether the class name becomes a prefix in the generated code. See Include Class Name Prefix in Generated Enumeration Value Names. |
|
| Specifies the custom name of the enumeration in the generated code. If the target language is C++, also specifies namespace of the enumeration in the generated code. See Specify a Custom Enumeration Name. | The default return value is
|
| Returns the default enumerated value. See Specify a Default Enumeration Value. | The default return value is the first value in the enumeration class definition. |
| Specifies whether the enumerated type is exported or imported. See:
|
|
| Specifies the header file that contains the definition of an imported or exported enumerated type. See: . | The default return value is
|
| For imported enumerated type, specifies whether the values of enumeration members can be modified at build time, that is, after source code generation. See Modify Enumeration Member Values at Build Time. |
|
Generate C++ Code That Contains Ordinary C Enumeration
When you generate code using a language standard that supports enumeration classes (C++11 or newer), your MATLAB enumeration class is converted to a C++ enumeration class. For example:
enum class MyEnumClass16 : short
{
Orange = 0, // Default value
Yellow,
Pink
};
To generate an ordinary C enumeration instead, provide a
generateEnumClass
method that returns
false
. For example:
classdef MyEnumClass16 < int16 enumeration Orange(0), Yellow(1), Pink(2) end % particular enum opting out methods(Static) function y = generateEnumClass() y = false; end end end
Now the generated C++ code contains an ordinary C enumeration.
enum MyEnumClass16 : short
{
Orange = 0, // Default value
Yellow,
Pink
};
Include Class Name Prefix in Generated Enumeration Value Names
By default, the generated enumerated type value name does not include the class name prefix. For example:
enum LEDcolor
{
GREEN = 1,
RED
};
typedef enum LEDcolor LEDcolor;
To include the class name prefix, provide an
addClassNameToEnumNames
method that returns
true
. For example:
classdef LEDcolor < int32 enumeration GREEN(1), RED(2) end methods(Static) function y = addClassNameToEnumNames() y=true; end end end
In the generated type definition, the enumerated value names include the class
prefix
LEDcolor
.
enum LEDcolor
{
LEDcolor_GREEN = 1,
LEDcolor_RED
};
typedef enum LEDcolor LEDcolor;
Note
When generating enumeration classes (C++11 and newer standards), the code generator ignores this static method.
Specify a Custom Enumeration Name
Since R2025a
You can specify a custom name for a MATLAB enumeration in the generated code that can be configured based on the target language.
Consider the case where the target language is C. Provide an implementation of the
generatedCodeIdentifier
method that, when passed the input
"C"
, returns the custom name as a string.
When the target language is C++, you can specify both a custom name and a
namespace for the enumeration. Provide an implementation of the
generatedCodeIdentifier
method that, when passed the input
"C++"
, returns the custom name and namespace as a string in
the format "mynamespace::myname"
.
For example, define this MATLAB enumeration in the namespace
matlabNamespace
:
% Defined in file +matlabNamespace/CustomEnumName.m classdef CustomEnumName < int32 enumeration Red(0), Blue(1), Green(2) end methods(Static) function n = generatedCodeIdentifier(lang) if lang == "C++" n = "cppNamespace::MyCppEnum"; else n = "myCEnum"; end end end end
Define an entry-point function xCustomEnumName
that uses this
enumeration:
function out = xCustomEnumName out = matlabNamespace.CustomEnumName.Green; end
First, generate C source code for this entry-point function.
codegen -config:lib -c xCustomEnumName -report
The generated C enumeration definition is:
enum myCEnum
{
Red = 0, /* Default value */
Blue,
Green
};
Next, generate C++ source code for this entry-point function.
codegen -lang::c++ -config:lib -c xCustomEnumName -report
The generated C++ enumeration definition is:
namespace cppNamespace {
enum class MyCppEnum : int
{
Red = 0, // Default value
Blue,
Green
};
}
Specify a Default Enumeration Value
If the value of a variable that is cast to an enumerated type does not match one of the enumerated type values:
Generated MEX reports an error.
Generated C/C++ code replaces the value of the variable with the enumerated type default value.
Unless you specify otherwise, the default value for an enumerated
type is the first value in the enumeration class definition. To specify
a different default value, add your own getDefaultValue
method
to the methods section. In this example, the first enumeration member
value is LEDcolor.GREEN
, but the getDefaultValue
method
returns LEDcolor.RED
:
classdef LEDcolor < int32 enumeration GREEN(1), RED(2) end methods (Static) function y = getDefaultValue() y = LEDcolor.RED; end end end
Import Enumerated Type Definition from External Header File
To specify that an enumerated type is defined in an external header file, provide a customized
getHeaderFile
method that returns the path to the header
file as a nonempty string. This example specifies that
LEDcolor
is defined in the external file
my_LEDcolor.h
.
classdef LEDcolor < int32 enumeration GREEN(1), RED(2) end methods(Static) function y = getHeaderFile() y = "my_LEDcolor.h"; end end end
In this case, the code generator does not produce a definition for the enumeration. You must
provide the my_LEDcolor.h
file that supplies this definition.
For example:
enum LEDcolor
{
GREEN = 1,
RED
};
typedef enum LEDcolor LEDcolor;
If you place the MATLAB enumeration LEDcolor
inside the MATLAB namespace nmsp
and generate C++ code, code
generation preserves the name of this enumeration and places it inside the C++
namespace nmsp
in the generated code. Therefore, in the
header file that you provide, you must define this enumeration inside the
namespace nmsp
.
Export Enumerated Type Definition to External Header File
Since R2025a
You can instruct the code generator to produce the definition of an enumerated type in a header file that you specify. In your MATLAB enumeration class definition, provide implementations of:
A
getDataScope
method that returns the string"Exported"
A
getHeaderFile
method that returns the name of the header file as a nonempty string
For example, define this MATLAB enumeration class
exportedEnum
:
classdef ExportedEnum < int32 enumeration red (1) blue (2) green (3) yellow (4) end methods(Static) function out = getDataScope() out = "Exported"; end function hFile = getHeaderFile() hFile = "exportedEnumHeader.h"; end end end
Define an entry-point function xExportedEnum
that uses this
enumeration:
function out = xExportedEnum(in) t = local(in); out = int32(t); end function out = local(in) t = ExportedEnum.green; if (in > 9) out = t; else out = ExportedEnum.red; end end
Generate C++ source code for
xExportedEnum
:
codegen -lang:c++ -config:lib -c xExportedEnum -args 0 -report
Inspect the generated files. The C++ enumeration class
ExportedEnum
is defined in the header file
exportedEnumHeader.h
.
Modify Enumeration Member Values at Build Time
Since R2025a
When you specify an enumeration as imported (see Import Enumerated Type Definition from External Header File), the code generator does not produce a definition for this enumeration in the generated C/C++ source files. When you build the generated source code, you must provide a header file that contains this definition.
In the general situation, the enumeration member values in your header file must match those in your MATLAB enumeration class definition. This is because, the code generator, when attempting to optimize the generated code by performing constant-folding, might hardcode the MATLAB enumeration member values in the generated source files.
However, you can indicate that you want to modify the imported enumeration member
values in your custom header file when you build the generated code. In your
MATLAB enumeration class definition, provide an implementation of the
isTunableInCode
static method that returns
true
. This return value instructs the code generator to not
constant-fold expressions that involve the enumeration members and retain references
to the original enumeration members themselves. This behavior allows the final build
artifact (MEX, library, or executable) to perform computations that use the
enumeration member values provided in your current header file.
For example, consider this MATLAB enumeration class definition that is specified as both imported and tunable:
classdef Colors < int32 enumeration Red(0), Blue(1), Green(2) end methods(Static) function y = getHeaderFile() y = 'Header.h'; % making this imported end function y = isTunableInCode() y = true; % making this tunable end end end
Define an entry-point function that uses the Colors
enumeration:
function out = xColors t = 2; if (t == Colors.Green) out = 1; elseif (t == Colors.Red) out = 2; else out = 6; end end
Generate C++ source code for
xColors
:
codegen -lang:c++ -c -config:lib xColors -report
Inspect the generated xColors
entry-point function. The
generated file retains all instances of the enumeration members
themselves:
double xColors()
{
double out;
if (static_cast<int>(Colors::Green) == 2) {
out = 1.0;
} else if (static_cast<int>(Colors::Red) == 2) {
out = 2.0;
} else {
out = 6.0;
}
return out;
}
Now comment out the isTunableInCode
method in the enumeration
and regenerate code. The code generator has now constant-folded the enumeration
members and further optimized the generated code to reduce it to a single
line.
double xColors()
{
return 1.0;
}
This example also highlights the fact that specifying an enumeration as tunable might prevent further optimizations of the generated code that depend on the constant-folding optimization.
Constant Conditional Expressions and Unreachable Code
To generate a static library for xColors
, create a file
Header.h
that contains this C++ enum class
definition:
enum class Colors : int
{
Green = 0, // Default value
Blue,
Red
};
To generate code and build a static library, run this command:
codegen -lang:c++ -config:lib xColors -report
Warning: C++ Compiler produced warnings. See the build log for further details. Code generation successful (with warnings): View report
For a given implementation of the Colors
enumeration,
conditional expressions like static_cast<int>(Colors::Green) ==
2
are constants and cause the C/C++ compiler to throw this
warning:
warning C4127: conditional expression is constant
In addition, this code pattern might cause certain branches of the
conditional block to become unreachable. For example, for the current definition
of Colors
, the else
branch in the
generated xColors
function is unreachable.
Constant conditional expressions and unreachable branches cause the generated code for tunable enumerations to violate certain coding standard rules including MISRA™ C:2012 Rules 2.1 and 14.3, and MISRA C++:2008 Rule 0-1-1.