Math Engine Reference: Decimal Fixed

math_engine_decimal_result_t 에 기록되는 연산 종류.

typedef enum math_engine_decimal_operation {
    MATH_ENGINE_DECIMAL_OPERATION_INVALID = 0, /**< 결과가 초기화 상태이거나 operation provenance가 없음을 나타낸다. */
    MATH_ENGINE_DECIMAL_OPERATION_RESCALE = 1, /**< 한 값의 decimal quantum을 명시 scale로 바꾼 결과다. */
    MATH_ENGINE_DECIMAL_OPERATION_ADD = 2, /**< 두 값을 공통 working scale에서 더한 결과다. */
    MATH_ENGINE_DECIMAL_OPERATION_SUBTRACT = 3, /**< 오른쪽 값을 왼쪽 값에서 뺀 결과다. */
    MATH_ENGINE_DECIMAL_OPERATION_MULTIPLY = 4, /**< 두 coefficient를 정확히 곱한 뒤 양자화한 결과다. */
    MATH_ENGINE_DECIMAL_OPERATION_DIVIDE = 5, /**< 두 decimal 값의 정확한 비율을 결과 scale로 양자화한 결과다. */
    MATH_ENGINE_DECIMAL_OPERATION_BASIS_POINTS = 6, /**< 금액에 1/10000 단위의 signed basis-point 비율을 적용한 결과다. */
    MATH_ENGINE_DECIMAL_OPERATION_BATCH_SUM = 7 /**< 배열을 순서 독립적으로 누적하고 한 번 양자화한 결과다. */
} math_engine_decimal_operation_t;

정확한 고정소수점 값. 0은 별도의 음수 표현을 갖지 않지만, 계수가 0이어도 양자를 보존하기 위해 0이 아닌 scale을 유지할 수 있다. reserved 는 반드시 0이어야 한다.

typedef struct math_engine_decimal_fixed {
    int64_t coefficient; /**< 정확한 값 =coefficient * 10^-scale=의 signed integer coefficient다. */
    int32_t scale; /**< 10진 소수 자릿수이자 quantum 지수이며 inclusive 0..18 범위다. */
    uint32_t reserved; /**< 향후 ABI 확장용이다. Caller와 producer 모두 0을 기록해야 한다. */
} math_engine_decimal_fixed_t;

버전이 있는 산술 결과와 감사 기록. discarded_numerator / discarded_denominator 는 반올림 전에 버린 값의 정확한 크기이며 discarded_sign 은 -1, 0, 1 중 하나다.

typedef struct math_engine_decimal_result {
    uint32_t struct_size; /**< Caller가 =sizeof(math_engine_decimal_result_t)=로 설정하는 byte 크기다. */
    uint32_t struct_version; /**< =MATH_ENGINE_DECIMAL_RESULT_VERSION_1=인 result ABI version이다. */
    math_engine_decimal_fixed_t value; /**< 성공한 operation의 최종 coefficient와 requested quantum이다. */
    uint32_t operation; /**< 결과를 만든 =math_engine_decimal_operation_t= 값이다. */
    uint32_t rounding; /**< 마지막 양자화에 적용한 =math_engine_decimal_rounding_t= 값이다. */
    uint32_t flags; /**< =MATH_ENGINE_DECIMAL_RESULT_FLAG_*= bit의 일관된 조합이다. */
    int32_t lhs_scale; /**< 첫 피연산자의 decimal scale이다. 단항 operation에도 원본 scale을 기록한다. */
    int32_t rhs_scale; /**< 둘째 피연산자의 scale이다. 둘째 피연산자가 없으면 0이다. */
    int32_t result_scale; /**< =value.scale=과 같은 caller-requested 최종 scale이다. */
    int32_t working_scale; /**< 넓힌 정수 산술에서 반올림 전에 사용한 중간 decimal scale이다. */
    int32_t discarded_sign; /**< 버린 exact remainder의 부호로 -1, 0, 1 중 하나다. */
    uint32_t reserved32_a; /**< 향후 ABI 확장용이다. Producer는 0을 기록하고 consumer는 무시한다. */
    uint32_t reserved32_b; /**< 향후 ABI 확장용이다. Producer는 0을 기록하고 consumer는 무시한다. */
    math_engine_u128_t discarded_numerator; /**< 반올림 전에 버린 remainder 절댓값의 exact unsigned numerator다. */
    math_engine_u128_t discarded_denominator; /**< Discarded fraction의 exact positive unsigned denominator다. Exact 결과에서는 1이다. */
    uint64_t operand_count; /**< Operation이 소비한 값의 수다. Batch sum에서는 =count=, 이항 연산에서는 2다. */
    uint64_t operation_fingerprint; /**< Operation kind, operands, scale와 rounding을 결합한 deterministic audit fingerprint다. */
    uint64_t reserved64; /**< 향후 ABI 확장용이다. Producer는 0을 기록하고 consumer는 무시한다. */
} math_engine_decimal_result_t;

