Working with Enumerated Data

Enumerated Data in the Embedded MATLAB Subset

Enumerated data is data that has a finite set of values. An enumerated data type is a user-defined type whose values belong to a predefined set of symbols, also called enumerated values.

The Embedded MATLAB subset supports integer-based enumerated types, where each enumerated value consists of a name and an underlying numeric value. You define an enumerated type as a MATLAB class; the instances of the class represent the values that comprise the enumerated type.

For example, the following MATLAB script defines an integer-based enumerated data type named PrimaryColors:

classdef(Enumeration) PrimaryColors < int32
    enumeration
        Red(1),
        Blue(2),
        Yellow(4)
    end
end

In this example, the statement classdef(Enumeration) PrimaryColors < int32 means that the enumerated type PrimaryColors is based on the built-in type int32. As such, PrimaryColors inherits the characteristics of the int32 type, as well as defining its own unique characteristics. For example, PrimaryColors is restricted to three enumerated values:

The Embedded MATLAB subset supports another enumerated type, based on the built-in type Simulink.IntEnumType, which requires a Simulink license.

See Also

• Types of Enumerated Data Supported by Embedded MATLAB

• How to Define Enumerated Data in Embedded MATLAB Code

• Defining and Organizing Classes in the MATLAB Object-Oriented Programming documentation for more information about defining MATLAB classes

• Enumerated Data in Simulink for more information about enumerated types based on Simulink.IntEnumType

Back to Top

When to Use Enumerated Data in Embedded MATLAB Functions

You can use enumerated types to represent program states and to control program logic, especially when you need to restrict data to a finite set of values and refer to these values by name. Even though you can sometimes achieve these goals by using integers or strings, enumerated types offer the following advantages:

• Provide more readable code than integers

• Allow more robust error checking than integers or strings

  For example, if you mistype the name of an element in the enumerated type, the Embedded MATLAB subset alerts you that the element does not belong to the set of allowable values.

• Produce more efficient code than strings

  For example, comparisons of enumerated values execute faster than comparisons of strings.

Back to Top

Types of Enumerated Data Supported by Embedded MATLAB

Enumerated types in MATLAB are user-defined types that are based on built-in data types. The enumerated type inherits the characteristics of the built-in type, but also defines its own unique characteristics. For an example, see Enumerated Data in the Embedded MATLAB Subset.

The Embedded MATLAB subset supports two integer-based enumerated data types, each of which inherits characteristics from a different built-in type:

• Enumerated Type Based on int32

• Enumerated Type Based on Simulink.IntEnumType

Enumerated Type Based on int32

This enumerated data type is based on the built-in type int32. Use this enumerated type when generating C-MEX functions from M-code that is compliant with the Embedded MATLAB subset. You can use C-MEX functions for rapid prototyping and verification of generated C code within MATLAB.

Syntax.  

classdef(Enumeration) type_name < int32

Example.  

classdef(Enumeration) PrimaryColors < int32
    enumeration
        Red(1),
        Blue(2),
        Yellow(4)
    end
end

How to Use.   Define enumerated data in M-code and compile your M-file with emlmex, as described in Using Enumerated Data in Embedded MATLAB Compliant M-Code.

Enumerated Type Based on Simulink.IntEnumType

This enumerated data type is based on the built-in type Simulink.IntEnumType, which is available with a Simulink license. Use this enumerated type when:

• Exchanging enumerated data with Simulink blocks and Stateflow charts

• Generating embeddable C code from Embedded MATLAB compliant M-code

Syntax.  

classdef(Enumeration) type_name < Simulink.IntEnumType

Example.  

classdef(Enumeration) myMode < Simulink.IntEnumType
  enumeration
    OFF(0)
    ON(1)
  end
end

How to Use.   Here are the basic guidelines for using enumerated data based on Simulink.IntEnumType:

For more information, see:

• Using Enumerated Data in Embedded MATLAB Function Blocks in the Simulink documentation

• Using Enumerated Data in Stateflow Charts in the Stateflow documentation

• How emlc Works with Enumerated Types in the Real-Time Workshop documentation

Back to Top

Simple Example: Defining and Using Enumerated Types in Embedded MATLAB Compliant M-Code

• About the Example

• Class Definition: sysMode

• Class Definition: LEDcolor

• M-Function: displayState

About the Example

