Operations on Enumerations

Operations Supported by Enumerations

You can use logical, set membership, and string comparison operations on enumerations. These operations also support the use of enumerations in conditional statements, such as switch and if statements. The string and char functions enable you to convert enumeration members to strings and char vectors.

Example Enumeration Class

This topic uses the WeekDays class to illustrate how to perform operations on enumerations. The WeekDays class defines members that enumerate days of the week.

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

For information on defining enumerations, see Define Enumeration Classes.

Default Methods

Enumeration classes have the following default methods:

methods('WeekDays')

Methods for class WeekDays:

WeekDays   char       intersect  ne         setxor     strcmpi    strncmp    union      
cellstr    eq         ismember   setdiff    strcmp     string     strncmpi

The WeekDays method converts text formats into enumerations. Supported formats include strings, char vectors, string arrays, and cell arrays of char vectors. For example:

f = WeekDays(["Monday" "Friday"])

f = 

  1×2 WeekDays enumeration array

    Monday    Friday

Convert Enumeration Members to Strings or `char` Vectors

Conversion of enumeration members to strings and char vectors is useful for creating text that contains enumeration member names. For example, use the string function to convert an enumeration member to a string and include it in a sentence:

string(WeekDays.Monday) + " is our meeting day."

ans = 

    "Monday is our meeting day."

Use the char function in a similar way:

['Today is ' char(WeekDays.Friday) '.']

ans =

    'Today is Friday.'

Convert Enumeration Arrays to String Arrays or Cell Arrays of `char` Vectors

Use the string function to convert an enumeration array into a string array:

sa = [WeekDays.Tuesday WeekDays.Thursday];
string(sa)

ans = 

  1×2 string array

    "Tuesday"    "Thursday"

Use cellstr to convert an enumeration array to a cell array of char vectors.

ca = cellstr([WeekDays.Tuesday WeekDays.Thursday]);
class(ca)

ans =

    'cell'

Both cells in the cell array contain char vectors:

class([ca{1:2}])

ans =

    'char'

Relational Operations with Enumerations, Strings, and `char` Vectors

You can compare enumeration instances with char vectors and strings using the relational operators eq (==) and ne (~=), as well as the isequal method.

Relational Operators `eq` and `ne`

Use eq and ne to compare enumeration members with text values. For example, you can compare an enumeration member with a string:

today = WeekDays.Friday;
today == "Friday"

ans =

  logical

   1

Compare an enumeration array to one char vector. The return value is a logical array indicating which members of the enumeration array are equivalent to the char vector:

wd = [WeekDays.Monday WeekDays.Wednesday WeekDays.Friday];
wd == 'Friday'

ans =

  1×3 logical array

   0   0   1

This example uses the ne function to compare the corresponding elements of an enumeration array and a string array of equal length:

sa = ["Monday" "Wednesday" "Friday"];
md = [WeekDays.Tuesday WeekDays.Thursday WeekDays.Friday];
md ~= sa

ans =

  1×3 logical array

   1   1   0

The char vector Wednesday is equal to (==) the enumeration member WeekDays.Wednesday. You can use this equality in conditional statements:

today = 'Wednesday';
   ...
if today == WeekDays.Wednesday
   disp('Team meeting at 2:00')
end

`isequal` Method

The isequal method also enables comparisons between enumeration instances and strings, character vectors, string arrays, and cell arrays of character vectors.

a = WeekDays.Monday;
isequal(a,"Monday")

ans =

     logical

     1

When comparing an enumeration array to a single item, the behavior of isequal differs slightly from eq and ne. The isequal method requires that the two values being compared are the same size. Therefore, isequal returns false when comparing an enumeration array to a char vector or string scalar, even if the text matches one of the enumeration members in the array.

wd = [WeekDays.Monday WeekDays.Wednesday WeekDays.Friday];
isequal(wd,"Friday")

ans =

     logical

     0

Enumerations in `switch` Statements

