Math Engine Reference: Checked Integer

문서 탐색

개요

Allocation-free checked integer and widened arithmetic C ABI.

All operations are deterministic, have no hidden mutable state, and preserve every output object when they return a non-OK status. Signed operations never depend on signed overflow, implementation-defined right shift, or negation of INT64_MIN. Compiler intrinsics are private implementation details and never enter this ABI.

실행 원본: include/math_engine/math_engine_checked_integer.h
분류: 수 표현·실행 profile

공개 API

Header 사용 시작

이 module의 public declaration을 사용하려면 installed SDK의 다음 header를 include한다.

#include <math_engine/math_engine_checked_integer.h>

Type과 callback

`math_engine_decimal_rounding_t`

Decimal and fixed-point quotient rounding policy.

typedef enum math_engine_decimal_rounding {
    /** Invalid sentinel; operations reject it with INVALID_ARGUMENT. */
    MATH_ENGINE_DECIMAL_ROUNDING_INVALID = 0,
    /** Round to the nearest integer; an exact tie selects the even integer. */
    MATH_ENGINE_DECIMAL_ROUNDING_HALF_EVEN = 1,
    /** Round to the nearest integer; an exact tie moves away from zero. */
    MATH_ENGINE_DECIMAL_ROUNDING_HALF_UP = 2,
    /** Discard the remainder and move toward zero. */
    MATH_ENGINE_DECIMAL_ROUNDING_TOWARD_ZERO = 3,
    /** Move toward positive infinity when a nonzero remainder exists. */
    MATH_ENGINE_DECIMAL_ROUNDING_UPWARD = 4,
    /** Move toward negative infinity when a nonzero remainder exists. */
    MATH_ENGINE_DECIMAL_ROUNDING_DOWNWARD = 5
} math_engine_decimal_rounding_t;

math_engine_decimal_rounding_t.MATH_ENGINE_DECIMAL_ROUNDING_INVALID
Invalid sentinel; operations reject it with INVALID_ARGUMENT.
```
/** Invalid sentinel; operations reject it with INVALID_ARGUMENT. */
    MATH_ENGINE_DECIMAL_ROUNDING_INVALID = 0,
```
math_engine_decimal_rounding_t.MATH_ENGINE_DECIMAL_ROUNDING_HALF_EVEN
Round to the nearest integer; an exact tie selects the even integer.
```
/** Round to the nearest integer; an exact tie selects the even integer. */
    MATH_ENGINE_DECIMAL_ROUNDING_HALF_EVEN = 1,
```
math_engine_decimal_rounding_t.MATH_ENGINE_DECIMAL_ROUNDING_HALF_UP
Round to the nearest integer; an exact tie moves away from zero.
```
/** Round to the nearest integer; an exact tie moves away from zero. */
    MATH_ENGINE_DECIMAL_ROUNDING_HALF_UP = 2,
```
math_engine_decimal_rounding_t.MATH_ENGINE_DECIMAL_ROUNDING_TOWARD_ZERO
Discard the remainder and move toward zero.
```
/** Discard the remainder and move toward zero. */
    MATH_ENGINE_DECIMAL_ROUNDING_TOWARD_ZERO = 3,
```
math_engine_decimal_rounding_t.MATH_ENGINE_DECIMAL_ROUNDING_UPWARD
Move toward positive infinity when a nonzero remainder exists.
```
/** Move toward positive infinity when a nonzero remainder exists. */
    MATH_ENGINE_DECIMAL_ROUNDING_UPWARD = 4,
```
math_engine_decimal_rounding_t.MATH_ENGINE_DECIMAL_ROUNDING_DOWNWARD
Move toward negative infinity when a nonzero remainder exists.
```
/** Move toward negative infinity when a nonzero remainder exists. */
    MATH_ENGINE_DECIMAL_ROUNDING_DOWNWARD = 5,
```

`math_engine_u128_t`

Little-word-first unsigned 128-bit value.

typedef struct math_engine_u128 {
    uint64_t low;  /**< Bits 0 through 63. */
    uint64_t high; /**< Bits 64 through 127. */
} math_engine_u128_t;

