Defining Simulink Enumerations

Basic Workflow for Defining a Simulink Enumeration

1. Create a class definition.

2. Optionally, customize the enumeration.

3. Optionally, save the enumeration in a MATLAB file.

For complete information about the MATLAB Object System, see Object-Oriented Programming.

Back to Top

Creating a Simulink Enumeration Class

To create a Simulink enumeration class, in the class definition:

• Define the class as a subclass of Simulink.IntEnumType

• Add an enumeration block that specifies enumeration values with underlying integer values

Consider the following example:

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

The first line defines an integer-based enumeration that is derived from built-in class Simulink.IntEnumType. The enumeration is integer-based because IntEnumType is derived from int32.

The enumeration section specifies three enumerated values.

When defining an enumeration class for use in the Simulink environment, consider the following:

• The name of the enumeration class must be unique among data type names and base workspace variable names, and is case-sensitive.

• Underlying integer values in the enumeration section need not be unique within the class and across types.

• Often, the underlying integers of a set of enumerated values are consecutive and monotonically increasing, but they need not be either consecutive or ordered.

• For simulation, an underlying integer can be any int32 value. Use the MATLAB functions intmin and intmax to get the limits.

• For code generation, every underlying integer value must be representable as an integer on the target hardware, which may impose different limits. See Target and Hardware Implementation Pane for more information.

For more information on superclasses, see Converting to Superclass Value.

Back to Top

Customizing a Simulink Enumeration

About Simulink Enumeration Customizations

You can customize a Simulink enumeration by using the same techniques that work with MATLAB classes, as described in Modifying Superclass Methods and Properties.

A primary source of customization are the methods associated with an enumeration.

Inherited Methods

Enumeration class definitions can include an optional methods section. Simulink enumerated classes inherit the following static methods from the superclass Simulink.IntEnumType. For more information about these methods, see .

Overriding Inherited Methods

You can override the inherited methods to customize the behavior of an enumeration. To override a method, include a customized version of the method in the methods section in the enumerated class definition. If you do not want to override the inherited methods, omit the methods section.

For information on overriding the inherited methods, see Overriding Default Methods (Optional) in the Simulink Coder documentation.

Specifying a Default Enumerated Value

Simulink software and related generated code use an enumeration's default value for ground-value initialization of enumerated data when you provide no other initial value. For example, an enumerated signal inside a conditionally executed subsystem that has not yet executed has the enumeration's default value. Generated code uses an enumeration's default value if a safe cast fails, as described in Enumerated Type Safe Casting in the Simulink Coder documentation.

Unless you specify otherwise, the default value for an enumeration is the first value in the enumeration class definition. To specify a different default value, add your own getDefaultValue method to the methods section. The following code shows a shell for the getDefaultValue method:

function retVal = getDefaultValue()
% GETDEFAULTVALUE  Returns the default enumerated value.
%   This value must be an instance of the enumerated class.
%   If this method is not defined, the first enumeration is used.
  retVal = ThisClass.EnumName;
end

To customize this method, provide a value for ThisClass.EnumName that specifies the desired default.

• ThisClass must be the name of the class within which the method exists.

• EnumName must be the name of an enumerated value defined in that class.

For example:

classdef BasicColors < Simulink.IntEnumType
  enumeration
    Red(0)
    Yellow(1)
    Blue(2) 
  end
  methods (Static)
    function retVal = getDefaultValue()
      retVal = BasicColors.Blue;
    end
  end
end 

This example defines the default as BasicColors.Blue. If this method does not appear, the default value would be BasicColors.Red, because that is the first value listed in the enumerated class definition.

The seemingly redundant specification of ThisClass inside the definition of that same class is necessary because getDefaultValue returns an instance of the default enumerated value, not just the name of the value. The method, therefore, needs a complete specification of what to instantiate. See Instantiating Enumerations for more information.

Back to Top

Saving an Enumeration in a MATLAB File

You can define an enumeration within a MATLAB file.

• The name of the definition file must match the name of the enumeration exactly, including case. For example, the definition of enumeration BasicColors must reside in a file named BasicColors.m. Otherwise, MATLAB will not find the definition.

• You must define each class definition in a separate file.

• Save each definition file on the MATLAB search path. MATLAB searches the path to find a definition when necessary.

  To add a file or folder to the MATLAB search path, type addpath pathname at the MATLAB command prompt. For more information, see Using the MATLAB Search Path, addpath, and savepath.

• You do not need to execute an enumeration class definition to use the enumeration. The only requirement, as indicated in the preceding bullet, is that the definition file be on the MATLAB search path.

Back to Top

Changing and Reloading Enumerations

You can change the definition of an enumeration by editing and saving the file that contains the definition. You do not need to inform MATLAB that a class definition has changed. MATLAB automatically reads the modified definition when you save the file. However, the class definition changes do not take full effect if any class instances (enumerated values) exist that reflect the previous class definition. Such instances might exist in the base workspace or might be cached.

The following table explains options for removing instances of an enumeration from the base workspace and cache.

For more information about applying enumeration changes, see Modifying and Reloading Classes.

Back to Top

Importing Enumerations Defined Externally to MATLAB

If you have enumerations defined externally to MATLAB—for example, in a data dictionary, that you want to import for use within the Simulink environment, you can do so programmatically with calls to the function Simulink.defineIntEnumType. This function defines an enumeration that you can use in MATLAB as if it is defined by a class definition file. In addition to specifying the enumeration class name and values, each function call can specify:

• String that describes the enumeration class.

• Which of the enumeration values is the default.

For code generation, you can specify:

• Header file in which the enumeration is defined for generated code.

• Whether the code generator applies the class name as a prefix to enumeration members—for example, BasicColors_Red or Red.

As an example, consider the following class definition:

classdef BasicColors < Simulink.IntEnumType
  enumeration
    Red(0)
    Yellow(1)
    Blue(2) 
  end
  methods (static)
    function retVal = getDescription()
      retVal = 'Basic colors...';
    end
    function retVal = getDefaultValue()
      retVal = BasicColors.Blue;
    end
    function retVal = getHeaderFile() 
      retVal = 'mybasiccolors.h'; 
    end 
    function retVal = addClassNameToEnumNames() 
      retVal = true; 
    end
end 

The following function call defines the same class for use in MATLAB:

Simulink.defineIntEnumType('BasicColors', ... 
     {'Red', 'Yellow', 'Blue'}, [0;1;2],...
     'Description', 'Basic colors', ...
     'DefaultValue', 'Blue', ...
     'HeaderFile', 'mybasiccolors.h'
     'DataScope', 'Imported'
     'AddClassNameToEnumNames', true);

Back to Top

About Simulink Enumerations

Using Enumerated Data in Simulink Models

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