error.h

Go to the documentation of this file.

/*
 * Copyright (c) 2012-2026, QORE Lab, Imperial College London
 * All rights reserved.
 */
#ifndef LINE_UTIL_ERROR_H
#define LINE_UTIL_ERROR_H
 
/**
 * @file
 * @ingroup line_util
 * The exception types the port throws.
 *
 * `Error` and its five refinements, one per category of the cross-codebase
 * error vocabulary (`_kb/17-error-vocabulary.md`): `InputError` for a malformed
 * model or argument, `NumericError` for a computation that cannot produce an
 * answer, `UnsupportedError` for a feature the chosen algorithm does not cover,
 * `ExternalError` for a missing or failed tool, and `InternalError` for a bug. Nothing
 * in the library calls `exit()` or writes to stderr on failure: the CLI catches
 * these at `main` and the bindings map them to exceptions, so the same code path
 * serves both.
 */
 
#include <cstddef>
#include <stdexcept>
#include <string>
#include <utility>
 
namespace line {
 
/**
 * The `<kind>` part of a `LINE:<category>:<kind>` identifier (see
 * `_kb/17-error-vocabulary.md`): an identifier such as `Cache`,
 * `SchedStrategy_PS`, `NonConvergence` or `Method`. A typed wrapper rather than a
 * bare string so that `UnsupportedError(kind, what)` cannot be confused with the
 * one-string constructor.
 */
struct ErrorKind {
    std::string name;
    explicit ErrorKind(std::string n) : name(std::move(n)) {}
};
 
namespace error_detail {
 
/** True when `s` matches `[A-Za-z][A-Za-z0-9_]*`, the grammar of a kind. */
inline bool valid_kind(const std::string& s) {
    if (s.empty()) return false;
    auto alpha = [](char c) { return (c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z'); };
    auto digit = [](char c) { return c >= '0' && c <= '9'; };
    if (!alpha(s[0])) return false;
    for (char c : s)
        if (!alpha(c) && !digit(c) && c != '_') return false;
    return true;
}
 
/** `LINE:<category>:<kind>`, or `LINE:internal:BadErrorId` for a malformed kind. */
inline std::string make_id(const char* category, const std::string& kind) {
    if (!valid_kind(kind)) return "LINE:internal:BadErrorId";
    return std::string("LINE:") + category + ":" + kind;
}
 
}  // namespace error_detail
 
/**
 * Base error for the multiprecision C++ port. Nothing in the library calls
 * exit() or prints to stderr on failure: the CLI catches these at main and the
 * Python binding maps them to exceptions, so the same code path serves both.
 *
 * Every error carries an identifier from the cross-codebase vocabulary,
 * `LINE:<category>:<kind>`, shared with MATLAB error ids, Java `LineException`
 * and Python `LineError`. A bare `Error` is `LINE:Error`, the legacy
 * unclassified id; the refinements below fix the category.
 */
class Error : public std::runtime_error {
public:
    explicit Error(const std::string& what) : std::runtime_error(what), id_("LINE:Error") {}
 
    /** The full identifier, e.g. `LINE:unsupported:Cache`. */
    const std::string& id() const noexcept { return id_; }
 
    /** `unsupported`, `numerical`, `input`, `external`, `internal`, or empty for `LINE:Error`. */
    std::string category() const {
        const std::size_t a = id_.find(':');
        const std::size_t b = id_.find(':', a + 1);
        return b == std::string::npos ? std::string() : id_.substr(a + 1, b - a - 1);
    }
 
    /** The `<kind>` part, or empty for `LINE:Error`. */
    std::string kind() const {
        const std::size_t a = id_.find(':');
        const std::size_t b = id_.find(':', a + 1);
        return b == std::string::npos ? std::string() : id_.substr(b + 1);
    }
 
protected:
    Error(const char* category, const std::string& kind, const std::string& what)
        : std::runtime_error(what), id_(error_detail::make_id(category, kind)) {}
 
private:
    std::string id_;
};
 
/** Malformed or inconsistent input (dimensions, negative populations, ...): `LINE:input:<kind>`. */
class InputError : public Error {
public:
    explicit InputError(const std::string& what) : Error("input", "Unspecified", what) {}
    InputError(const ErrorKind& kind, const std::string& what) : Error("input", kind.name, what) {}
};
 
/** The algorithm cannot produce a trustworthy answer on this instance: `LINE:numerical:<kind>`. */
class NumericError : public Error {
public:
    explicit NumericError(const std::string& what) : Error("numerical", "Unspecified", what) {}
    NumericError(const ErrorKind& kind, const std::string& what) : Error("numerical", kind.name, what) {}
};
 
/** A refusal: the feature, method or analysis is not covered: `LINE:unsupported:<kind>`. */
class UnsupportedError : public Error {
public:
    explicit UnsupportedError(const std::string& what) : Error("unsupported", "Unspecified", what) {}
    UnsupportedError(const ErrorKind& kind, const std::string& what) : Error("unsupported", kind.name, what) {}
};
 
/** A tool, binary, service or bridge LINE depends on is missing or failed: `LINE:external:<kind>`. */
class ExternalError : public Error {
public:
    explicit ExternalError(const std::string& what) : Error("external", "Unspecified", what) {}
    ExternalError(const ErrorKind& kind, const std::string& what) : Error("external", kind.name, what) {}
};
 
/** An invariant LINE should guarantee was violated, i.e. a bug: `LINE:internal:<kind>`. */
class InternalError : public Error {
public:
    explicit InternalError(const std::string& what) : Error("internal", "Unspecified", what) {}
    InternalError(const ErrorKind& kind, const std::string& what) : Error("internal", kind.name, what) {}
};
 
}  // namespace line
 
#endif  // LINE_UTIL_ERROR_H