math_engine_u128_t.low
Bits 0 through 63.
```
uint64_t low;
```
math_engine_u128_t.high
Bits 64 through 127.
```
uint64_t high;
```

`math_engine_i128_t`

Little-word-first two's-complement 128-bit bit pattern.

typedef struct math_engine_i128 {
    uint64_t low;  /**< Bits 0 through 63. */
    uint64_t high; /**< Bits 64 through 127, including the sign bit. */
} math_engine_i128_t;

math_engine_i128_t.low
Bits 0 through 63.
```
uint64_t low;
```
math_engine_i128_t.high
Bits 64 through 127, including the sign bit.
```
uint64_t high;
```

`math_engine_i64_divrem_t`

Signed quotient and remainder produced by truncation toward zero.

typedef struct math_engine_i64_divrem {
    int64_t quotient;  /**< Truncation-toward-zero quotient. */
    int64_t remainder; /**< Remainder with the numerator's sign. */
} math_engine_i64_divrem_t;

math_engine_i64_divrem_t.quotient
Truncation-toward-zero quotient.
```
int64_t quotient;
```
math_engine_i64_divrem_t.remainder
Remainder with the numerator's sign.
```
int64_t remainder;
```

`math_engine_u64_divrem_t`

Unsigned quotient and remainder.

typedef struct math_engine_u64_divrem {
    uint64_t quotient;  /**< Exact unsigned quotient. */
    uint64_t remainder; /**< Remainder smaller than the denominator. */
} math_engine_u64_divrem_t;

math_engine_u64_divrem_t.quotient
Exact unsigned quotient.
```
uint64_t quotient;
```
math_engine_u64_divrem_t.remainder
Remainder smaller than the denominator.
```
uint64_t remainder;
```

`math_engine_u128_divrem_t`

Unsigned 128-by-64 quotient and remainder.

typedef struct math_engine_u128_divrem {
    math_engine_u128_t quotient; /**< Full-width quotient. */
    uint64_t remainder;          /**< Remainder smaller than the denominator. */
    uint64_t reserved;           /**< Written as zero; reserved for ABI growth. */
} math_engine_u128_divrem_t;

math_engine_u128_divrem_t.quotient
Full-width quotient.
```
math_engine_u128_t quotient;
```
math_engine_u128_divrem_t.remainder
Remainder smaller than the denominator.
```
uint64_t remainder;
```
math_engine_u128_divrem_t.reserved
Written as zero; reserved for ABI growth.
```
uint64_t reserved;
```

Function

`math_engine_i64_magnitude`

Computes the unsigned magnitude of a signed 64-bit value.

매개변수 value: Input value, including INT64_MIN.
매개변수 out_magnitude: Caller-owned result.
반환: OK, or INVALID_ARGUMENT when out_magnitude is NULL.
Math Engine ownership: out_magnitude=caller
Math Engine nullable: out_magnitude=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_i64_magnitude(
    int64_t value, uint64_t* out_magnitude);

`math_engine_i64_checked_add`

Adds two signed 64-bit values with overflow detection.

매개변수 lhs: Left operand.
매개변수 rhs: Right operand.
매개변수 out_value: Caller-owned sum.
반환: OK, INVALID_ARGUMENT, or OVERFLOW.
Math Engine ownership: out_value=caller
Math Engine nullable: out_value=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_i64_checked_add(
    int64_t lhs, int64_t rhs, int64_t* out_value);

`math_engine_i64_checked_sub`

Subtracts two signed 64-bit values with overflow detection.

매개변수 lhs: Left operand.
매개변수 rhs: Right operand.
매개변수 out_value: Caller-owned difference.
반환: OK, INVALID_ARGUMENT, or OVERFLOW.
Math Engine ownership: out_value=caller
Math Engine nullable: out_value=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_i64_checked_sub(
    int64_t lhs, int64_t rhs, int64_t* out_value);

`math_engine_i64_checked_mul`

Multiplies two signed 64-bit values with overflow detection.

