status

中文版

Lightweight C++17 library for structured errors: kumo::Status and kumo::Result<T> (StatusOr-style), plus early-return macros.

Inspired by Abseil/turbo Status, trimmed for embedding:

• sizeof(Status) == sizeof(uintptr_t) — inline OK / code+SubError+Dap
• Heap only when there is a message, payload, or stack
• First-class SubError (user / errno / errc) and Dap (short duration)
• String payloads and call-site stacks — no Cord, no fmt dependency

Also includes status/expected.h (tl::expected-style expected<T,E>) as a separate header-only target. Prefer Status / Result for this library’s own error model; use expected only when you explicitly want generic T|E.

Quick start

#include <status/status.h>

kumo::Status Open(std::string_view path) {
    if (path.empty()) {
        return kumo::make_invalid_argument("empty path")
                .with_payload("field", "path")
                .with_stack(KUMO_STATUS_TRACE_PARAM);
    }
    return kumo::OkStatus();
}

kumo::Result<int> Parse(std::string_view s) {
    KUMO_RETURN_NOT_OK(Open(s));
    if (s == "bad") {
        return kumo::make_not_found("missing");
    }
    return 42;  // success: return the value
}

kumo::Status Use() {
    int n = 0;
    KUMO_MOVE_OR_RAISE(n, Parse("ok"));
    (void)n;
    return kumo::OkStatus();
}

Include map

Header	Contents
<status/status.h>	Umbrella: Status + Result + macros
<status/detail/status.h>	Status, factories, is_*, SubError, Dap
<status/detail/result.h>	Result<T>, BadResultAccess, to_result
<status/detail/status_macros.h>	KUMO_RETURN_*, MOVE/COPY_OR_RAISE
<status/detail/inline_status.h>	InlineStatus encoding (8-byte word)
<status/expected.h>	Generic expected<T,E> (separate from Status)

See status/skills.h, AGENTS.md, and docs/AI.md for AI/human API notes (exclusive SubError/Dap masks, no legacy internal/ tree).

Design notes

• with_*: mutate in place, return Status&. No-op on OK for message / payload / stack.
• Formatting: pass one preformatted string / string_view. Default to_string() is brief (OK or CODE / CODE: message). Custom: to_string<MyFormat>().
• Result: success = return value;; errors = build a Status then return it as Result<T>. Do not use OkStatus() as a Result error (Debug asserts; Release → internal_error).
• Exclusive tags: switching SubError kind or Dap unit clears sibling bits via kSubErrorExclusiveMask / kDapExclusiveMask.
• Macros: optional stack frames when KUMO_EXTRA_ERROR_CONTEXT is 1 (default). Set to 0 before including macros to disable.

Build

CI mirrors xhash: reusable workflows from kumose/x-ci (Ubuntu / Alpine / CentOS / macOS / Windows) on master pushes and PRs — see .github/workflows/ci.yml.

Built with kmcmake. kmpkg is optional. There is no required kmpkg.json (zero third-party package deps). If a build directory was previously configured with manifest mode, delete it and reconfigure after removing a manifest.

Requirements

• Linux / macOS / Windows (MSVC + Ninja recommended)
• CMake ≥ 3.20
• GCC ≥ 9.4 / Clang ≥ 12 / MSVC (VS 2022+)
• Optional: kmpkg toolchain via KMPKG_CMAKE
• Optional: ninja for --preset=ninja

Configure and build

# Unix Makefiles → build/
cmake --preset=default
cmake --build build -j$(nproc)

# Ninja → build-ninja/
cmake --preset=ninja
cmake --build build-ninja -j$(nproc)

Without presets:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)

Tests

ctest --test-dir build
# or
ctest --test-dir build-ninja

Main targets: status_status_basic_test, status_result_test, status_macros_no_context_test.

CMake consumers

find_package(status REQUIRED)
target_link_libraries(myapp PRIVATE status::status_static)

Header-only expected:

target_link_libraries(myapp PRIVATE status::api)  # expected.h

License

Apache License 2.0 — see LICENSE.