Fixed decimal이 지원하는 inclusive 최대 scale이며 양자는 =10^-18=이다.

#define MATH_ENGINE_DECIMAL_FIXED_SCALE_MAX INT32_C(18)

Fixed decimal이 지원하는 inclusive 최소 scale이며 양자는 =10^0=이다.

#define MATH_ENGINE_DECIMAL_FIXED_SCALE_MIN INT32_C(0)

결과 coefficient가 정확한 수학값을 손실 없이 표현함을 나타내는 bit다.

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

결과 quantum에서 정확한 수학값 일부가 버려졌음을 나타내는 bit다.

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

최종 result scale이 반올림 전 working scale과 달라 quantum이 바뀌었음을 나타내는 bit다.

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

버린 remainder에 명시 rounding policy를 실제 적용했음을 나타내는 bit다.

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

math_engine_decimal_result_t 의 최초 안정 ABI version이다.

#define MATH_ENGINE_DECIMAL_RESULT_VERSION_1 UINT32_C(1)

Canonical decimal wire value 하나의 고정 byte 수다.

#define MATH_ENGINE_DECIMAL_WIRE_SIZE UINT64_C(16)

Canonical little-endian decimal wire format의 최초 안정 version이다.

#define MATH_ENGINE_DECIMAL_WIRE_VERSION_1 UINT32_C(1)

값의 scale 범위와 reserved 필드를 검사한다.

• 매개변수 value: 검사할 호출자 소유 값. 함수가 변경하지 않는다.
• 반환: 유효하면 OK, 포인터가 null이거나 필드가 잘못되면 INVALID_ARGUMENT.
• Math Engine ownership: value=caller
• Math Engine nullable: value=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_decimal_fixed_validate(
    const math_engine_decimal_fixed_t* value);

수치를 바꾸지 않고 계수의 10진 후행 0과 scale을 함께 줄인다.

• 매개변수 value: 정규화할 값.
• 매개변수 out_canonical: 호출자가 소유한 결과. 모든 0은 coefficient 0, scale 0이 된다.
• 반환: 성공하면 OK, 입력 또는 출력 포인터가 잘못되면 INVALID_ARGUMENT.

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

• Math Engine ownership: out_canonical=caller
• Math Engine nullable: out_canonical=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_decimal_fixed_canonicalize(
    math_engine_decimal_fixed_t value,
    math_engine_decimal_fixed_t* out_canonical);

서로 다른 scale을 정확히 정렬하여 두 값을 비교한다.

• 매개변수 lhs: 왼쪽 피연산자.
• 매개변수 rhs: 오른쪽 피연산자.
• 매개변수 out_order: 호출자 소유 결과. lhs가 작으면 -1, 같으면 0, 크면 1.
• 반환: 성공하면 OK, 입력 필드나 출력 포인터가 잘못되면 INVALID_ARGUMENT, 내부 128비트 정렬 범위를 넘으면 OVERFLOW.

@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_decimal_fixed_compare(
    math_engine_decimal_fixed_t lhs,
    math_engine_decimal_fixed_t rhs,
    int32_t* out_order);

엄격한 로캘 독립 ASCII 10진 문자열을 해석한다.

• 매개변수 text: 길이가 text_size 인 읽기 전용 바이트열. NUL 종료는 요구하지 않는다.
• 매개변수 text_size: 입력 바이트 수. 단위는 byte이며 1 이상이어야 한다.
• 매개변수 out_value: 호출자 소유 결과. 입력의 소수부 후행 0을 scale로 보존한다.
• 반환: 성공하면 OK, 문법·포인터가 잘못되면 INVALID_ARGUMENT, scale이 18을 넘으면 OUT_OF_RANGE, 계수가 int64 범위를 넘으면 OVERFLOW.

@note 선택적 부호와 소수점 한 개만 허용하며 지수, 구분자, 공백을 거부한다. 실패하면 out_value 는 변경되지 않는다.

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

MATH_ENGINE_API math_engine_status_t math_engine_decimal_fixed_parse(
    const char* text,
    uint64_t text_size,
    math_engine_decimal_fixed_t* out_value);

저장된 10진 양자를 로캘 독립 ASCII로 정확히 출력한다.

