Main Content

Mutable Handle vs. Immutable Value Enumeration Members

Select Handle- or Value-Based Enumerations

Use a handle enumeration to enumerate a set of objects whose state can change over time. Use a value enumeration to enumerate a set of abstract (and immutable) values. For information about handle and value classes, see Comparison of Handle and Value Classes.

Value-Based Enumeration Classes

A value-based enumeration class has a fixed set of specific values. Modify these values by changing the values of properties. Doing so expands or changes the fixed set of values for this enumeration class.

Inherited Property SetAccess Must Be Immutable

Value-based enumeration classes 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.

Enumeration Members Remain Constant

An instance of a value-based enumeration class is unique until the class is cleared and reloaded. For example, given this 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;
[red.R,red.G,red.B]
ans =

     1     0     0

You cannot change a property value:

red.G = 1;
You cannot set the read-only property 'G' of Colors.

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
   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)
      Green (0, 1, 0)
      Blue  (0, 0, 1)
   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 0.8:

a.R = 0.8;

After setting the value of the R property to 0.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.8. A 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:

clear classes
a = HandleColors.Red;
a.R
ans =

     1

To prevent reassignment of a given property value, set that property's SetAccess attribute to immutable.

Equality of Handle-Based Enumerations

Assign two variables to a particular enumeration member:

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

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 handle classes that are not enumeration 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.

Represent State with Enumerations

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

m = Machine;
m.start
Running
m.stop
NotRunning

Related Topics