V719. The switch statement does not cover all values of the enum.

The analyzer has detected a suspicious switch operator. The choice of an option is made through an enum variable, but not all possible cases are covered.

The example:

enum TEnum { A, B, C, D, E, F };
....
TEnum x = foo();
switch (x)
{
  case A: Y(11); break;
  case B: Y(22); break;
  case C: Y(33); break;
  case D: Y(44); break;
  case E: Y(55); break;
}

The TEnum enumeration contains 6 named constants, but the switch statement uses only five of them. It is highly probable that this is an error.

The error often occurs as a result of refactoring, when the F constant is added to TEnum and some of the switch are fixed and some are not. It resulted in the F value being processed incorrectly.

The analyzer warns about the non-used F constant and it allows fixing the error:

switch (x)
{
  case A: Y(11); break;
  case B: Y(22); break;
  case C: Y(33); break;
  case D: Y(44); break;
  case E: Y(55); break;
  case F: Y(66); break;
}

The analyzer does not always generate a warning when some constants of an enum are not used in a switch. Otherwise, there would be too many false positives. There are a number of empirical exceptions to the rule. Here are the basic ones:

• the default branch is used;
• the enum contains only one or two constants;
• more than four constants are not used in switch;
• half or more of the enum elements are not used in the switch;
• the name of the missing constant contains None, Unknown, etc.
• the missing constant is the very last one in the enum and its name contains end, num, count, and the like.

To configure a different behavior, set up a rule based on the following diagnostic rule.

How to additionally configure the diagnostic rule

To change the behavior of the diagnostic rule, add one or more of the following commands to the .pvsconfig file.

Exception: the default branch is used

By default, the analyzer does not issue warnings about unused enum values if the default branch is used, because it can trigger the plethora of potential false positives in cases where the default branch contains an assert or throws an exception.

The example:

enum TEnum { A, B, C, D, E, F };
....
TEnum x = foo();
switch (x)
{
  case A: Y(11); break;
  case B: Y(22); break;
  case C: Y(33); break;
  case D: Y(44); break;
  case E: Y(55); break;
  default:
    throw MyException("Oops! We forgot to handle one of the options!");
}

To find all unused values regardless of whether a default branch is used, configure the following setting:

`//+V719 IGNORE_DEFAULT:ON` (by default)
`//+V719 IGNORE_DEFAULT:OFF`

Exception: enums contains only 1–2 elements

By default, the analyzer does not issue a warning if the unused element belongs to an enum that consists of only one or two elements. To change this behavior, use the following setting:

`//+V719 IGNORE_SMALL_ENUM:ON` (by default)
`//+V719 IGNORE_SMALL_ENUM:OFF`

to define custom names for the last element of the enum

By default, the analyzer does not issue a warning about a missing element if it is the last one in the enum and its name contains a substring such as end, num, count, max, or last.

To define your own list of names, use the following setting:

`//-V719_COUNT_NAME:NAME1, *END,LAST?ELEMENT*`

Notes:

• When this setting is used, the analyzer does not use the default list of names. Only the names specified by the user are used.
• The setting value can be a pattern that uses wildcard characters:
  • * (zero or more of any characters);
  • ? (exactly one of any character).
• Multiple patterns can be listed, separated by commas.
• If the setting value contains no wildcard characters (* or ?), the analyzer searches for a substring.

How to change the threshold of missing constants for issuing warnings

By default, the analyzer stops issuing a warning if more than four constants are missing in a switch statement. To change this behavior, use the following setting:

//+V719 MAX_UNCOVERED_ENUMERATORS: 2

To fully remove this limit, set the value to zero:

//+V719 MAX_UNCOVERED_ENUMERATORS: 0

How to define constant names that do not trigger the diagnostic rule

The setting allows specifying the names of constants whose omission the analyzer does not treat as an error:

//-V719_IGNORE_ENUMERATORS: WithN?, *_DONT_USE, ExactName

Notes:

• The setting value can be a pattern that uses wildcard characters:
  • * (zero or more of any characters);
  • ? (exactly one of any character).
• Multiple patterns can be listed, separated by commas.
• If the pattern contains no wildcard characters, the analyzer searches for an exact match with the name of the enumeration element.

This diagnostic rule is classified as: