Math Engine Reference: Units

Dimensionless 값의 표시 의미다. SI exponent가 하나라도 0이 아니면 PHYSICAL만 유효하다.

typedef enum math_engine_display_kind {
    MATH_ENGINE_DISPLAY_PHYSICAL = 0, /**< SI exponent가 정의하는 일반 물리 dimension 또는 plain dimensionless 값이다. */
    MATH_ENGINE_DISPLAY_PLANE_ANGLE = 1, /**< SI exponent는 모두 0이지만 plane angle 의미와 radian 계열 표시를 보존한다. */
    MATH_ENGINE_DISPLAY_SOLID_ANGLE = 2, /**< SI exponent는 모두 0이지만 solid angle 의미와 steradian 표시를 보존한다. */
    MATH_ENGINE_DISPLAY_LOGARITHMIC_RATIO = 3, /**< SI exponent는 모두 0인 logarithmic ratio/level 표시 의미다. */
    MATH_ENGINE_DISPLAY_COUNT = 4 /**< SI exponent는 모두 0인 discrete count 의미다. */
} math_engine_display_kind_t;

SI exponent 7개와 display kind로 이루어진 fixed-width, padding-free 값이다.

typedef struct math_engine_dimension {
    int8_t exponents[MATH_ENGINE_DIMENSION_COUNT]; /**< Length, mass, time, current, temperature, amount, luminous-intensity 순서의 signed exponent다. 각 값은 -127..127이다. */
    uint8_t display_kind; /**< Dimensionless 표시 의미를 보존하는 =math_engine_display_kind_t= 값이다. */
} math_engine_dimension_t;

표시값을 coherent SI 값으로 보내는 transform 종류다.

typedef enum math_engine_unit_transform {
    MATH_ENGINE_UNIT_TRANSFORM_LINEAR = 0, /**< Coherent SI 값이 =display_value * scale=인 linear transform이다. */
    MATH_ENGINE_UNIT_TRANSFORM_AFFINE = 1, /**< Coherent SI 값이 =display_value * scale + offset=인 affine transform이다. */
    MATH_ENGINE_UNIT_TRANSFORM_LOGARITHMIC = 2 /**< Coherent SI 값이 =scale * pow(log_base, display_value / log_factor)=인 transform이다. */
} math_engine_unit_transform_t;

Caller-owned unit descriptor다.

Linear: coherent = value * scale. Affine: coherent = value * scale + offset. Logarithmic: coherent = scale * pow(log_base, value / log_factor).

typedef struct math_engine_unit {
    uint32_t struct_size; /**< Caller가 =sizeof(math_engine_unit_t)=로 설정하는 byte 크기다. */
    uint32_t struct_version; /**< =MATH_ENGINE_UNIT_VERSION_1=인 unit ABI version이다. */
    uint64_t stable_id; /**< Catalog release 사이에서도 동일 canonical unit을 식별하는 nonzero ID다. */
    math_engine_dimension_t dimension; /**< Unit가 측정하는 SI dimension과 dimensionless display kind다. */
    int32_t transform; /**< Display value를 coherent 값으로 보내는 =math_engine_unit_transform_t= 값이다. */
    uint32_t flags; /**< =MATH_ENGINE_UNIT_FLAG_*= bit의 조합이며 known mask 밖 bit는 0이어야 한다. */
    double scale; /**< Linear/affine multiplier 또는 logarithmic coherent reference scale인 finite positive 값이다. */
    double offset; /**< Affine transform에서 scale 뒤 더하는 coherent-unit offset이다. Linear/logarithmic에서는 0이다. */
    double log_base; /**< Logarithmic transform의 finite base로 양수이고 1이 아니어야 한다. 다른 transform에서는 0이다. */
    double log_factor; /**< Logarithmic display exponent divisor인 finite nonzero 값이다. 다른 transform에서는 0이다. */
} math_engine_unit_t;

Process lifetime 동안 immutable인 static prefix catalog record다. 문자열 pointer도 같다.