The following example appears throughout this section to illustrate how to define and use enumerated types. It is a simple M-function, displayState, that uses enumerated data to represent the modes of a device that controls the colors of an LED display.

Before you can use enumerated data in Embedded MATLAB compliant M-code, you must define your enumerated data types as MATLAB classes that inherit from the built-in type int32. Each class definition must reside in a separate M-file on the MATLAB path. This example uses two enumerated types: sysMode to represent the set of allowable modes and LEDcolor to represent the set of allowable colors.

See Also.  

• Using Enumerated Data in Embedded MATLAB Compliant M-Code

• How to Define Enumerated Data in Embedded MATLAB Code

• How to Instantiate Enumerated Types in the Embedded MATLAB Subset

• How to Generate C-MEX Functions for Enumerated Data

Class Definition: sysMode

Here is the class definition of the sysMode enumerated data type:

classdef(Enumeration) sysMode < int32
  enumeration
    OFF(0)
    ON(1)
  end
end

This definition must reside on the MATLAB path in an M-file with the same name as the class, sysMode.m.

Class Definition: LEDcolor

Here is the class definition of the LEDcolor enumerated data type:

classdef(Enumeration) LEDcolor < int32
    enumeration
        GREEN(1),
        RED(2),
    end
end

This definition must reside on the MATLAB path in an M-file called LEDcolor.m.

M-Function: displayState

The following M-function displayState uses enumerated data to activate an LED display, based on the state of a device. It lights a green LED display to indicate the ON state and lights a red LED display to indicate the OFF state.

function led = displayState(state)
%#eml

if state == sysMode.ON
    led = LEDcolor.GREEN;
else
    led = LEDcolor.RED;
end

This function models a simple control.

Compiler directive %#eml ensures compliance with the Embedded MATLAB subset. See Adding the Compilation Directive %#eml.

Back to Top

Using Enumerated Data in Embedded MATLAB Compliant M-Code

Here is the basic workflow for using enumerated data when generating C-MEX functions from Embedded MATLAB compliant M-code:

Back to Top

How to Define Enumerated Data in Embedded MATLAB Code

Follow these steps:

1. Create a class definition file.

   In the MATLAB Command Window, select File > New > Class M-File.

2. Enter the class definition as follows:

   classdef(Enumeration) EnumTypeName < int32

   For example, the following code defines an enumerated type called sysMode:

   classdef(Enumeration) sysMode < int32
       ...
   end

   EnumTypeName is a case-sensitive string that must be unique among data type names and workspace variable names. It must inherit from the built-in type int32.

3. Define enumerated values in an enumeration section as follows:

   classdef(Enumeration) EnumTypeName < int32
     enumeration
       EnumName(N)
       ...
     end
   end

   For example, the following code defines a set of two values for enumerated type sysMode:

   classdef(Enumeration) sysMode < int32
       enumeration
            OFF(0)
            ON(1)
       end
   
   end

   An enumerated type can define any number of values. Each enumerated value consists of a string EnumName and an underlying integer N. Each EnumName must be unique within its type, but can also appear in other enumerated types. The underlying integers need not be either consecutive or ordered, nor must they be unique within the type or across types.

4. Save the M-file on the MATLAB path.

   The name of the M-file must match the name of the enumerated data type. The match is case sensitive.

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

For examples of enumerated data type definitions, see Class Definition: sysMode and Class Definition: LEDcolor.

Back to Top

How to Instantiate Enumerated Types in the Embedded MATLAB Subset

To instantiate an enumerated type in Embedded MATLAB code, use dot notation to specify ClassName.EnumName. For example, the following Embedded MATLAB function displayState instantiates the enumerated types sysMode and LEDcolor from Simple Example: Defining and Using Enumerated Types in Embedded MATLAB Compliant M-Code. The dot notation appears highlighted in the code.

function led = displayState(state)
%#eml

if state == sysMode.ON
    led = LEDcolor.GREEN;
else
    led = LEDcolor.RED;
end

Back to Top

How to Generate C-MEX Functions for Enumerated Data

Use the command emlmex to generate C-MEX functions from Embedded MATLAB compliant code that uses enumerated data. Each enumerated data type must be defined on the MATLAB path in a separate M-file as a class derived from the built-in type int32. See How to Define Enumerated Data in Embedded MATLAB Code.

