Math Engine Reference: Quantity

typedef enum math_engine_quantity_numeric_kind {
    MATH_ENGINE_QUANTITY_NUMERIC_INVALID = 0, /**< 활성 numeric storage가 없는 zero/sentinel kind다. */
    MATH_ENGINE_QUANTITY_NUMERIC_BINARY32 = 1, /**< 유한 IEEE-754 binary32 값을 =numeric.binary32=에 저장한다. */
    MATH_ENGINE_QUANTITY_NUMERIC_BINARY64 = 2, /**< 유한 IEEE-754 binary64 값을 =numeric.binary64=에 저장한다. */
    MATH_ENGINE_QUANTITY_NUMERIC_FIXED_DECIMAL = 3, /**< =coefficient*10^-scale= exact decimal을 저장한다. */
    MATH_ENGINE_QUANTITY_NUMERIC_PRECISION_DECIMAL = 4 /**< Caller precision context의 live slot을 pointer-free 참조한다. */
} math_engine_quantity_numeric_kind_t;

typedef enum math_engine_quantity_operation {
    MATH_ENGINE_QUANTITY_OPERATION_INVALID = 0, /**< 완료된 quantity operation이 없는 zero/sentinel 값이다. */
    MATH_ENGINE_QUANTITY_OPERATION_CONVERT_UNIT = 1, /**< 차원을 유지하며 호환 target unit으로 값을 변환했다. */
    MATH_ENGINE_QUANTITY_OPERATION_CONVERT_NUMERIC = 2, /**< Unit을 유지하며 numeric backend를 변환했다. */
    MATH_ENGINE_QUANTITY_OPERATION_ADD = 3, /**< 호환 차원의 =lhs+rhs=를 계산했다. */
    MATH_ENGINE_QUANTITY_OPERATION_SUBTRACT = 4, /**< 호환 차원의 =lhs-rhs=를 계산했다. */
    MATH_ENGINE_QUANTITY_OPERATION_MULTIPLY = 5, /**< 값과 unit dimension을 곱했다. */
    MATH_ENGINE_QUANTITY_OPERATION_DIVIDE = 6, /**< 값과 unit dimension을 =lhs/rhs=로 나눴다. */
    MATH_ENGINE_QUANTITY_OPERATION_POWER = 7, /**< =lhs^request.power= 정수 거듭제곱을 계산했다. */
    MATH_ENGINE_QUANTITY_OPERATION_PARSE = 8 /**< ASCII number와 unit expression을 quantity로 해석했다. */
} math_engine_quantity_operation_t;

typedef struct math_engine_quantity_fixed_value {
    int64_t coefficient; /**< Signed exact integer 계수이며 저장값은 =coefficient*10^-scale=이다. */
    int32_t scale; /**< Decimal 소수 자릿수인 포함 범위 0..18이다. */
    uint32_t reserved; /**< Producer는 0으로 두며 quantity validator가 nonzero를 거부하는 ABI slot이다. */
} math_engine_quantity_fixed_value_t;

typedef struct math_engine_quantity_precision_ref {
    uint64_t context_id; /**< Slot을 소유한 precision context의 nonzero stable runtime ID다. */
    uint32_t slot; /**< Context slot 배열의 zero-based index이며 실제 범위는 context가 검증한다. */
    uint32_t generation; /**< 해제·재획득된 stale slot을 구분하는 nonzero generation token이다. */
} math_engine_quantity_precision_ref_t;