• 매개변수 value: 출력할 값.
• 매개변수 buffer: 호출자 소유 버퍼. capacity 가 0이면 null일 수 있다.
• 매개변수 capacity: 버퍼 크기. 단위는 byte이며 종료 NUL 공간을 포함한다.
• 매개변수 out_size: 호출자 소유 필요 길이. 단위는 byte이며 종료 NUL은 제외한다.
• 반환: 성공하면 OK, 인수가 잘못되면 INVALID_ARGUMENT, 버퍼가 작으면 INSUFFICIENT_BUFFER.

@note 변환 가능한 입력이면 버퍼가 작아도 out_size 는 기록한다. 완전한 문자열과 NUL이 들어가기 전에는 buffer 를 변경하지 않으며, 그 밖의 실패에서는 모든 출력이 보존된다.

• Math Engine ownership: buffer=caller
• Math Engine ownership: out_size=caller
• Math Engine nullable: buffer=capacity_zero_only
• Math Engine nullable: out_size=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_decimal_fixed_format(
    math_engine_decimal_fixed_t value,
    char* buffer,
    uint64_t capacity,
    uint64_t* out_size);

버전, 계수, scale을 16바이트 little-endian wire 형식으로 인코딩한다.

• 매개변수 value: 인코딩할 값.
• 매개변수 buffer: 호출자 소유 출력 버퍼.
• 매개변수 capacity: 버퍼 크기. 단위는 byte이며 최소 MATH_ENGINE_DECIMAL_WIRE_SIZE.
• 반환: 성공하면 OK, 인수가 잘못되면 INVALID_ARGUMENT, 버퍼가 작으면 INSUFFICIENT_BUFFER.

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

• Math Engine ownership: buffer=caller
• Math Engine nullable: buffer=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_decimal_fixed_encode(
    math_engine_decimal_fixed_t value,
    uint8_t* buffer,
    uint64_t capacity);

16바이트 little-endian wire 형식을 디코딩하고 검증한다.

• 매개변수 buffer: 호출자 소유 읽기 전용 입력 버퍼.
• 매개변수 size: 입력 크기. 단위는 byte이며 정확히 MATH_ENGINE_DECIMAL_WIRE_SIZE.
• 매개변수 out_value: 호출자 소유 디코딩 결과.
• 반환: 성공하면 OK, 포인터·필드가 잘못되면 INVALID_ARGUMENT, 크기가 다르면 INVALID_SIZE, wire 버전을 지원하지 않으면 UNSUPPORTED.

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

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

MATH_ENGINE_API math_engine_status_t math_engine_decimal_fixed_decode(
    const uint8_t* buffer,
    uint64_t size,
    math_engine_decimal_fixed_t* out_value);

명시한 반올림 정책으로 값의 10진 양자를 변경한다.

• 매개변수 value: 원본 값.
• 매개변수 result_scale: 결과 scale. 범위는 0..18.
• 매개변수 rounding: 버리는 자릿수에 적용할 반올림 정책.
• 매개변수 out_result: 호출자가 초기화한 버전 결과 구조체.
• 반환: 성공하면 OK, 입력이 잘못되면 INVALID_ARGUMENT, 결과 구조체 크기가 다르면 INVALID_SIZE, 버전이 다르면 UNSUPPORTED, 결과 계수가 넘치면 OVERFLOW.

@note 성공 시에만 out_result 전체를 기록한다.

• 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_decimal_fixed_rescale(
    math_engine_decimal_fixed_t value,
    int32_t result_scale,
    math_engine_decimal_rounding_t rounding,
    math_engine_decimal_result_t* out_result);

넓힌 공통 scale에서 정확히 더한 뒤 결과 scale로 한 번만 양자화한다.

• 매개변수 lhs: 왼쪽 피연산자.
• 매개변수 rhs: 오른쪽 피연산자.
• 매개변수 result_scale: 결과 scale. 범위는 0..18.
• 매개변수 rounding: 마지막 양자화에만 적용할 반올림 정책.
• 매개변수 out_result: 호출자가 초기화한 버전 결과 구조체.
• 반환: 성공하면 OK, 계약 위반은 INVALID_ARGUMENT/INVALID_SIZE/UNSUPPORTED, 중간값 또는 결과 계수 범위 초과는 OVERFLOW.

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

• 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_decimal_fixed_add(
    math_engine_decimal_fixed_t lhs,
    math_engine_decimal_fixed_t rhs,
    int32_t result_scale,
    math_engine_decimal_rounding_t rounding,
    math_engine_decimal_result_t* out_result);

넓힌 공통 scale에서 정확히 뺀 뒤 결과 scale로 한 번만 양자화한다.