If your Embedded MATLAB function has inputs, you must specify the properties of these inputs to emlmex. For an enumerated data input, use the -eg option to pass one of its allowable values as a sample value. For example, the following emlmex command specifies that the function displayState takes one input of enumerated data type sysMode.

emlmex  displayState -eg {sysMode.ON}

After executing this command, emlmex generates a platform-specific C-MEX function that you can test in MATLAB. For example, to test displayState, type the following command:

displayState(sysMode.OFF) 

You should get the following result:

ans = 

    RED

See Also

• Working with Embedded MATLAB MEX to learn more about emlmex

• Simple Example: Defining and Using Enumerated Types in Embedded MATLAB Compliant M-Code for a description of the example function displayState and its enumerated type definitions

Back to Top

Operations on Enumerated Data in the Embedded MATLAB Subset

The following operations work with enumerated operands in the Embedded MATLAB subset. The examples are based on the definitions of the enumeration type LEDcolor described in Class Definition: LEDcolor.

Assignment Operator, =

xon = LEDcolor.GREEN
xoff = LEDcolor.RED

xon = 

    GREEN
xoff = 

    RED

Relational Operators, < > <= >= == ~=

xon == xoff

ans =

     0

xon <= xoff

ans =

     1

xon > xoff

ans =

     0

Cast Operation

double(LEDcolor.RED)

ans =

     2

z = 2
y = LEDcolor(z)

z =

     2


y = 

    RED

Indexing Operation

m = [1 2]
n = LEDcolor(m)
p = n(LEDcolor.GREEN)

m =

     1     2


n = 

    GREEN    RED  


p = 

    GREEN

Control Flow Statements: if, switch, while

if state == sysMode.ON
    led = LEDcolor.GREEN;
else
    led = LEDcolor.RED;
end

switch button
    case VCRButton.Stop
        state = VCRState.Stop;
    case VCRButton.PlayOrPause
        state = VCRState.Play;
    case VCRButton.Next
        state = VCRState.Forward;
    case VCRButton.Previous
        state = VCRState.Rewind;
    otherwise
         state = VCRState.Stop;
end

while state ~= State.Ready
    switch state
        case State.Standby
            initialize();
            state = State.Boot;
        case State.Boot
            boot();
            state = State.Ready;
    end
end

Back to Top

Examples: Using Enumerated Data in Control Flow Statements in the Embedded MATLAB Subset

The following control statements work with enumerated operands in the Embedded MATLAB subset.

Using the if Statement on Enumerated Data Types

This example is based on the definition of the enumeration types LEDcolor and sysMode. The M-function displayState uses these enumerated data types to activate an LED display.

Class Definition: sysMode.   Here is the class definition of the sysMode enumerated data type:

classdef(Enumeration) sysMode < int32
  enumeration
    OFF(0)
    ON(1)
  end
end

This definition must reside on the MATLAB path in an M-file with the same name as the class, sysMode.m.

Class Definition: LEDcolor.   Here is the class definition of the LEDcolor enumerated data type:

classdef(Enumeration) LEDcolor < int32
    enumeration
        GREEN(1),
        RED(2),
    end
end

This definition must reside on the MATLAB path in an M-file called LEDcolor.m.

M-Function: displayState.   The following M-function displayState uses enumerated data to activate an LED display, based on the state of a device. It lights a green LED display to indicate the ON state and lights a red LED display to indicate the OFF state.

function led = displayState(state)
%#eml

if state == sysMode.ON
    led = LEDcolor.GREEN;
else
    led = LEDcolor.RED;
end

Build and Test a C-MEX Executable for displayState.  

1. Generate a C-MEX executable for displayState. Use the -eg option to pass one of the allowable values for the enumerated data input as a sample value.

   emlmex  displayState -eg {sysMode.ON}

2. Test the function. For example,

   displayState(sysMode.OFF)

   You should get the following result:

   ans = 
   
       RED

Using the switch Statement on Enumerated Data Types

This example is based on the definition of the enumeration types VCRState and VCRButton. The M-function VCR uses these enumerated data types to set the state of the VCR.

Class Definition: VCRState.   Here is the class definition of the VCRState enumerated data type:

classdef(Enumeration) VCRState < int32
    enumeration
        Stop(0),
        Pause(1),
        Play(2),
        Forward(3),
        Rewind(4)
    end
end

This definition must reside on the MATLAB path in an M-file with the same name as the class, VCRState.m.