Equality (eq) and inequality (ne) functions enable you to use enumeration members in switch statements. For example, using the WeekDays enumeration defined previously, construct a switch statement:

function c = Reminder(day)
   % Add error checking here
   switch(day)
      case WeekDays.Monday
         c = 'No meetings';
      case WeekDays.Tuesday
         c = 'Department meeting at 10:00';
      case {WeekDays.Wednesday WeekDays.Friday}
         c = 'Team meeting at 2:00';
      case WeekDays.Thursday
         c = 'Volleyball night';
   end
end

Pass a member of the WeekDays enumeration class to the Reminder function:

today = WeekDays.Wednesday;
Reminder(today)

ans =

Team meeting at 2:00

For more information, see Objects in Conditional Statements.

Substitute Strings or `char` Vectors

You can use strings or char vectors to represent specific enumeration members:

function c = Reminder2(day)
   switch(day)
      case 'Monday'
         c = 'Department meeting at 10:00';
      case 'Tuesday'
         c = 'Meeting Free Day!';
      case {'Wednesday' 'Friday'}
         c = 'Team meeting at 2:00';
      case 'Thursday'
         c = 'Volleyball night';
   end
end

Although you can use char vectors or strings instead of specifying enumerations explicitly, MATLAB^® must convert the text format to an enumeration. Eliminate the need for this conversion if it is not necessary.

Enumeration Set Membership

Enumeration classes provide methods to determine set membership.

ismember — True for elements of an enumeration array if in a set
setdiff — Set difference for enumeration arrays
intersect — Set intersection for enumeration arrays
setxor — Set exclusive-or for enumeration arrays
union — Set union for enumeration arrays

Determine if today is a meeting day for your team. Create a set of enumeration members corresponding to the days on which the team has meetings.

today = WeekDays.Tuesday;
teamMeetings = [WeekDays.Wednesday WeekDays.Friday];

Use ismember to determine if today is part of the teamMeetings set:

ismember(today,teamMeetings)

ans = 
     0

Mixed Sets of Enumeration and Text

If you pass both enumeration members and text values to an enumeration class method, the class attempts to convert the text value to the class of the enumeration.

Determine if the char vector 'Friday' is a member of the enumeration array.

teamMeetings = [WeekDays.Wednesday WeekDays.Friday];
ismember('Friday',teamMeetings)

ans =

  logical

   1

Determine if the enumeration member is a member of the string array.

ismember(WeekDays.Friday,["Wednesday" "Friday"])

ans =

  logical

   1

Enumeration Text Comparison Methods

Enumeration classes provide methods to compare enumeration members with text. One of the arguments to the string comparison methods must be a char vector or a string. Comparing two enumeration members returns false.

strcmp — Compare enumeration members
strncmp — Compare first n characters of enumeration members
strcmpi — Case insensitive comparison of enumeration members
strncmpi — Case insensitive first n character comparison of enumeration members

Comparing Enumeration Member with Strings or `char` Vectors

The string comparison methods can compare enumeration members with char vectors and strings.

today = WeekDays.Tuesday;
strcmp(today,'Friday')

ans =

     0

strcmp(today,"Tuesday")

ans =

     1

Get Information About Enumerations

Obtain information about enumeration classes using the enumeration function. For example:

enumeration WeekDays

Enumeration members for class 'WeekDays':

    Monday
    Tuesday
    Wednesday
    Thursday
    Friday

For more information on how class introspection works with enumerations, see Metaclass EnumeratedValues Property.

Testing for an Enumeration

To determine if a value is an enumeration, use the isenum function. For example:

today = WeekDays.Wednesday;
isenum(today)

ans =

     1

isenum returns true for empty enumeration objects:

noday = WeekDays.empty;
isenum(noday)

ans =

     1

To determine if a class is an enumeration class, use the matlab.metadata.Class object.

today = WeekDays.Wednesday;
mc = metaclass(today);
mc.Enumeration

ans =

     1