Define Simulink Enumerations

Create Simulink Enumeration Class

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

  • Define the class as a subclass of Simulink.IntEnumType. You can also base an enumerated type on one of these built-in integer data types: int8, uint8, int16, uint16, and int32.

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

Consider the following example:

classdef BasicColors < Simulink.IntEnumType

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.

Enumerated ValueEnumerated NameUnderlying Integer

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. For information on how enumeration classes are handled when there is more than one name for an underlying value, see Aliasing Enumeration Names .

Customize Simulink Enumeration

About Simulink Enumeration Customizations

You can customize a Simulink enumeration by implementing specific static methods in the class definition. If you define these methods using the appropriate syntax, you can change the behavior of the class during simulation and in generated code.

The table shows the methods you can implement to customize an enumeration.

Static MethodPurposeDefault Value Without Implementing MethodCustom Return ValueUsage Context
getDefaultValueSpecifies the default enumeration member for the class.First member specified in the enumeration definitionA string containing the name of an enumeration member in the class (see Instantiate Enumerations)Simulation and code generation
getDescriptionSpecifies a description of the enumeration class.''A string containing the description of the typeCode generation
getHeaderFileSpecifies the name of a header file. The method getDataScope determines the significance of the file.''A string containing the name of the header file that defines the enumerated typeCode generation
getDataScopeSpecifies whether generated code exports or imports the definition of the enumerated data type. Use the method getHeaderFile to specify the generated or included header file that defines the type.'Auto'One of these strings: 'Auto', 'Exported', or 'Imported'Code generation
addClassNameToEnumNamesSpecifies whether to prefix the class name in generated code.falsetrue or falseCode generation

For more examples of these methods as they apply to code generation, see Customize Enumerated Data Type (Optional) in the Simulink Coder™ documentation.

Specify a Default Enumerated Value

wSimulink 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 Type Casting for Enumerations 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 Specifies the default enumeration member.
      % Return a valid member of this enumeration class to specify the default.
      % If you do not define this method, Simulink uses the first member.
      retVal = ThisClass.EnumName;

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
  methods (Static)
    function retVal = getDefaultValue()
      retVal = BasicColors.Blue;

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 Instantiate Enumerations for more information.

Save 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 What Is 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.

Change and Reload 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.

If In Base Workspace...If In Cache...

Do one of the following:

  • Locate and delete specific obsolete instances.

  • Delete everything from the workspace by using the clear command.

  • Delete obsolete instances by closing all models that you updated or simulated while the previous class definition was in effect.

  • Clear functions and close models that are caching instances of the class.

For more information about applying enumeration changes, see Automatic Updates for Modified Classes.

Import 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
	methods (Static = true)
		function retVal = getDescription()
			retVal = 'Basic colors...';
		function retVal = getDefaultValue()
			retVal = BasicColors.Blue;
		function retVal = getHeaderFile()
			retVal = 'mybasiccolors.h'; 
		function retVal = addClassNameToEnumNames()
			retVal = true;

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);
Was this topic helpful?