typedef union math_engine_quantity_numeric_storage {
    float binary32; /**< Numeric kind BINARY32에서만 의미 있는 finite 값이다. */
    double binary64; /**< Numeric kind BINARY64에서만 의미 있는 finite 값이다. */
    math_engine_quantity_fixed_value_t fixed_decimal; /**< FIXED_DECIMAL kind의 coefficient/scale 저장 member다. */
    math_engine_quantity_precision_ref_t precision_decimal; /**< PRECISION_DECIMAL kind의 caller-context slot 참조다. */
    uint64_t reserved[2]; /**< Union을 16 byte로 고정하는 ABI view이며 producer는 활성 member 기록 전 전체를 0으로 초기화한다. */
#ifdef __cplusplus
    constexpr math_engine_quantity_numeric_storage() : reserved{0u, 0u} {}
    constexpr explicit math_engine_quantity_numeric_storage(double value)
        : binary64(value) {}
#endif
} math_engine_quantity_numeric_storage_t;

typedef struct math_engine_quantity {
    uint32_t struct_size; /**< Exact ABI byte 크기 =sizeof(math_engine_quantity_t)=다. */
    uint32_t struct_version; /**< =MATH_ENGINE_QUANTITY_VERSION_1=이어야 한다. */
    uint32_t numeric_kind; /**< =numeric=에서 활성인 =math_engine_quantity_numeric_kind_t= 값이다. */
    uint32_t flags; /**< V1 quantity에는 정의된 bit가 없어 반드시 0이다. */
    math_engine_quantity_numeric_storage_t numeric; /**< =numeric_kind=가 선택한 pointer-free 값 storage다. */
    math_engine_unit_t unit; /**< Numeric 값이 표현된 차원·scale·offset의 값 소유 unit descriptor다. */
} math_engine_quantity_t;

typedef struct math_engine_quantity_request {
    uint32_t struct_size; /**< Caller가 exact request byte 크기로 설정한다. */
    uint32_t struct_version; /**< =MATH_ENGINE_QUANTITY_REQUEST_VERSION_1=이어야 한다. */
    uint32_t result_numeric_kind; /**< 결과에 요구하는 유효 non-INVALID numeric kind다. */
    int32_t fixed_scale; /**< FIXED_DECIMAL 결과에서 사용할 포함 범위 0..18; 다른 kind에서는 무시된다. */
    uint32_t rounding; /**< Fixed 결과의 =math_engine_decimal_rounding_t= 값이며 다른 kind에서는 무시된다. */
    int32_t power; /**< POWER operation의 signed integer exponent이며 다른 operation에서는 무시된다. */
    uint32_t flags; /**< V1 request에는 정의된 bit가 없어 반드시 0이다. */
    uint32_t reserved32; /**< Caller는 0으로 두며 V1 validator가 nonzero를 거부한다. */
    void* precision_context; /**< Precision source/result에서 필수인 borrowed caller-owned context; nullable otherwise, 호출 동안 유효하고 보관되지 않으며 caller가 직렬화한다. */
    math_engine_quantity_precision_ref_t precision_output; /**< Precision 결과를 commit할 이미 획득한 writable slot; 다른 result kind에서는 무시된다. */
    uint64_t reserved[2]; /**< Caller가 0으로 두어야 하고 V1 validator가 검사하는 ABI 확장 word다. */
} math_engine_quantity_request_t;

typedef struct math_engine_quantity_result {
    uint32_t struct_size; /**< Caller가 exact result byte 크기로 미리 설정한다. */
    uint32_t struct_version; /**< =MATH_ENGINE_QUANTITY_RESULT_VERSION_1=이어야 한다. */
    uint32_t operation; /**< 성공한 =math_engine_quantity_operation_t= provenance 값이다. */
    uint32_t flags; /**< EXACT/INEXACT와 선택적 rounding/unit/backend provenance bit의 OR다. */
    uint32_t source_numeric_kind; /**< Parse에서는 requested kind, 그 밖에는 첫 source quantity의 numeric kind다. */
    uint32_t result_numeric_kind; /**< =quantity.numeric_kind=와 같은 실제 결과 backend kind다. */
    uint64_t operation_fingerprint; /**< Operation, source/result kind, flags와 결과 payload의 결정적 64-bit hash다. */
    math_engine_quantity_t quantity; /**< 성공한 값과 명시적 결과 unit을 소유하는 versioned quantity다. */
    uint64_t reserved[2]; /**< Library가 0으로 기록하고 caller가 무시하는 ABI 확장 word다. */
} math_engine_quantity_result_t;

