modernize-use-to-underlying

Finds casts from a scoped enumeration (enum class) to an integer type and replaces them with a call to std::to_underlying (introduced in C++23).

Converting a scoped enumeration to a hard-coded integer type is error-prone: if the enumeration’s underlying type is later changed, every such cast silently becomes a narrowing, widening or sign-changing conversion. std::to_underlying always yields exactly the underlying type and keeps the code correct.

Example:

enum class Color : unsigned char { Red, Green, Blue };

void f(Color c) {
  // Before:
  auto value = static_cast<unsigned char>(c);
  // After:
  auto value = std::to_underlying(c);
}

The check matches static_cast, C-style casts and functional-style casts.

Precise and imprecise casts

A cast is precise when its destination type is exactly the underlying type of the enumeration. A cast is imprecise when the destination type is an integer type other than the underlying type (a different width or signedness).

enum class E : int {};

// precise cast
int i = static_cast<int>(E{});
// imprecise cast
unsigned j = static_cast<unsigned>(E{});

Precise casts are always rewritten.

Imprecise casts perform an additional integer conversion, so there is no single correct rewrite. Rewrites of imprecise casts are controlled by the ImpreciseCasts option.

A cast to a non-integer type (floating point, pointer, another enumeration) is never flagged. A cast to bool is only flagged when bool is the exact underlying type of the enumeration; otherwise it is treated as a truthiness test and left untouched.

Options

ImpreciseCasts

Controls how imprecise casts (whose destination type differs from the underlying type) are handled. Precise casts are always diagnosed and fixed regardless of this option. Possible values:

• Ignore: Do not diagnose imprecise casts.

• Warn: Diagnose imprecise casts but do not offer a fix-it. Neither automatic rewrite is applied because both change the meaning of the code in ways that may not be intended.

• PreserveType: Wrap the operand in a call to the replacement function, keeping the original destination type:

  long l = static_cast<long>(E{});
  // becomes:
  long l = static_cast<long>(std::to_underlying(E{}));
  

• UseUnderlyingType: Replace the whole cast with a call to the replacement function. This changes the type of the expression from the destination type to the underlying type, so use it only when the wider or differently-signed destination type was itself unintended:

  long l = static_cast<long>(E{});
  // becomes:
  long l = std::to_underlying(E{});
  

Default is Warn.

ReplacementFunction

The fully qualified name of the function used in the replacement. Set this to use a hand-rolled equivalent (for example llvm::to_underlying) when targeting a language standard before C++23. When the value is std::to_underlying, the check only runs in C++23 or later; with any other value it runs from C++11 onwards. Default is std::to_underlying.

ReplacementFunctionHeader

The header to include when the replacement function is used. When the value is enclosed in angle brackets the include directive uses angle brackets, otherwise it uses quotes. Default is <utility> when ReplacementFunction is set to std::to_underlying, and otherwise empty (no include is added).

IncludeStyle

A string specifying which include-style is used, llvm or google. Default is llvm.