Enumerations

About Enumerated Data Types

Enumerated data is data that is restricted to a finite set of values. An enumerated data type is a MATLAB class that defines a set of enumerated values. Each enumerated value consists of an enumerated name and an underlying integer which the software uses internally and in generated code. The following is a MATLAB class definition for an enumerated data type named BasicColors, which is used in all examples in this section.

classdef(Enumeration) BasicColors < Simulink.IntEnumType
  enumeration
    Red(0)
    Yellow(1)
    Blue(2)
  end
end

For information about enumerated data types and their use in Simulink models, see Enumerations and Modeling in the Simulink documentation. For information about enumerated data types in Stateflow charts, see Using Enumerated Data in Stateflow Charts.

Back to Top

Default Code for an Enumerated Data Type

By default, enumerated data types in generated code are defined in the generated header file model_types.h for the model. For example, the default code for BasicColors, which is defined in the previous section, appears as follows:

#ifndef _DEFINED_TYPEDEF_FOR_BasicColors_
#define _DEFINED_TYPEDEF_FOR_BasicColors_

typedef enum {
  Red = 0,            /* Default value */
  Yellow = 1,
  Blue = 2,
} BasicColors;

#endif

Back to Top

Type Casting for Enumerations

How Safe Casting Works

A Simulink Data Type Conversion block can accept a signal of integer type and convert the input to one of the underlying values of an enumerated type.

If the input value does not match any of the underlying values of the enumerated type's values, Simulink can insert a safe cast to replace the input value with the enumerated type's default value.

Enable and Disable Safe Casting

You can enable or disable safe casting for enumerations during code generation for a Simulink Data Type Conversion block or a Stateflow block.

To control safe casting, enable or disable the block's Saturate on integer overflow parameter. The parameter works as follows:

• Enabled: Simulink replaces a non-matching input value with the default value of the enumerated values during simulation and generates a safe cast function during code generation.

• Disabled: For a non-matching input value, Simulink generates an error during simulation and omits the safe cast function during code generation. While the code is more efficient in this case, it may be more vulnerable to runtime errors.

Safe Cast Function in Generated Code

This example shows how the safe cast function int32_T ET08_safe_cast_to_BasicColors for the enumeration BasicColors appears in generated code.

static int32_T ET08_safe_cast_to_BasicColors(int32_T input)
{
	int32_T output;
	/* Initialize output value to default value for BasicColors (Red) */
	output = 0;
	if ((input >= 0) && (input <= 2)) {
	/* Set output value to input value if it is a member of BasicColors */
		output = input;
	}
	return output;
}

Through this function, the enumerated type's default value is used if the input value does not match one of underlying values of the enumerated type's values.

If the block's Saturate on integer overflow parameter is disabled, this function does not appear in generated code.

Back to Top

Override Default Methods (Optional)

Every enumerated class has four associated static methods, which it inherits from Simulink.IntEnumType. You can optionally override any or all of these static methods to customize the behavior of an enumerated type. The methods are:

• getDefaultValue — Returns the default value of the enumerated data type.

• getDescription — Returns a description of the enumerated data type.

• getHeaderFile — Specifies a file where the type is defined for generated code.

• addClassNameToEnumNames — Specifies whether the class name becomes a prefix in code.

The first of these methods, getDefaultValue, is relevant to both simulation and code generation, and is described in Specifying a Default Enumerated Value in the Simulink documentation. The other three methods are relevant only to code generation, and are described in this section. To override any of the methods, include a customized version of the method in the enumerated class definition's methods section. If you do not want to override any default methods, omit the methods section entirely. The following table summarizes the four methods and the data to supply for each one:

Specifying a Description

To specify a description for an enumerated data type, include the following method in the enumerated class's methods section:

function retVal = getDescription() 
% GETDESCRIPTION  Optional string to describe the data type.
  retVal = 'description';
end

Substitute any legal MATLAB string for description. The generated code that defines the enumerated type will include the specified description.

Specify a Header File

To prevent the declaration of an enumerated type from being embedded in the generated code, allowing you to provide the declaration in an external file, include the following method in the enumerated class's methods section:

function retVal = getHeaderFile()
% GETHEADERFILE  File where type is defined for generated code.
%   If specified, this file is #included  in the code.
%   Otherwise, the type is written out in the generated code.
retVal = 'filename';
end

Substitute any legal filename for filename. Be sure to provide a filename suffix, typically .h. Providing the method replaces the declaration that would otherwise have appeared in model_types.h with a #include statement like:

#include "imported_enum_type.h"

The getHeaderFile method does not create the declaration file itself. You must provide a file of the specified name that declares the enumerated data type.

Add Prefixes To Class Names

By default, enumerated values in generated code have the same names that they have in the enumerated class definition. Alternatively, the code can prefix every enumerated value in an enumerated class with the name of the class. This technique can be useful for preventing identifier conflicts or improving the clarity of the code. To specify class name prefixing, include the following method in an enumerated class's methods section:

function retVal = addClassNameToEnumNames()
% ADDCLASSNAMETOENUMNAMES  Control whether class name is added as
%   a prefix to enumerated names in the generated code.
%   By default the code does not use the class name as a prefix.
retVal = boolean;
end

Replace boolean with true to enable class name prefixing, or false to suppress prefixing without having to delete the method itself. If boolean is true, each enumerated value in the class appears in generated code as EnumTypeName_EnumName. For BasicColors, which was defined in About Enumerated Data Types, the data type definition with class name prefixing looks like this:

#ifndef _DEFINED_TYPEDEF_FOR_BasicColors_
#define _DEFINED_TYPEDEF_FOR_BasicColors_

typedef enum {
  BasicColors_Red = 0,            /* Default value */
  BasicColors_Yellow = 1,
  BasicColors_Blue = 2,
} BasicColors;

#endif

In this example, the enumerated class name BasicColors appears as a prefix for each of the enumerated names. The definition is otherwise the same as it would be without name prefixing.

Back to Top

Enumerated Type Limitations

• Generated code does not support logging enumerated data.

Back to Top

Data Representation

Structure Parameters and Generated Code

Related Products & Applications

• Simulink
• Control Design
• Signal Processing & Communications
• Model-Based Design
• Physical Modeling
• Verification & Validation

Get Simulink trial software

Learn more about Simulink through this collection of videos, articles, technical literature and the Getting Started with Simulink Guide.

Get this Simulink Kit