typedef struct math_engine_constant_record {
    uint32_t struct_size; /**< Engine record의 exact byte 크기 =sizeof(math_engine_constant_record_t)=다. */
    uint32_t struct_version; /**< =MATH_ENGINE_CONSTANT_RECORD_VERSION_1=이다. */
    uint64_t stable_id; /**< Name-domain에서 결정적으로 생성한 process/version 간 nonzero catalog ID다. */
    uint32_t flags; /**< =MATH_ENGINE_CONSTANT_FLAG_*= 중 알려진 provenance/lifecycle bit의 OR다. */
    uint32_t reserved32; /**< Engine이 0으로 제공하고 consumer가 무시하는 ABI 확장 slot이다. */
    const char* canonical_name; /**< Non-NULL engine-owned NUL-terminated canonical UTF-8/ASCII 이름; process lifetime 동안 유효하다. */
    const char* symbol; /**< Non-NULL engine-owned NUL-terminated 표준 symbol; process lifetime 동안 유효하다. */
    const char* ascii_alias; /**< Non-NULL engine-owned NUL-terminated ASCII 검색 alias; process lifetime 동안 유효하다. */
    const char* value_decimal; /**< Non-NULL engine-owned canonical decimal 값 text; process lifetime 동안 유효하다. */
    const char* standard_uncertainty_decimal; /**< Non-NULL engine-owned standard-uncertainty decimal text; exact record는 ="0"=이다. */
    const char* unit_expression; /**< Non-NULL engine-owned parseable canonical unit expression; process lifetime 동안 유효하다. */
    const char* edition; /**< Non-NULL engine-owned source edition/revision text; process lifetime 동안 유효하다. */
    const char* provenance; /**< Non-NULL engine-owned provenance/authority text; process lifetime 동안 유효하다. */
    const char* legacy_disposition; /**< Non-NULL engine-owned migration/disposition text이며 없으면 빈 문자열이다. */
    uint64_t replacement_stable_id; /**< DEPRECATED record의 대체 catalog ID이며 대체가 없으면 0이다. */
    math_engine_quantity_t value; /**< =value_decimal=을 binary64로 materialize한 값과 명시적 unit이다. */
    double standard_uncertainty; /**< =value=와 같은 unit의 finite nonnegative 1-sigma uncertainty; exact이면 0이다. */
} math_engine_constant_record_t;

#define MATH_ENGINE_CONSTANT_FLAG_CONVENTIONAL (UINT32_C(1) << 3u)

#define MATH_ENGINE_CONSTANT_FLAG_DEPRECATED (UINT32_C(1) << 5u)

#define MATH_ENGINE_CONSTANT_FLAG_DERIVED (UINT32_C(1) << 2u)

#define MATH_ENGINE_CONSTANT_FLAG_EXACT (UINT32_C(1) << 0u)

#define MATH_ENGINE_CONSTANT_FLAG_KNOWN_MASK UINT32_C(0x0000003f)

#define MATH_ENGINE_CONSTANT_FLAG_MEASURED (UINT32_C(1) << 1u)

#define MATH_ENGINE_CONSTANT_FLAG_SI_DEFINING (UINT32_C(1) << 4u)

#define MATH_ENGINE_CONSTANT_RECORD_VERSION_1 UINT32_C(1)

#define MATH_ENGINE_QUANTITY_REQUEST_VERSION_1 UINT32_C(1)

#define MATH_ENGINE_QUANTITY_RESULT_FLAG_BACKEND_CONVERTED (UINT32_C(1) << 4u)

#define MATH_ENGINE_QUANTITY_RESULT_FLAG_EXACT (UINT32_C(1) << 0u)