typedef struct math_engine_prefix_record {
    uint32_t struct_size; /**< Catalog가 기록한 =sizeof(math_engine_prefix_record_t)= byte 크기다. */
    uint32_t struct_version; /**< =MATH_ENGINE_PREFIX_RECORD_VERSION_1=인 record ABI version이다. */
    uint64_t stable_id; /**< Catalog release 사이에서 같은 prefix를 식별하는 nonzero ID다. */
    int32_t decimal_exponent; /**< Prefix multiplier =10^decimal_exponent=의 signed exponent다. */
    uint32_t reserved; /**< 향후 ABI 확장용이다. Catalog는 0을 기록하고 consumer는 무시한다. */
    const char* canonical_name; /**< Process lifetime 동안 유효한 non-null immutable canonical UTF-8 이름을 빌려준다. Caller가 해제하지 않는다. */
    const char* symbol; /**< Process lifetime 동안 유효한 non-null immutable canonical UTF-8 symbol을 빌려준다. */
    const char* ascii_alias; /**< Process lifetime 동안 유효한 nullable immutable ASCII alias다. Alias가 없으면 NULL이다. */
} math_engine_prefix_record_t;

Process lifetime 동안 immutable인 static unit catalog record다. 문자열 pointer도 같다.

typedef struct math_engine_unit_record {
    uint32_t struct_size; /**< Catalog가 기록한 =sizeof(math_engine_unit_record_t)= byte 크기다. */
    uint32_t struct_version; /**< =MATH_ENGINE_UNIT_RECORD_VERSION_1=인 record ABI version이다. */
    uint64_t stable_id; /**< Catalog release 사이에서 같은 unit record를 식별하는 nonzero ID다. */
    const char* canonical_name; /**< Process lifetime 동안 유효한 non-null immutable canonical UTF-8 이름을 빌려준다. Caller가 해제하지 않는다. */
    const char* symbol; /**< Process lifetime 동안 유효한 non-null immutable canonical UTF-8 unit symbol을 빌려준다. */
    const char* ascii_alias; /**< Process lifetime 동안 유효한 nullable immutable ASCII alias다. Alias가 없으면 NULL이다. */
    math_engine_unit_t unit; /**< Canonical transform, dimension, flags와 같은 =stable_id=를 가진 embedded unit descriptor다. */
} math_engine_unit_record_t;

Dimension vector에 저장하는 SI base exponent 수(length부터 luminous intensity까지)다.

#define MATH_ENGINE_DIMENSION_COUNT UINT32_C(7)

유효한 dimension exponent의 inclusive 최댓값이다.

#define MATH_ENGINE_DIMENSION_EXPONENT_MAX 127

유효한 dimension exponent의 닫힌 범위다. =-128=은 허용하지 않는다.

#define MATH_ENGINE_DIMENSION_EXPONENT_MIN (-127)

math_engine_prefix_record_t 의 최초 ABI version이다.

#define MATH_ENGINE_PREFIX_RECORD_VERSION_1 UINT32_C(1)

Embedded catalog의 core shard에도 포함되는 unit flag다.

#define MATH_ENGINE_UNIT_FLAG_EMBEDDED_CORE UINT32_C(0x00000002)

현재 version에서 허용하는 unit flag 전체 mask다.

#define MATH_ENGINE_UNIT_FLAG_KNOWN_MASK UINT32_C(0x00000003)

Decimal prefix 적용을 허용하는 linear unit flag다.

#define MATH_ENGINE_UNIT_FLAG_PREFIXABLE UINT32_C(0x00000001)

math_engine_unit_record_t 의 최초 ABI version이다.

#define MATH_ENGINE_UNIT_RECORD_VERSION_1 UINT32_C(1)

math_engine_unit_t 의 최초 ABI version이다.

#define MATH_ENGINE_UNIT_VERSION_1 UINT32_C(1)

SI exponent 범위와 dimension/display-kind 정책을 검증한다.

• 매개변수 dimension: 호출 동안만 읽는 dimension 값.
• 반환: 유효하면 MATH_ENGINE_STATUS_OK. NULL, 알 수 없는 display kind 또는 nonzero SI dimension의 non-PHYSICAL kind면 MATH_ENGINE_STATUS_INVALID_ARGUMENT, exponent -128=이면 =MATH_ENGINE_STATUS_OUT_OF_RANGE.
• Math Engine ownership: dimension=borrowed
• Math Engine nullable: dimension=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_dimension_validate(
    const math_engine_dimension_t* dimension);

