Mutable (Handle) vs. Immutable (Value) Enumeration Members

Basic Knowledge

The material presented in this section builds on an understanding of the information provided in the following sections.

• Comparing Handle and Value Classes

• enumeration function displays enumeration names

See for general information about these two kinds of classes.

Back to Top

Selecting Handle- or Value-Based Enumerations

Use a handle enumeration when you want to enumerate a set of objects whose state might change over time. Use a value enumeration to enumerate a set of abstract (and immutable) values.

Back to Top

Value-Based Enumeration Classes

A value-based enumeration class has a fixed set of specific values. You cannot modify these values by changing the values of properties because doing so expands or changes the fixed set of values for this enumeration class.

Inherited Property SetAccess Must Be Immutable

Value-based enumeration class implicitly define the SetAccess attributes of all properties as immutable. You cannot set the SetAccess attribute to any other value.

However, all superclass properties must explicitly define property SetAccess as immutable. See Property Attributes for more information on property attributes.

Enumeration Members Remain Constant

When you create an instance of a value-based enumeration class, this instance is unique until the class is cleared and reloaded. For example, given the following class:

classdef WeekDays
   enumeration
      Monday, Tuesday, Wednesday, Thursday, Friday
   end
end

MATLAB considers a and b as equivalent:

a = WeekDays.Monday;
b = WeekDays.Monday;
isequal(a,b)
ans =

     1

a == b
ans =

     1

Enumeration Member Properties Remain Constant

Value-based enumeration classes that define properties are immutable. For example, the Colors enumeration class associates RGB values with color names.

classdef Colors
   properties
      R = 0;
      G = 0;
      B = 0;
   end
      methods
      function c = Colors(r, g, b)
         c.R = r; c.G = g; c.B = b;
      end
   end
      enumeration
      Red   (1, 0, 0)
      Green (0, 1, 0)
      Blue  (0, 0, 1)
   end
end

The constructor assigns the input arguments to R, G, and B properties:

red = Colors.Red;

You cannot change a property value:

red.G = 1;
Setting the 'G' property of the 'Colors' class is not allowed.

Back to Top

Handle-Based Enumeration Classes

Handle-based enumeration classes that define properties are mutable. Derive enumeration classes from the handle class when you must be able to change property values on instances of that class.

Note   You cannot derive an enumeration class from matlab.mixin.Copyable because the number of instances you can create are limited to the ones defined inside the enumeration block.

An Enumeration Member Remains Constant

Given a handle-based enumeration class with properties, changing the property value of an instance causes all references to that instance to reflect the changed value.

For example, the HandleColors enumeration class associates RGB values with color names, the same as the Colors class in the previous example. However, HandleColors derives from handle:

classdef HandleColors < handle
% Enumeration class derived from handle
   properties
      R = 0;
      G = 0;
      B = 0;
   end
   
   methods
      function c = HandleColors(r, g, b)
         c.R = r; c.G = g; c.B = b;
      end
   end
   
   enumeration
      Red (1, 0, 0)
... % Other colors omitted
   end
end

Create an instance of HandleColors.Red and return the value of the R property:

a = HandleColors.Red;
a.R

ans =

    1

MATLAB constructs the HandleColors.Red enumeration member, which sets the R property to 1, the G property to 0, and the B property to 0.

Change the value of the R property to .8:

a.R = .8;

After setting the value of the R property to .8, create another instance, b, of HandleColors.Red:

b = HandleColors.Red;

b.R

ans =

    0.8000

The value of the R property of the newly created instance is also 0.8000. The MATLAB session has only one value for any enumeration member at any given time.

Clearing the workspace variables does not change the current definition of the enumeration member HandleColors.Red:

clear
a = HandleColors.Red;
a.R

ans =

    0.8000

Clear the class to reload the definition of the HandleColors class (see clear classes):

clear classes
a = HandleColors.Red;

a.R

ans =

     1

If you do not want to allow reassignment of a given property value, set that property's SetAccess attribute to immutable.

See Property Attributes for more information about property attributes.

Equality of Handle-Based Enumerations

Suppose you assign two variables to a particular enumeration member:

a = HandleColors.Red;
b = HandleColors.Red;

You can compare a and b using isequal:

>> isequal(a,b)

ans =

     1

The property values of a and b are the same, so isequal returns true. However, unlike nonenumeration handle classes, a and b are the same handle because there is only one enumeration member. Determine handle equality using == (the handle eq method).

>> a == b

ans =

     1

See the handle eq method for information on how isequal and == differ when used with handles.

Back to Top

Example – Using Enumerations to Represent a State

The MachineState class defines two enumeration members to represent the state of a machine, either running or not running.

classdef MachineState
   enumeration
      Running
      NotRunning
   end   
end

The Machine class represents a machine with start and stop operations. The MachineState enumerations are easy to work with because of their eq and char methods, and they result in code that is easy to read.

classdef Machine < handle
   properties (SetAccess = Private)
      State = MachineState.NotRunning;
   end
   
   methods
      function start(machine)
         if machine.State == MachineState.NotRunning
            machine.State = MachineState.Running;
         end
         disp (machine.State.char)
      end
      function stop(machine)
         if machine.State == MachineState.Running
            machine.State = MachineState.NotRunning;
         end
         disp (machine.State.char)
      end
   end
end

Create a Machine object and call start and stop methods:

% Create a Machine object
>> m = Machine;
% Start the machine
>> m.start
Running
% Stop the machine
>> m.stop
NotRunning

Back to Top

Enumerations Derived from Built-In Classes

Enumerations That Encapsulate Data

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