#define MATH_ENGINE_QUANTITY_RESULT_FLAG_INEXACT (UINT32_C(1) << 1u)

#define MATH_ENGINE_QUANTITY_RESULT_FLAG_ROUNDED (UINT32_C(1) << 2u)

#define MATH_ENGINE_QUANTITY_RESULT_FLAG_UNIT_CONVERTED (UINT32_C(1) << 3u)

#define MATH_ENGINE_QUANTITY_RESULT_VERSION_1 UINT32_C(1)

#define MATH_ENGINE_QUANTITY_TEXT_MAX_BYTES UINT64_C(256)

#define MATH_ENGINE_QUANTITY_VERSION_1 UINT32_C(1)

MATH_ENGINE_API math_engine_status_t math_engine_quantity_init_binary32(
    float value, const math_engine_unit_t* unit, math_engine_quantity_t* out_quantity);

MATH_ENGINE_API math_engine_status_t math_engine_quantity_init_binary64(
    double value, const math_engine_unit_t* unit, math_engine_quantity_t* out_quantity);

MATH_ENGINE_API math_engine_status_t math_engine_quantity_init_fixed(
    int64_t coefficient, int32_t scale, const math_engine_unit_t* unit,
    math_engine_quantity_t* out_quantity);

MATH_ENGINE_API math_engine_status_t math_engine_quantity_init_precision(
    math_engine_quantity_precision_ref_t value, const math_engine_unit_t* unit,
    math_engine_quantity_t* out_quantity);

MATH_ENGINE_API math_engine_status_t math_engine_quantity_validate(
    const math_engine_quantity_t* quantity);

MATH_ENGINE_API math_engine_status_t math_engine_quantity_convert_unit(
    const math_engine_quantity_t* quantity, const math_engine_unit_t* target_unit,
    const math_engine_quantity_request_t* request,
    math_engine_quantity_result_t* out_result);

MATH_ENGINE_API math_engine_status_t math_engine_quantity_convert_numeric(
    const math_engine_quantity_t* quantity,
    const math_engine_quantity_request_t* request,
    math_engine_quantity_result_t* out_result);

MATH_ENGINE_API math_engine_status_t math_engine_quantity_evaluate(
    math_engine_quantity_operation_t operation,
    const math_engine_quantity_t* lhs, const math_engine_quantity_t* rhs,
    const math_engine_quantity_request_t* request,
    math_engine_quantity_result_t* out_result);

MATH_ENGINE_API math_engine_status_t math_engine_unit_parse_expression(
    const char* text, uint64_t text_size, math_engine_unit_t* out_unit);

MATH_ENGINE_API math_engine_status_t math_engine_unit_format_expression(
    const math_engine_unit_t* unit, char* buffer, uint64_t capacity,
    uint64_t* out_size);

MATH_ENGINE_API math_engine_status_t math_engine_quantity_parse(
    const char* text, uint64_t text_size,
    const math_engine_quantity_request_t* request,
    math_engine_quantity_result_t* out_result);

MATH_ENGINE_API math_engine_status_t math_engine_quantity_format(
    const math_engine_quantity_t* quantity, const void* precision_context,
    char* buffer, uint64_t capacity, uint64_t* out_size);

MATH_ENGINE_API size_t math_engine_constant_catalog_count(void);

MATH_ENGINE_API const math_engine_constant_record_t* math_engine_constant_catalog_at(
    size_t index);

MATH_ENGINE_API math_engine_status_t math_engine_constant_catalog_find(
    const char* alias, const math_engine_constant_record_t** out_record);

MATH_ENGINE_API math_engine_status_t math_engine_constant_catalog_find_id(
    uint64_t stable_id, const math_engine_constant_record_t** out_record);

MATH_ENGINE_API uint64_t math_engine_constant_catalog_fingerprint(void);

MATH_ENGINE_API const char* math_engine_constant_catalog_input_sha256(void);