매개변수 lhs: Left operand.
매개변수 rhs: Right operand.
매개변수 out_value: Caller-owned product.
반환: OK, INVALID_ARGUMENT, or OVERFLOW.
Math Engine ownership: out_value=caller
Math Engine nullable: out_value=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_i64_checked_mul(
    int64_t lhs, int64_t rhs, int64_t* out_value);

`math_engine_i64_checked_divrem`

Divides signed values and returns quotient and remainder explicitly.

매개변수 numerator: Dividend.
매개변수 denominator: Divisor.
매개변수 out_result: Caller-owned quotient/remainder pair.
반환: OK, INVALID_ARGUMENT, DIVIDE_BY_ZERO, or OVERFLOW for INT64_MIN/-1.
Math Engine ownership: out_result=caller
Math Engine nullable: out_result=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_i64_checked_divrem(
    int64_t numerator, int64_t denominator,
    math_engine_i64_divrem_t* out_result);

`math_engine_i64_div_round`

Divides signed values using an explicit decimal rounding policy.

매개변수 numerator: Dividend.
매개변수 denominator: Divisor.
매개변수 rounding: Required non-sentinel rounding policy.
매개변수 out_quotient: Caller-owned rounded quotient.
반환: OK, INVALID_ARGUMENT, DIVIDE_BY_ZERO, or OVERFLOW.
Math Engine ownership: out_quotient=caller
Math Engine nullable: out_quotient=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_i64_div_round(
    int64_t numerator, int64_t denominator,
    math_engine_decimal_rounding_t rounding, int64_t* out_quotient);

`math_engine_u64_checked_add`

Adds two unsigned 64-bit values with overflow detection.

매개변수 lhs: Left operand.
매개변수 rhs: Right operand.
매개변수 out_value: Caller-owned sum.
반환: OK, INVALID_ARGUMENT, or OVERFLOW.
Math Engine ownership: out_value=caller
Math Engine nullable: out_value=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_u64_checked_add(
    uint64_t lhs, uint64_t rhs, uint64_t* out_value);

`math_engine_u64_checked_sub`

Subtracts unsigned values and reports underflow as OVERFLOW.

매개변수 lhs: Left operand.
매개변수 rhs: Right operand.
매개변수 out_value: Caller-owned difference.
반환: OK, INVALID_ARGUMENT, or OVERFLOW when lhs < rhs.
Math Engine ownership: out_value=caller
Math Engine nullable: out_value=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_u64_checked_sub(
    uint64_t lhs, uint64_t rhs, uint64_t* out_value);

`math_engine_u64_checked_mul`

Multiplies two unsigned 64-bit values with overflow detection.

매개변수 lhs: Left operand.
매개변수 rhs: Right operand.
매개변수 out_value: Caller-owned product.
반환: OK, INVALID_ARGUMENT, or OVERFLOW.
Math Engine ownership: out_value=caller
Math Engine nullable: out_value=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_u64_checked_mul(
    uint64_t lhs, uint64_t rhs, uint64_t* out_value);

`math_engine_u64_checked_divrem`

Divides unsigned values and returns quotient and remainder explicitly.

매개변수 numerator: Dividend.
매개변수 denominator: Divisor.
매개변수 out_result: Caller-owned quotient/remainder pair.
반환: OK, INVALID_ARGUMENT, or DIVIDE_BY_ZERO.
Math Engine ownership: out_result=caller
Math Engine nullable: out_result=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_u64_checked_divrem(
    uint64_t numerator, uint64_t denominator,
    math_engine_u64_divrem_t* out_result);

`math_engine_i64_checked_shift_left`

Multiplies a signed value by 2^shift with range checking.

매개변수 value: Input value.
매개변수 shift: Shift count in the inclusive range 0..63.
매개변수 out_value: Caller-owned result.
반환: OK, INVALID_ARGUMENT, INVALID_SHIFT, or OVERFLOW.
Math Engine ownership: out_value=caller
Math Engine nullable: out_value=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_i64_checked_shift_left(
    int64_t value, uint32_t shift, int64_t* out_value);

`math_engine_i64_shift_right_toward_zero`

Divides a signed value by 2^shift with truncation toward zero.