• 매개변수 lhs: 왼쪽 피연산자.
• 매개변수 rhs: 오른쪽 피연산자.
• 매개변수 result_scale: 결과 scale. 범위는 0..18.
• 매개변수 rounding: 마지막 양자화에만 적용할 반올림 정책.
• 매개변수 out_result: 호출자가 초기화한 버전 결과 구조체.
• 반환: 성공하면 OK, 계약 위반은 INVALID_ARGUMENT/INVALID_SIZE/UNSUPPORTED, 중간값 또는 결과 계수 범위 초과는 OVERFLOW.

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

• 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_decimal_fixed_subtract(
    math_engine_decimal_fixed_t lhs,
    math_engine_decimal_fixed_t rhs,
    int32_t result_scale,
    math_engine_decimal_rounding_t rounding,
    math_engine_decimal_result_t* out_result);

두 계수를 128비트로 정확히 곱한 뒤 결과 scale로 한 번만 양자화한다.

• 매개변수 lhs: 왼쪽 피연산자.
• 매개변수 rhs: 오른쪽 피연산자.
• 매개변수 result_scale: 결과 scale. 범위는 0..18.
• 매개변수 rounding: 마지막 양자화에만 적용할 반올림 정책.
• 매개변수 out_result: 호출자가 초기화한 버전 결과 구조체.
• 반환: 성공하면 OK, 계약 위반은 INVALID_ARGUMENT/INVALID_SIZE/UNSUPPORTED, 결과 계수 범위 초과는 OVERFLOW.

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

• 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_decimal_fixed_multiply(
    math_engine_decimal_fixed_t lhs,
    math_engine_decimal_fixed_t rhs,
    int32_t result_scale,
    math_engine_decimal_rounding_t rounding,
    math_engine_decimal_result_t* out_result);

두 10진 값을 정확한 정수 비율로 나누고 결과 scale에서만 반올림한다.

• 매개변수 lhs: 분자 값.
• 매개변수 rhs: 분모 값.
• 매개변수 result_scale: 결과 scale. 범위는 0..18.
• 매개변수 rounding: 마지막 양자화에만 적용할 반올림 정책.
• 매개변수 out_result: 호출자가 초기화한 버전 결과 구조체.
• 반환: 성공하면 OK, 0으로 나누면 DIVIDE_BY_ZERO, 계약 위반은 INVALID_ARGUMENT/INVALID_SIZE/UNSUPPORTED, 범위 초과는 OVERFLOW.

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

• 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_decimal_fixed_divide(
    math_engine_decimal_fixed_t lhs,
    math_engine_decimal_fixed_t rhs,
    int32_t result_scale,
    math_engine_decimal_rounding_t rounding,
    math_engine_decimal_result_t* out_result);

금액에 부호 있는 basis point 비율을 적용한다.

• 매개변수 amount: 원본 금액.
• 매개변수 basis_points: 적용 비율. 단위는 bp이며 10,000 bp가 1배다.
• 매개변수 result_scale: 결과 scale. 범위는 0..18.
• 매개변수 rounding: 결과 양자화에 적용할 반올림 정책.
• 매개변수 out_result: 호출자가 초기화한 버전 결과 구조체.
• 반환: 성공하면 OK, 계약 위반은 INVALID_ARGUMENT/INVALID_SIZE/UNSUPPORTED, 범위 초과는 OVERFLOW.

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

• 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_decimal_fixed_apply_basis_points(
    math_engine_decimal_fixed_t amount,
    int64_t basis_points,
    int32_t result_scale,
    math_engine_decimal_rounding_t rounding,
    math_engine_decimal_result_t* out_result);

메모리 할당 없이 여러 값을 정확히 정렬하여 합하고 한 번만 반올림한다.

• 매개변수 values: 호출자 소유 읽기 전용 배열. count 가 0일 때만 null일 수 있다.
• 매개변수 count: 배열 원소 수.
• 매개변수 result_scale: 결과 scale. 범위는 0..18.
• 매개변수 rounding: 마지막 양자화에만 적용할 반올림 정책.
• 매개변수 out_result: 호출자가 초기화한 버전 결과 구조체.
• 반환: 성공하면 OK, 계약 위반은 INVALID_ARGUMENT/INVALID_SIZE/UNSUPPORTED, 누적값 또는 결과 계수 범위 초과는 OVERFLOW.

@note 양수와 음수 크기를 따로 누적하므로 성공한 결과와 fingerprint는 입력 순서와 무관하다. 실패하면 out_result 는 변경되지 않는다.

• Math Engine ownership: values=caller
• Math Engine ownership: out_result=caller
• Math Engine nullable: values=count_zero_only
• Math Engine nullable: out_result=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_decimal_fixed_sum(
    const math_engine_decimal_fixed_t* values,
    uint64_t count,
    int32_t result_scale,
    math_engine_decimal_rounding_t rounding,
    math_engine_decimal_result_t* out_result);