SI exponent와 display kind를 모두 포함해 두 dimension을 비교한다.

• 매개변수 left: 호출 동안만 읽는 첫 dimension.
• 매개변수 right: 호출 동안만 읽는 둘째 dimension.
• 매개변수 out_equal: 성공 시 같으면 1, 다르면 0을 받을 caller-owned output.
• 반환: 성공하면 MATH_ENGINE_STATUS_OK. Pointer 또는 dimension 검증 실패 시 해당 status를 반환하고 out_equal 을 보존한다.
• Math Engine ownership: left=borrowed right=borrowed out_equal=caller
• Math Engine nullable: left=false right=false out_equal=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_dimension_equal(
    const math_engine_dimension_t* left,
    const math_engine_dimension_t* right,
    uint32_t* out_equal);

SI exponent를 더하고 display-kind algebra로 dimension 곱셈을 계산한다.

• 매개변수 left: 호출 동안만 읽는 좌항 dimension.
• 매개변수 right: 호출 동안만 읽는 우항 dimension.
• 매개변수 out_dimension: 성공한 합성 dimension을 받을 caller-owned output.
• 반환: 성공하면 MATH_ENGINE_STATUS_OK. Exponent 범위를 넘으면 MATH_ENGINE_STATUS_OVERFLOW, 정의되지 않은 dimensionless kind 조합이면 MATH_ENGINE_STATUS_INVALID_ARGUMENT 이며 실패 시 output을 보존한다.
• Math Engine ownership: left=borrowed right=borrowed out_dimension=caller
• Math Engine nullable: left=false right=false out_dimension=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_dimension_multiply(
    const math_engine_dimension_t* left,
    const math_engine_dimension_t* right,
    math_engine_dimension_t* out_dimension);

좌항 SI exponent에서 우항을 빼고 display-kind algebra로 dimension 나눗셈을 계산한다.

• 매개변수 left: 호출 동안만 읽는 분자 dimension.
• 매개변수 right: 호출 동안만 읽는 분모 dimension.
• 매개변수 out_dimension: 성공한 합성 dimension을 받을 caller-owned output.
• 반환: 성공하면 MATH_ENGINE_STATUS_OK. Exponent 범위를 넘으면 MATH_ENGINE_STATUS_OVERFLOW, 정의되지 않은 kind 조합이면 MATH_ENGINE_STATUS_INVALID_ARGUMENT 이며 실패 시 output을 보존한다.
• Math Engine ownership: left=borrowed right=borrowed out_dimension=caller
• Math Engine nullable: left=false right=false out_dimension=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_dimension_divide(
    const math_engine_dimension_t* left,
    const math_engine_dimension_t* right,
    math_engine_dimension_t* out_dimension);

모든 SI exponent에 정수 지수를 곱한다.

• 매개변수 dimension: 호출 동안만 읽는 밑 dimension.
• 매개변수 power: 적용할 dimensionless 정수 지수.
• 매개변수 out_dimension: 성공한 거듭제곱 dimension을 받을 caller-owned output.
• 반환: 성공하면 MATH_ENGINE_STATUS_OK. Exponent overflow 또는 plane angle 등 non-PHYSICAL kind에 0·1 이외 지수를 적용하면 오류이며 실패 시 output을 보존한다.
• Math Engine ownership: dimension=borrowed out_dimension=caller
• Math Engine nullable: dimension=false out_dimension=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_dimension_power(
    const math_engine_dimension_t* dimension,
    int32_t power,
    math_engine_dimension_t* out_dimension);

Unit의 versioned layout, dimension, flag와 transform field를 검증한다.

• 매개변수 unit: 호출 동안만 읽는 unit descriptor.
• 반환: 유효하면 MATH_ENGINE_STATUS_OK. Size·version 오류는 각각 MATH_ENGINE_STATUS_INVALID_SIZE=·=MATH_ENGINE_STATUS_UNSUPPORTED 이며 unknown flag, non-finite field와 transform별 invariant 위반은 해당 오류 status다.
• Math Engine ownership: unit=borrowed
• Math Engine nullable: unit=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_unit_validate(
    const math_engine_unit_t* unit);

Coherent SI 값을 경유해 같은 dimension의 unit 사이에서 값을 변환한다.

