Mutable Handle vs. Immutable Value Enumeration Members

Select Handle- or Value-Based Enumerations

Use a handle enumeration to define a set of objects whose state can change over time. Use a value enumeration to define a set of 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 that are defined explicitly in the classdef file. To modify the set of values for a given enumeration class, you must modify the enumeration in the classdef file itself.

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 can also define properties. 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

The properties defined by an enumeration class are immutable.

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

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.

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.

Handle-Based Enumeration Members Based on Properties

If a handle-based enumeration class defines members based on properties, changing the property values of an instance changes the members for all references to that instance.

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

See Also

Topics