Class Definition: VCRButton.   Here is the class definition of the VCRButton enumerated data type:

classdef(Enumeration) VCRButton < int32
    enumeration
        Stop(1),
        PlayOrPause(2),
        Next(3),
        Previous(4)
    end
end

This definition must reside on the MATLAB path in an M-file with the same name as the class, VCRButton.m.

M-Function: VCR.   The following M-function VCR uses enumerated data to set the state of a VCR, based on the initial state of the VCR and the state of the VCR button.

function s = VCR(button) 
%#eml

persistent state

if isempty(state)
    state = VCRState.Stop;
end

switch state
    case {VCRState.Stop, VCRState.Forward, VCRState.Rewind}
        state = handleDefault(button);
    case VCRState.Play
        switch button
            case VCRButton.PlayOrPause, state = VCRState.Pause;
            otherwise, state = handleDefault(button);
        end
    case VCRState.Pause
        switch button
            case VCRButton.PlayOrPause, state = VCRState.Play;
            otherwise, state = handleDefault(button);
        end
end
s = state;
 
function state = handleDefault(button)
switch button
    case VCRButton.Stop, state = VCRState.Stop;
    case VCRButton.PlayOrPause, state = VCRState.Play;
    case VCRButton.Next, state = VCRState.Forward;
    case VCRButton.Previous, state = VCRState.Rewind;
    otherwise, state = VCRState.Stop;
end

Build and Test a C-MEX Executable for VCR.  

1. Generate a C-MEX executable for VCR. Use the -eg option to pass one of the allowable values for the enumerated data input as a sample value.

   emlmex  -eg {VCRButton.Stop}  VCR

2. Test the function. For example,

   s = VCR(VCRButton.Stop)

   You should get the following result:

   s = 
   
       Stop   

Using the while Statement on Enumerated Data Types

This example is based on the definition of the enumeration type State. The M-function Setup uses this enumerated data type to set the state of a device.

Class Definition: State.   Here is the class definition of the State enumerated data type:

classdef(Enumeration) State < int32
    enumeration
        Standby(0),
        Boot(1),
        Ready(2)
     end
end

This definition must reside on the MATLAB path in an M-file with the same name as the class, State.m.

M-Function: Setup.   The following M-function Setup uses enumerated data to set the state of a device.

function s = Setup(initState)
%#eml

state = initState;

if isempty(state)
    state = State.Standby;
end

while state ~= State.Ready
    switch state
        case State.Standby
            initialize();
            state = State.Boot;
        case State.Boot
            boot();
            state = State.Ready;
    end
end
s = state;

function initialize()
% Perform initialization.

function boot()
% Boot the device.

Build and Test a C-MEX Executable for Setup.  

1. Generate a C-MEX executable for Setup. Use the -eg option to pass one of the allowable values for the enumerated data input as a sample value.

   emlmex Setup -eg {State.Standby}

2. Test the function. For example,

   s = Setup(State.Standby)

   You should get the following result:

   s = 
   
       Ready   

Back to Top

Embedded MATLAB Library Functions That Support Enumerated Types

The following Embedded MATLAB library functions support enumerated types:

• cast

• cat

• circshift

• flipdim

• fliplr

• flipud

• histc

• ipermute

• isequal

• isequalwithequalnans

• isfinite

• isinf

• isnan

• issorted

• length

• permute

• repmat

• reshape

• rot90

• shiftdim

• sort

• sortrows

• squeeze

Back to Top

Limitations of Enumerated Types in the Embedded MATLAB Subset

 Use a unique name for each enumerated data type

 Do not use enumerated data as the control variable in switch statements

 Do not use enumerated data as the loop counter variable in for- loops

classdef(Enumeration) ColorCodes < int32
    enumeration
        Red(1),
        Blue(2),
        Green(3)
        Yellow(4)
        Purple(5)
    end
end

...
for i = int32(ColorCodes.Red):int32(ColorCodes.Purple)
     c = ColorCodes(i);
     ...
end

Back to Top

Generating Code for Variable-Size Data

Working with Structures

Recommended Products

• MATLAB
• Signal Processing Toolbox
• Optimization Toolbox
• Statistics Toolbox
• Control System Toolbox

Get MATLAB trial software

Includes the most popular MATLAB recorded presentations with Q&A sessions led by MATLAB experts.

Get the Interactive Kit