• 매개변수 value: from_unit 으로 표현한 finite 입력값.
• 매개변수 from_unit: 호출 동안만 읽는 입력 unit descriptor.
• 매개변수 to_unit: 호출 동안만 읽는 출력 unit descriptor.
• 매개변수 out_value: 성공 시 to_unit 으로 표현한 값을 받을 caller-owned output.
• 반환: 성공하면 MATH_ENGINE_STATUS_OK. Dimension 불일치·invalid transform, non-finite 입력, logarithmic 범위 또는 표현 overflow면 해당 status를 반환하고 out_value 을 보존한다.
• Math Engine ownership: from_unit=borrowed to_unit=borrowed out_value=caller
• Math Engine nullable: from_unit=false to_unit=false out_value=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_unit_convert_f64(
    double value,
    const math_engine_unit_t* from_unit,
    const math_engine_unit_t* to_unit,
    double* out_value);

Catalog에 있는 decimal prefix를 prefixable linear unit에 적용한다.

• 매개변수 unit: 호출 동안만 읽는 prefixable linear unit.
• 매개변수 prefix: 이 component의 catalog에서 얻은 immutable prefix record.
• 매개변수 out_unit: 성공한 scale과 compound stable ID를 받을 caller-owned output.
• 반환: 성공하면 MATH_ENGINE_STATUS_OK. Catalog record가 아니거나 unit이 prefixable linear가 아니면 MATH_ENGINE_STATUS_INVALID_ARGUMENT, scale overflow면 MATH_ENGINE_STATUS_OVERFLOW 이며 실패 시 output을 보존한다.
• Math Engine ownership: unit=borrowed prefix=borrowed out_unit=caller
• Math Engine nullable: unit=false prefix=false out_unit=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_unit_apply_prefix(
    const math_engine_unit_t* unit,
    const math_engine_prefix_record_t* prefix,
    math_engine_unit_t* out_unit);

두 linear unit의 scale과 dimension을 곱해 compound unit을 만든다.

• 매개변수 left: 호출 동안만 읽는 좌항 linear unit.
• 매개변수 right: 호출 동안만 읽는 우항 linear unit.
• 매개변수 out_unit: 성공한 compound unit을 받을 caller-owned output.
• 반환: 성공하면 MATH_ENGINE_STATUS_OK. Affine·logarithmic unit, invalid dimension 조합 또는 exponent·scale overflow면 해당 status를 반환하고 output을 보존한다.
• Math Engine ownership: left=borrowed right=borrowed out_unit=caller
• Math Engine nullable: left=false right=false out_unit=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_unit_multiply(
    const math_engine_unit_t* left,
    const math_engine_unit_t* right,
    math_engine_unit_t* out_unit);

두 linear unit의 scale과 dimension을 나눠 compound unit을 만든다.

• 매개변수 left: 호출 동안만 읽는 분자 linear unit.
• 매개변수 right: 호출 동안만 읽는 분모 linear unit.
• 매개변수 out_unit: 성공한 compound unit을 받을 caller-owned output.
• 반환: 성공하면 MATH_ENGINE_STATUS_OK. Affine·logarithmic unit, invalid dimension 조합 또는 exponent·scale overflow면 해당 status를 반환하고 output을 보존한다.
• Math Engine ownership: left=borrowed right=borrowed out_unit=caller
• Math Engine nullable: left=false right=false out_unit=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_unit_divide(
    const math_engine_unit_t* left,
    const math_engine_unit_t* right,
    math_engine_unit_t* out_unit);

Linear unit의 scale과 dimension을 정수 거듭제곱한다.

• 매개변수 unit: 호출 동안만 읽는 밑 linear unit.
• 매개변수 power: 적용할 dimensionless 정수 지수.
• 매개변수 out_unit: 성공한 compound unit을 받을 caller-owned output.
• 반환: 성공하면 MATH_ENGINE_STATUS_OK. Non-linear unit, invalid dimension power 또는 scale overflow면 해당 status를 반환하고 output을 보존한다.
• Math Engine ownership: unit=borrowed out_unit=caller
• Math Engine nullable: unit=false out_unit=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_unit_power(
    const math_engine_unit_t* unit,
    int32_t power,
    math_engine_unit_t* out_unit);

