Documentation Center

  • Trial Software
  • Product Updates

Contents

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

  • 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.

Enumerated ValueEnumerated NameUnderlying Integer
Red(0)Red0
Yellow(1)Yellow1
Blue(2)Blue2

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.

Customize 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 Simulink.defineIntEnumType.

Default MethodDescriptionDefault Value Returned or SpecifiedUsage Context
getDescriptionReturns a description of the enumeration.''Code generation
getHeaderFileSpecifies the file in which the enumeration is defined for code generation.''Code generation
addClassNameToEnumNamesSpecifies whether the class name becomes a prefix in generated code.false — prefix is not usedCode generation

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.

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 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  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 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 Modifying and Reloading 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
	enumeration
		Red(0)
		Yellow(1)
		Blue(2)
	end
	methods (Static = true)
		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
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);
Was this topic helpful?