std::expected ​

什么是 std::expected ​

std::expected<T, E> 是 C++23 引入的错误处理类型,定义在 <expected> 头文件中。它表示一个操作的结果:要么包含期望的成功值(类型 T),要么包含错误值(类型 E)。类似于 Rust 的 Result<T, E>。

与异常不同,std::expected 强制调用者显式处理错误,不会跳过调用栈;与错误码不同,它将成功值和错误值封装在同一个类型中,不需要额外的输出参数。

cpp
#include <expected>

std::expected<int, std::string> divide(int a, int b) {
    if (b == 0) return std::unexpected("除数不能为零");
    return a / b;
}

基本示例 ​

cpp
#include <iostream>
#include <expected>
#include <string>
#include <vector>
#include <fstream>
#include <charconv>

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

std::expected<int, std::string> parse_int(const std::string& s) {
    int result = 0;
    auto [ptr, ec] = std::from_chars(s.data(), s.data() + s.size(), result);

    if (ec == std::errc::invalid_argument) {
        return std::unexpected("无效的数字格式: " + s);
    }
    if (ec == std::errc::result_out_of_range) {
        return std::unexpected("数字超出范围: " + s);
    }
    if (ptr != s.data() + s.size()) {
        return std::unexpected("包含非数字字符: " + s);
    }
    return result;
}

void basic_demo() {
    // 成功的情况
    auto r1 = parse_int("42");
    if (r1.has_value()) {
        std::cout << "解析成功: " << r1.value() << std::endl;
    }

    // 也可以用 bool 转换
    if (r1) {
        std::cout << "值: " << *r1 << std::endl;  // 用 * 解引用
    }

    // 失败的情况
    auto r2 = parse_int("abc");
    if (!r2) {
        std::cout << "解析失败: " << r2.error() << std::endl;
    }
}

// ============================
// 示例2:value_or 提供默认值
// ============================

void value_or_demo() {
    auto r1 = parse_int("100");
    auto r2 = parse_int("xyz");

    // value_or 在成功时返回值,失败时返回默认值
    int v1 = r1.value_or(0);
    int v2 = r2.value_or(-1);

    std::cout << "v1 = " << v1 << std::endl;  // 100
    std::cout << "v2 = " << v2 << std::endl;  // -1
}

// ============================
// 示例3:用枚举作为错误类型
// ============================

enum class FileError {
    NotFound,
    PermissionDenied,
    TooLarge,
    Unknown
};

std::expected<std::string, FileError> read_file(const std::string& path) {
    std::ifstream file(path);
    if (!file.is_open()) {
        return std::unexpected(FileError::NotFound);
    }

    std::string content((std::istreambuf_iterator<char>(file)),
                         std::istreambuf_iterator<char>());

    if (content.size() > 1024 * 1024) {
        return std::unexpected(FileError::TooLarge);
    }

    return content;
}

void enum_error_demo() {
    auto result = read_file("不存在的文件.txt");

    if (!result) {
        switch (result.error()) {
            case FileError::NotFound:
                std::cout << "文件未找到" << std::endl;
                break;
            case FileError::PermissionDenied:
                std::cout << "权限不足" << std::endl;
                break;
            case FileError::TooLarge:
                std::cout << "文件过大" << std::endl;
                break;
            default:
                std::cout << "未知错误" << std::endl;
        }
    }
}

// ============================
// 示例4:expected<void, E>
// ============================

enum class ValidationError {
    Empty,
    TooShort,
    TooLong,
    InvalidChar
};

std::expected<void, ValidationError> validate_username(const std::string& name) {
    if (name.empty()) return std::unexpected(ValidationError::Empty);
    if (name.size() < 3) return std::unexpected(ValidationError::TooShort);
    if (name.size() > 20) return std::unexpected(ValidationError::TooLong);

    for (char c : name) {
        if (!std::isalnum(c) && c != '_') {
            return std::unexpected(ValidationError::InvalidChar);
        }
    }

    return {};  // 成功(void 值)
}

void void_demo() {
    auto r1 = validate_username("alice_123");
    if (r1) {
        std::cout << "用户名有效" << std::endl;
    }

    auto r2 = validate_username("ab");
    if (!r2) {
        std::cout << "用户名无效: ";
        switch (r2.error()) {
            case ValidationError::TooShort: std::cout << "太短"; break;
            case ValidationError::TooLong: std::cout << "太长"; break;
            case ValidationError::Empty: std::cout << "为空"; break;
            case ValidationError::InvalidChar: std::cout << "包含非法字符"; break;
        }
        std::cout << std::endl;
    }
}

// ============================
// 示例5:error_or 提供默认错误值
// ============================

void error_or_demo() {
    auto success = parse_int("42");
    auto failure = parse_int("abc");

    // error_or 在失败时返回错误,成功时返回默认错误值
    std::string err1 = success.error_or("没有错误");
    std::string err2 = failure.error_or("没有错误");

    std::cout << "err1: " << err1 << std::endl;  // 没有错误
    std::cout << "err2: " << err2 << std::endl;  // 无效的数字格式: abc
}