Decimal prefix catalog의 항목 수를 반환한다.

• 반환: Exponent -30부터 +30까지 정의된 고정 catalog의 항목 수.
• Math Engine thread_safety: safe

MATH_ENGINE_API size_t math_engine_prefix_catalog_count(void);

Index로 immutable prefix record 하나를 빌린다.

• 매개변수 index: 조회할 zero-based catalog index.
• 반환: 성공하면 process lifetime 동안 유효한 static record pointer, 범위 밖이면 NULL.
• Math Engine ownership: return=static
• Math Engine nullable: return=true
• Math Engine thread_safety: safe

MATH_ENGINE_API const math_engine_prefix_record_t* math_engine_prefix_catalog_at(
    size_t index);

Canonical name, symbol 또는 승인된 UTF-8/ASCII alias로 prefix를 찾는다.

• 매개변수 alias: 호출 동안만 읽는 NUL-terminated 문자열. 첫 64 byte 안에 NUL이 있어야 한다.
• 매개변수 out_record: 성공 시 process-lifetime static record pointer를 받을 caller-owned output.
• 반환: 성공하면 MATH_ENGINE_STATUS_OK. Invalid pointer·unterminated 문자열은 MATH_ENGINE_STATUS_INVALID_ARGUMENT, 미발견은 MATH_ENGINE_STATUS_OUT_OF_RANGE 이며 실패 시 out_record 를 보존한다.
• Math Engine ownership: alias=borrowed out_record=caller
• Math Engine nullable: alias=false out_record=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_prefix_catalog_find(
    const char* alias,
    const math_engine_prefix_record_t** out_record);

현재 compiled full 또는 embedded unit catalog의 항목 수를 반환한다.

• 반환: 현재 build에 포함된 unit record 수.
• Math Engine thread_safety: safe

MATH_ENGINE_API size_t math_engine_unit_catalog_count(void);

Index로 immutable unit record 하나를 빌린다.

• 매개변수 index: 조회할 zero-based catalog index.
• 반환: 성공하면 process lifetime 동안 유효한 static record pointer, 범위 밖이면 NULL.
• Math Engine ownership: return=static
• Math Engine nullable: return=true
• Math Engine thread_safety: safe

MATH_ENGINE_API const math_engine_unit_record_t* math_engine_unit_catalog_at(
    size_t index);

Canonical name, symbol 또는 승인된 alias로 compiled unit을 찾는다.

• 매개변수 alias: 호출 동안만 읽는 NUL-terminated 문자열. 첫 128 byte 안에 NUL이 있어야 한다.
• 매개변수 out_record: 성공 시 process-lifetime static record pointer를 받을 caller-owned output.
• 반환: 성공하면 MATH_ENGINE_STATUS_OK. Invalid pointer·unterminated 문자열은 MATH_ENGINE_STATUS_INVALID_ARGUMENT, 미발견은 MATH_ENGINE_STATUS_OUT_OF_RANGE 이며 실패 시 out_record 를 보존한다.
• Math Engine ownership: alias=borrowed out_record=caller
• Math Engine nullable: alias=false out_record=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_unit_catalog_find(
    const char* alias,
    const math_engine_unit_record_t** out_record);

Stable ID로 compiled unit을 찾는다.

• 매개변수 stable_id: 0이 아닌 unit stable ID.
• 매개변수 out_record: 성공 시 process-lifetime static record pointer를 받을 caller-owned output.
• 반환: 성공하면 MATH_ENGINE_STATUS_OK. ID 0 또는 NULL output은 MATH_ENGINE_STATUS_INVALID_ARGUMENT, 미발견은 MATH_ENGINE_STATUS_OUT_OF_RANGE 이며 실패 시 out_record 를 보존한다.
• Math Engine ownership: out_record=caller
• Math Engine nullable: out_record=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_unit_catalog_find_id(
    uint64_t stable_id,
    const math_engine_unit_record_t** out_record);

Prefix와 compiled unit catalog byte의 안정된 FNV-1a fingerprint를 계산한다.

• 반환: Catalog 내용과 순서를 대표하는 deterministic 64-bit fingerprint.
• Math Engine thread_safety: safe

MATH_ENGINE_API uint64_t math_engine_unit_catalog_fingerprint(void);