std::to_underlying 枚举转换(C++23) ​

什么是 std::to_underlying ​

std::to_underlying 是 C++23 引入的函数模板,定义在 <utility> 头文件中。它将一个枚举值转换为其底层整数类型的值。

在 C++23 之前,要获取枚举的底层值需要使用 static_cast<std::underlying_type_t<E>>(e),写法比较冗长。std::to_underlying 提供了更简洁的写法。

cpp
#include <utility>

enum class Color : int { Red = 1, Green = 2, Blue = 3 };

auto value = std::to_underlying(Color::Red);  // 返回 int 类型的 1

基本示例 ​

cpp
#include <iostream>
#include <utility>
#include <type_traits>
#include <cstdint>
#include <string>
#include <map>

// ============================
// 示例1:基本用法
// ============================

enum class Color : int { Red = 1, Green = 2, Blue = 3 };

void basic_demo() {
    Color c = Color::Green;

    // C++23 方式
    auto value = std::to_underlying(c);
    std::cout << "Color::Green = " << value << std::endl;  // 2

    // C++23 之前的方式(冗长)
    auto old_way = static_cast<std::underlying_type_t<Color>>(c);
    std::cout << "旧方式结果相同: " << old_way << std::endl;  // 2
}

// ============================
// 示例2:不同底层类型
// ============================

enum class SmallEnum : std::uint8_t { A, B, C };
enum class BigEnum : std::int64_t { X = 100000, Y = 200000 };
enum class DefaultEnum { Alpha, Beta, Gamma };  // 默认底层类型是 int

void underlying_types_demo() {
    // to_underlying 返回枚举的实际底层类型
    auto a = std::to_underlying(SmallEnum::C);   // uint8_t 类型
    auto b = std::to_underlying(BigEnum::Y);     // int64_t 类型
    auto c = std::to_underlying(DefaultEnum::Gamma);  // int 类型

    std::cout << "SmallEnum::C = " << (int)a << " (uint8_t)" << std::endl;
    std::cout << "BigEnum::Y = " << b << " (int64_t)" << std::endl;
    std::cout << "DefaultEnum::Gamma = " << c << " (int)" << std::endl;

    // 验证返回类型
    static_assert(std::is_same_v<decltype(a), std::uint8_t>);
    static_assert(std::is_same_v<decltype(b), std::int64_t>);
    static_assert(std::is_same_v<decltype(c), int>);
}

// ============================
// 示例3:constexpr 用法
// ============================

enum class Permission : unsigned {
    Read    = 1,
    Write   = 2,
    Execute = 4
};

void constexpr_demo() {
    // 编译期可用
    constexpr auto read_val = std::to_underlying(Permission::Read);
    constexpr auto write_val = std::to_underlying(Permission::Write);
    constexpr auto exec_val = std::to_underlying(Permission::Execute);

    static_assert(read_val == 1);
    static_assert(write_val == 2);
    static_assert(exec_val == 4);

    std::cout << "Read=" << read_val
              << " Write=" << write_val
              << " Execute=" << exec_val << std::endl;
}

// ============================
// 示例4:用于位运算
// ============================

enum class Flags : unsigned {
    None    = 0,
    Bold    = 1 << 0,
    Italic  = 1 << 1,
    Under   = 1 << 2,
    Strike  = 1 << 3
};

// 位运算辅助函数
constexpr Flags operator|(Flags a, Flags b) {
    return static_cast<Flags>(
        std::to_underlying(a) | std::to_underlying(b));
}

constexpr bool has_flag(Flags set, Flags flag) {
    return (std::to_underlying(set) & std::to_underlying(flag)) != 0;
}

void flags_demo() {
    Flags style = Flags::Bold | Flags::Under;

    std::cout << std::boolalpha;
    std::cout << "Bold: " << has_flag(style, Flags::Bold) << std::endl;     // true
    std::cout << "Italic: " << has_flag(style, Flags::Italic) << std::endl; // false
    std::cout << "Under: " << has_flag(style, Flags::Under) << std::endl;   // true

    std::cout << "style 值: " << std::to_underlying(style) << std::endl;    // 5
}