매개변수 value: Input value.
매개변수 shift: Shift count in the inclusive range 0..63.
매개변수 out_value: Caller-owned result.
반환: OK, INVALID_ARGUMENT, or INVALID_SHIFT.
Math Engine ownership: out_value=caller
Math Engine nullable: out_value=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_i64_shift_right_toward_zero(
    int64_t value, uint32_t shift, int64_t* out_value);

`math_engine_u64_checked_shift_left`

Shifts an unsigned value left and rejects discarded high bits.

매개변수 value: Input value.
매개변수 shift: Shift count in the inclusive range 0..63.
매개변수 out_value: Caller-owned result.
반환: OK, INVALID_ARGUMENT, INVALID_SHIFT, or OVERFLOW.
Math Engine ownership: out_value=caller
Math Engine nullable: out_value=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_u64_checked_shift_left(
    uint64_t value, uint32_t shift, uint64_t* out_value);

`math_engine_u64_shift_right`

Performs a range-checked unsigned logical right shift.

매개변수 value: Input value.
매개변수 shift: Shift count in the inclusive range 0..63.
매개변수 out_value: Caller-owned result.
반환: OK, INVALID_ARGUMENT, or INVALID_SHIFT.
Math Engine ownership: out_value=caller
Math Engine nullable: out_value=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_u64_shift_right(
    uint64_t value, uint32_t shift, uint64_t* out_value);

`math_engine_u64_mul_wide`

Computes the exact 128-bit product of two unsigned 64-bit values.

매개변수 lhs: Left operand.
매개변수 rhs: Right operand.
매개변수 out_product: Caller-owned widened product.
반환: OK or INVALID_ARGUMENT.
Math Engine ownership: out_product=caller
Math Engine nullable: out_product=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_u64_mul_wide(
    uint64_t lhs, uint64_t rhs, math_engine_u128_t* out_product);

`math_engine_i64_mul_wide`

Computes the exact two's-complement 128-bit signed product.

매개변수 lhs: Left operand.
매개변수 rhs: Right operand.
매개변수 out_product: Caller-owned widened product bit pattern.
반환: OK or INVALID_ARGUMENT.
Math Engine ownership: out_product=caller
Math Engine nullable: out_product=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_i64_mul_wide(
    int64_t lhs, int64_t rhs, math_engine_i128_t* out_product);

`math_engine_u128_divrem_u64`

Divides an unsigned 128-bit numerator by a 64-bit denominator.

매개변수 numerator: Full-width dividend.
매개변수 denominator: Divisor.
매개변수 out_result: Caller-owned full-width quotient and remainder.
반환: OK, INVALID_ARGUMENT, or DIVIDE_BY_ZERO.
Math Engine ownership: out_result=caller
Math Engine nullable: out_result=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_u128_divrem_u64(
    math_engine_u128_t numerator, uint64_t denominator,
    math_engine_u128_divrem_t* out_result);

`math_engine_u128_compare`

부호 없는 128비트 값을 비교한다.

매개변수 lhs: 왼쪽 피연산자.
매개변수 rhs: 오른쪽 피연산자.
매개변수 out_order: 호출자 소유 결과. lhs가 작으면 -1, 같으면 0, 크면 1.
반환: 성공하면 OK, 출력 포인터가 null이면 INVALID_ARGUMENT.

@note 실패하면 out_order 는 변경되지 않는다.

Math Engine ownership: out_order=caller
Math Engine nullable: out_order=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_u128_compare(
    math_engine_u128_t lhs,
    math_engine_u128_t rhs,
    int32_t* out_order);

`math_engine_u128_checked_add`

부호 없는 128비트 값을 더하고 bit 127 밖의 carry를 검출한다.

매개변수 lhs: 왼쪽 피연산자.
매개변수 rhs: 오른쪽 피연산자.
매개변수 out_value: 호출자 소유 합계.
반환: 성공하면 OK, 출력 포인터가 null이면 INVALID_ARGUMENT, 넘치면 OVERFLOW.

@note 실패하면 out_value 는 변경되지 않는다.