// ============================
// 示例6:链式调用(手动方式)
// ============================

std::expected<int, std::string> get_config_value(const std::string& key) {
    if (key == "port") return 8080;
    if (key == "timeout") return 30;
    return std::unexpected("配置项不存在: " + key);
}

std::expected<int, std::string> validate_port(int port) {
    if (port < 1 || port > 65535) {
        return std::unexpected("端口超出范围: " + std::to_string(port));
    }
    return port;
}

void chain_demo() {
    // 手动链式调用
    auto port = get_config_value("port");
    if (port) {
        auto validated = validate_port(*port);
        if (validated) {
            std::cout << "有效端口: " << *validated << std::endl;
        } else {
            std::cout << "验证失败: " << validated.error() << std::endl;
        }
    } else {
        std::cout << "获取失败: " << port.error() << std::endl;
    }
}

// ============================
// 示例7:emplace 就地构造
// ============================

void emplace_demo() {
    std::expected<std::vector<int>, std::string> result;

    // 就地构造成功值
    result.emplace({1, 2, 3, 4, 5});

    if (result) {
        std::cout << "vector 大小: " << result->size() << std::endl;  // 5
        std::cout << "第一个元素: " << result->front() << std::endl;  // 1
    }
}

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

    std::cout << "\n=== value_or ===" << std::endl;
    value_or_demo();

    std::cout << "\n=== 枚举错误 ===" << std::endl;
    enum_error_demo();

    std::cout << "\n=== void 特化 ===" << std::endl;
    void_demo();

    std::cout << "\n=== error_or ===" << std::endl;
    error_or_demo();

    std::cout << "\n=== 链式调用 ===" << std::endl;
    chain_demo();

    std::cout << "\n=== emplace ===" << std::endl;
    emplace_demo();

    return 0;
}

expected 的成员函数一览 ​

函数说明
has_value()是否包含成功值
operator bool同 has_value()
value()获取成功值(失败时抛异常)
error()获取错误值(成功时未定义行为)
operator* / operator->访问成功值(不检查)
value_or(default)成功返回值,失败返回默认值
error_or(default)失败返回错误,成功返回默认错误
emplace(args...)就地构造成功值
and_then(f)Monadic:成功时链式调用 f
transform(f)Monadic:成功时变换值
or_else(f)Monadic:失败时调用 f
transform_error(f)Monadic:失败时变换错误

expected vs optional vs 异常 vs 错误码 ​

特性std::expectedstd::optional异常错误码
错误信息携带详细错误只有"无值"异常对象整数
强制处理类型系统强制需要检查不强制不强制
性能开销零运行时开销零开销抛出时很大零开销
栈展开不展开不展开展开不展开
函数签名明确表达不够明确不在签名中需要额外参数
链式操作支持(monadic)支持(monadic)不支持不支持

适用场景 ​

  • 函数可能失败且需要返回错误详情
  • 替代异常的高性能错误处理
  • 替代错误码+输出参数的传统模式
  • 解析和验证操作
  • 文件/网络 I/O 操作
  • 需要链式错误处理的场景

常见问题 ​

value() 在失败时会怎样?

如果 expected 包含错误值,调用 value() 会抛出 std::bad_expected_access<E> 异常。建议先用 has_value() 检查,或者使用 value_or() 提供默认值。

expected 可以同时没有值和没有错误吗?

不可以。expected 总是处于两种状态之一:包含成功值或包含错误值,不会为空。

T 和 E 有什么限制?

T 可以是 void(表示只关心成功/失败),但 E 不能是 void。T 和 E 都不能是引用类型、数组类型或函数类型。

expected 的内存开销是多少?

expected 内部是一个 union,大小大约是 max(sizeof(T), sizeof(E)) 加一个 bool 标志。没有堆分配。

注意事项 ​

  • expected 永远不会为空——总是有值或有错误
  • 使用 * 或 -> 访问值前确保 has_value()
  • E 不能是 void
  • 使用 std::unexpected 构造错误值
  • value() 在失败时抛异常,性能敏感场景用 * 或 value_or
  • expected<void, E> 用于只关心成功/失败的场景

编译器支持情况 ​

编译器std::expected最低版本
GCC支持12.0
Clang支持16.0
MSVC支持19.33 (VS 2022 17.3)

总结 ​

std::expected<T, E> 是 C++23 引入的类型安全错误处理方案,表示一个操作要么成功返回 T 类型的值,要么失败返回 E 类型的错误。它结合了异常的表达力(可以携带详细错误信息)和错误码的确定性(不做栈展开,零运行时开销)。函数签名明确表达了可能的失败,类型系统强制调用者处理错误。配合 C++23 的 monadic 操作(and_then、transform、or_else、transform_error),expected 支持函数式风格的链式错误处理管道。