// ============================
// 示例5:序列化/日志输出
// ============================

enum class HttpStatus : int {
    OK = 200,
    NotFound = 404,
    InternalError = 500
};

std::string status_to_string(HttpStatus s) {
    return "HTTP " + std::to_string(std::to_underlying(s));
}

void serialization_demo() {
    std::cout << status_to_string(HttpStatus::OK) << std::endl;
    std::cout << status_to_string(HttpStatus::NotFound) << std::endl;
    std::cout << status_to_string(HttpStatus::InternalError) << std::endl;
}

// ============================
// 示例6:用作容器的键
// ============================

enum class ErrorCode : int {
    Success = 0,
    FileNotFound = 1,
    PermissionDenied = 2,
    Timeout = 3
};

void map_key_demo() {
    // 用底层值作为 map 的键
    std::map<int, std::string> error_messages;
    error_messages[std::to_underlying(ErrorCode::FileNotFound)] = "文件未找到";
    error_messages[std::to_underlying(ErrorCode::PermissionDenied)] = "权限不足";
    error_messages[std::to_underlying(ErrorCode::Timeout)] = "超时";

    ErrorCode err = ErrorCode::Timeout;
    auto it = error_messages.find(std::to_underlying(err));
    if (it != error_messages.end()) {
        std::cout << "错误 " << std::to_underlying(err)
                  << ": " << it->second << std::endl;
    }
}

// ============================
// 示例7:传统无作用域枚举
// ============================

enum OldColor { RED = 10, GREEN = 20, BLUE = 30 };

void unscoped_enum_demo() {
    // to_underlying 也可以用于无作用域枚举
    auto val = std::to_underlying(GREEN);
    std::cout << "GREEN = " << val << std::endl;  // 20
}

int main() {
    std::cout << "=== 基本用法 ===" << std::endl;
    basic_demo();

    std::cout << "\n=== 不同底层类型 ===" << std::endl;
    underlying_types_demo();

    std::cout << "\n=== constexpr ===" << std::endl;
    constexpr_demo();

    std::cout << "\n=== 位运算 ===" << std::endl;
    flags_demo();

    std::cout << "\n=== 序列化 ===" << std::endl;
    serialization_demo();

    std::cout << "\n=== 容器键 ===" << std::endl;
    map_key_demo();

    std::cout << "\n=== 无作用域枚举 ===" << std::endl;
    unscoped_enum_demo();

    return 0;
}

to_underlying vs static_cast ​

方式写法类型安全可读性
std::to_underlying(e)简洁只接受枚举好
static_cast<underlying_type_t<E>>(e)冗长手动指定类型差
(int)e(C 风格转换)短不安全差

适用场景 ​

  • 枚举值的序列化和日志输出
  • 枚举位标志的位运算
  • 将枚举值传递给需要整数的 API
  • 用枚举值作为容器索引或键
  • 替代冗长的 static_cast + underlying_type_t 组合

常见问题 ​

to_underlying 可以用于无作用域枚举吗?

可以。它同时支持 enum class 和传统的 enum。

返回类型是什么?

返回枚举的底层类型(underlying type)。对于 enum class Color : uint8_t,返回 uint8_t。

可以反向从整数转回枚举吗?

to_underlying 只做枚举到整数的转换。反向转换需要 static_cast<EnumType>(value)。

注意事项 ​

  • 只接受枚举类型,传入非枚举类型会编译错误
  • 返回类型是枚举声明时指定的底层类型
  • 如果枚举没有显式指定底层类型,默认是 int
  • 是 constexpr 和 noexcept 的
  • 需要 <utility> 头文件

总结 ​

std::to_underlying 是 C++23 提供的便捷函数,将枚举值转换为其底层整数类型。它替代了以前冗长的 static_cast<std::underlying_type_t<E>>(e) 写法,代码更简洁、可读性更好。它支持有作用域和无作用域枚举,是 constexpr 的,在位运算、序列化、日志输出等需要枚举底层值的场景中特别有用。