Math Engine ownership: out_value=caller
Math Engine nullable: out_value=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_u128_checked_add(
    math_engine_u128_t lhs,
    math_engine_u128_t rhs,
    math_engine_u128_t* out_value);

`math_engine_u128_checked_sub`

부호 없는 128비트 값을 빼고 음수가 되는 경우를 검출한다.

매개변수 lhs: 왼쪽 피연산자.
매개변수 rhs: 오른쪽 피연산자.
매개변수 out_value: 호출자 소유 차이.
반환: 성공하면 OK, 출력 포인터가 null이면 INVALID_ARGUMENT, lhs가 rhs보다 작으면 UNDERFLOW.

@note 실패하면 out_value 는 변경되지 않는다.

Math Engine ownership: out_value=caller
Math Engine nullable: out_value=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_u128_checked_sub(
    math_engine_u128_t lhs,
    math_engine_u128_t rhs,
    math_engine_u128_t* out_value);

`math_engine_u128_checked_mul_u64`

부호 없는 128비트 값과 64비트 값을 곱하고 넘침을 검출한다.

매개변수 value: 128비트 피연산자.
매개변수 multiplier: 64비트 피연산자.
매개변수 out_product: 호출자 소유 곱.
반환: 성공하면 OK, 출력 포인터가 null이면 INVALID_ARGUMENT, 넘치면 OVERFLOW.

@note 실패하면 out_product 는 변경되지 않는다.

Math Engine ownership: out_product=caller
Math Engine nullable: out_product=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_u128_checked_mul_u64(
    math_engine_u128_t value,
    uint64_t multiplier,
    math_engine_u128_t* out_product);

`math_engine_u64_gcd`

Computes the greatest common divisor; gcd(0,0) is zero.

매개변수 lhs: First value.
매개변수 rhs: Second value.
매개변수 out_gcd: Caller-owned result.
반환: OK or INVALID_ARGUMENT.
Math Engine ownership: out_gcd=caller
Math Engine nullable: out_gcd=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_u64_gcd(
    uint64_t lhs, uint64_t rhs, uint64_t* out_gcd);

`math_engine_u64_decimal_digits`

Counts base-10 digits; zero has one digit.

매개변수 value: Input value.
매개변수 out_digits: Caller-owned digit count in the range 1..20.
반환: OK or INVALID_ARGUMENT.
Math Engine ownership: out_digits=caller
Math Engine nullable: out_digits=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_u64_decimal_digits(
    uint64_t value, uint32_t* out_digits);

`math_engine_u64_pow10`

Computes exact 10^exponent for an exponent in 0..19.

매개변수 exponent: Base-10 exponent.
매개변수 out_value: Caller-owned power of ten.
반환: OK, INVALID_ARGUMENT, or OUT_OF_RANGE.
Math Engine ownership: out_value=caller
Math Engine nullable: out_value=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_u64_pow10(
    uint32_t exponent, uint64_t* out_value);

Math Engine Reference: Checked Integer

문서 탐색

개요

관련 public header

공개 API

Header 사용 시작

Type과 callback

math_engine_decimal_rounding_t

math_engine_u128_t

math_engine_i128_t

math_engine_i64_divrem_t

math_engine_u64_divrem_t

math_engine_u128_divrem_t

Function

math_engine_i64_magnitude

math_engine_i64_checked_add

math_engine_i64_checked_sub

math_engine_i64_checked_mul

math_engine_i64_checked_divrem

math_engine_i64_div_round

math_engine_u64_checked_add

math_engine_u64_checked_sub

math_engine_u64_checked_mul

math_engine_u64_checked_divrem

math_engine_i64_checked_shift_left

math_engine_i64_shift_right_toward_zero

math_engine_u64_checked_shift_left

math_engine_u64_shift_right

math_engine_u64_mul_wide

math_engine_i64_mul_wide

math_engine_u128_divrem_u64

math_engine_u128_compare

math_engine_u128_checked_add

math_engine_u128_checked_sub

math_engine_u128_checked_mul_u64

math_engine_u64_gcd

math_engine_u64_decimal_digits

math_engine_u64_pow10