|On this page…|
Consider the following enumeration class definition—BasicColors with enumerated values Red, Yellow, and Blue, with Blue as the default value:
classdef BasicColors < Simulink.IntEnumType enumeration Red(0) Yellow(1) Blue(2) end methods (Static) function retVal = getDefaultValue() retVal = BasicColors.Blue; end end end
Once this class definition is known to MATLAB®, you can use the enumeration in Simulink® and Stateflow® models. Information specific to enumerations in Stateflow appears in Enumerated Data. The following Simulink model uses the enumeration defined above:
The output of the model looks like this:
The Data Type Conversion block OrigToInt specifies an Output data type of int32 and Integer rounding mode: Floor, so the block converts the Sine Wave block output, which appears in the top graph of the Scope display, to a cycle of integers: 1, 2, 1, 0, 1, 2, 1. The Data Type Conversion block IntToColor uses these values to select colors from the enumerated type BasicColors by referencing their underlying integers.
The result is a cycle of colors: Yellow, Blue, Yellow, Red, Yellow, Blue, Yellow, as shown in the middle graph. The Enumerated Constant block EnumConst outputs Yellow, which appears in the second graph as a straight line. The Relational Operator block compares the constant Yellow to each value in the cycle of colors. It outputs 1 (true) when Yellow is less than the current color, and 0 (false) otherwise, as shown in the third graph.
The sort order used by the comparison is the numeric order of the underlying integers of the compared values, not the lexical order in which the enumerated values appear in the enumerated class definition. In this example the two orders are the same, but they need not be. See Specify Enumerations as Data Types and Enumerated Values in Computation for more information.
Once you define an enumeration, you can use it much like any other data type. Because an enumeration is a class rather than an instance, you must use the prefix ? or Enum: when specifying the enumeration as a data type. You must use the prefix ? in the MATLAB Command Window. However, you can use either prefix in a Simulink model. Enum: has the same effect as the ? prefix, but Enum: is preferred because it is more self-explanatory in the context of a graphical user interface.
Depending on the context, type Enum: followed by the name of an enumeration, or select Enum: <class name> from a menu (for example, for the Output data type block parameter) , and replace <class name>.
To use the Data Type Assistant, set the Mode to Enumerated, then enter the name of the enumeration. For example, in the previous model, the Data Type Conversion block IntToColor, which outputs a signal of type BasicColors, has the following output signal specification:
You cannot set a minimum or maximum value for a signal defined as an enumeration, because the concepts of minimum and maximum are not relevant to the purpose of enumerations. If you change the minimum or maximum for a signal of an enumeration from the default value of , an error occurs when you update the model. See Enumerated Values in Computation for more information.
The functions enumeration and Simulink.data.getEnumTypeInfo return information about enumerated data types.
Use the function enumeration to:
Return an array that contains all enumeration values for an enumeration class in the MATLAB Command Window
Get the enumeration values programmatically
Provide the values to a Simulink block parameter that accepts an array or vector of enumerated values, such as the Case conditions parameter of the Switch Case block
See the enumeration function for details.
The table shows how to use the function Simulink.data.getEnumTypeInfo to return information about an enumerated class BasicColors.
|Return the default enumeration member.|
|Return the description of the class.|
|Return the name of the header file used in generated code.|
|Return the scope of the type definition in generated code.|
|Indicate whether the name of the class prefixes the enumeration members in generated code.|
|Return the data type of the integers underlying the enumeration members.|
Wherever possible, Simulink software displays enumeration values by name, not by the underlying integer value. However, the underlying integers can affect value display in Scope and Floating Scope blocks.
|Block...||Affect on Value Display...|
|Scope||When displaying an enumerated signal, the names of the enumerated values appear as labels on the Y axis. The names appear in the order given by their underlying integers, with the lowest value at the bottom.|
|Floating Scope||When displaying signals that are of the same enumeration, names appear on the Y axis as they would for a Scope block. If the Floating Scope block displays mixed data types, no names appear, and any enumerated values are represented by their underlying integers.|
More than one value in an enumeration can have the same underlying integer value, as described in Specify Enumerations as Data Types. When this occurs, the value on an axis of Scope block output or in Display block output always is the first value listed in the enumerated class definition that has the shared underlying integer. For example:
Although the Enumerated Constant block outputs True, both On and True have the same underlying integer, and On is defined first in the class definition enumeration section. Therefore, the Display block shows On. Similarly, a Scope axis would show only On, never True, no matter which of the two values is input to the Scope block.
Before you can use an enumeration, you must instantiate it. You can instantiate an enumeration in MATLAB, in a Simulink model, or in a Stateflow chart. The syntax is the same in all contexts.
To instantiate an enumeration in MATLAB, enter ClassName.EnumName in the MATLAB Command Window. The instance is created in the base workspace. For example, if BasicColors is defined as in Create Simulink Enumeration Class, you can type:
bcy = BasicColors.Yellow bcy = Yellow
Tab completion works for enumerations. For example, if you enter:
bcy = BasicColors.<tab>
MATLAB displays the elements and methods of BasicColors in alphabetical order:
Double-click an element or method to insert it at the position where you pressed <tab>. See Tab Completion for more information.
In MATLAB, you can cast directly from an integer to an enumerated value:
bcb = BasicColors(2) bcb = Blue
You can also cast from an enumerated value to its underlying integer:
>> bci = int32(bcb) bci = 2
In either case, MATLAB returns the result of the cast in a 1x1 array of the relevant data type.
Although casting is possible, use of enumeration values is not robust in cases where enumeration values and the integer equivalents defined for an enumeration class might change.
To instantiate an enumeration in a Simulink model, you can enter ClassName.EnumName as a value in a dialog box. For example, consider the following model:
The Enumerated Constant block EnumConst, which outputs the enumerated value Yellow, defines that value as follows:
You can enter any valid MATLAB expression that evaluates to an enumerated value, including arrays and workspace variables. For example, you could enter BasicColors(1), or if you had previously executed bcy = BasicColors.Yellow in the MATLAB Command Window, you could enter bcy. As another example, you could enter an array, such as[BasicColors.Red, BasicColors.Yellow, BasicColors.Blue] .
You can use a Constant block to output enumerated values. However, that block displays parameters that do not apply to enumerated types, such as Output Minimum and Output Maximum.
If you create a Simulink.Parameter object as an enumeration, you must specify the Value parameter as an enumeration member and the Data type with the Enum: or ? prefix, as explained in Specify Enumerations as Data Types.
You cannot specify the integer value of an enumeration member for the Value parameter. See Enumerated Values in Computation for more information. Thus, the following fails even though the integer value for BasicColors.Yellow is 1.
The same syntax and considerations apply in Stateflow. See Enumerated Data for more information.
By design, Simulink prevents enumerated values from being used as numeric values in mathematical computation, even though an enumerated class is a subclass of the MATLAB int32 class. Thus, an enumerated type does not function as a numeric type despite the existence of its underlying integers. For example, you cannot input an enumerated signal directly to a Gain block.
You can use a Data Type Conversion block to convert in either direction between an integer type and an enumerated type, or between two enumerated types. That is, you can use a Data Type Conversion block to convert an enumerated signal to an integer signal (consisting of the underlying integers of the enumerated signal values) and input the resulting integer signal to a Gain block. See Casting Enumerated Signals for more information.
Enumerated types in Simulink are intended to represent program states and control program logic in blocks like the Relational Operator block and the Switch block. When a Simulink block compares enumerated values, the values compared must be of the same enumerated type. The block compares enumerated values based on their underlying integers, not their order in the enumerated class definition.
When a block like the Switch block or Multiport Switch block selects among multiple data signals, and any data signal is of an enumerated type, all the data signals must be of that same enumerated type. When a block inputs both control and data signals, as Switch and Multiport Switch do, the control signal type need not match the data signal type.
You can use a Data Type Conversion block to cast an enumerated signal to a signal of any numeric type, provided that the underlying integers of all enumerated values input to the block are within the range of the numeric type. Otherwise, an error occurs during simulation.
Similarly, you can use a Data Type Conversion block to cast a signal of any integer type to an enumerated signal, provided that every value input to the Data Type Conversion block is the underlying integer of some value in the enumerated type. Otherwise, an error occurs during simulation.
You cannot use a Data Type Conversion block to cast a numeric signal of any non-integer data type to an enumerated type. For example, the model used in Simulate with Enumerations needed two Data Conversion blocks to convert a sine wave to enumerated values.
The first block casts double to int32, and the second block casts int32 to BasicColors. You cannot cast a complex signal to an enumerated type regardless of the data types of its real and imaginary parts.
You cannot cast a block parameter of any numeric data type to an enumerated data type. For example, suppose that an Enumerated Constant block specifies a Value of 2 and an Output data type of Enum: BasicColors:
An error occurs because the specifications implicitly cast a double value to an enumerated type. The error occurs even though the numeric value corresponds arithmetically to one of the enumerated values in the enumerated type.
You cannot cast a block parameter of an enumeration to any other data type. For example, suppose that a Constant block specifies a Constant value of BasicColors.Blue and an Output data type of int32.
An error occurs because the specifications implicitly cast an enumerated value to a numeric type. The error occurs even though the enumerated value's underlying integer is a valid int32.