Decimal-Java는 java.math.BigDecimal을 IEEE-754r로 변환하고 다시 변환하는 라이브러리입니다.

Source: Hacker News

decimal-java

Decimal-java은 java.math.BigDecimal을 IEEE‑754r (IEEE‑754‑2008) 10진수 바이트 표현으로 변환하고, 그 반대로 변환하는 라이브러리입니다.

Maven

Maven에서 decimal-java를 가져옵니다:

<dependency>
    <groupId>org.firebirdsql</groupId>
    <artifactId>decimal-java</artifactId>
    <version>2.0.1</version>
</dependency>

또는 다음 좌표를 사용합니다:

org.firebirdsql
decimal-java
2.0.1

License

이 라이브러리는 MIT license 하에 라이선스가 부여됩니다; LICENSE.md도 참조하십시오.

Status

API는 안정적이며 변경될 예정이 없습니다.

• Version 2.0.0 이상은 Java 17 이상이 필요하며 모듈 이름 org.firebirdsql.decimal 로 모듈화되었습니다.
• Version 1.0.2는 Java 7 이상이 필요하고 자동 모듈 이름 org.firebirdsql.decimal 를 선언합니다.

목표

이 라이브러리는 java.math.BigDecimal와 IEEE‑754r 소수점 형식 간의 변환을 제공합니다. 구체적으로 지원되는 바이트 표현은 다음과 같습니다:

• decimal32
• decimal64
• decimal128

다른 형식(임의 정밀도 소수점)은 계획되지 않았습니다.

비목표

라이브러리에는 소수값에 대한 수학 연산이 포함되어 있지 않습니다. 산술 연산을 위해서는 BigDecimal을 MathContext.DECIMAL128, MathContext.DECIMAL64, 또는 MathContext.DECIMAL32와 함께 사용하십시오.

사용법

전체 Javadoc (최신 태그 릴리스):

Decimal32 디코딩

byte[] bytes = {(byte) 0xc7, (byte) 0xf4, (byte) 0xd2, (byte) 0xe7};
Decimal32 decimal32 = Decimal32.parseBytes(bytes);
BigDecimal bigDecimal = decimal32.toBigDecimal();
assertEquals(new BigDecimal("-1.234567E+96"), bigDecimal);

toBigDecimal() 은 값이 무한대이거나 NaN인 경우 DecimalInconvertibleException을 발생시킵니다; 예외에는 실제 타입과 부호가 포함됩니다.

Decimal32 인코딩

BigDecimal bigDecimal = new BigDecimal("-7.50E-7");
Decimal32 decimal32 = Decimal32.valueOf(bigDecimal);
byte[] bytes = decimal32.toBytes();
assertArrayEquals(new byte[] {(byte) 0xa1, (byte) 0xc0, 0x03, (byte) 0xd0}, bytes);

BigDecimal 이 Decimal32에 맞지 않을 경우 반올림이 적용됩니다; 오버플로우는 무한대로 반올림됩니다. 오버플로우를 거부하려면:

Decimal32 decimal32 = Decimal32.valueOf(bigDecimal, OverflowHandling.THROW_EXCEPTION);
byte[] bytes = decimal32.toBytes();
assertArrayEquals(new byte[] {(byte) 0xa1, (byte) 0xc0, 0x03, (byte) 0xd0}, bytes);

Decimal64 및 Decimal128에 대해서도 변환 방식은 동일합니다.

사용 가능한 valueOf 오버로드

• BigDecimal
• BigInteger (라운딩 시 DecimalOverflowException을 발생시키는 valueOfExact(BigInteger) 포함)
• String
• double

부모 클래스 Decimal ( Decimal32, Decimal64, Decimal128 의 슈퍼클래스) 역시 10진수 타입 간 변환을 제공합니다.

변환 메서드

• toBytes()
• toBigDecimal() – 무한대/NaN에 대해 DecimalInconvertibleException 발생
• toString()
• doubleValue()
• toDecimal(Class) 및 toDecimal(Class, OverflowHandling)

BigInteger 를 얻으려면 toBigDecimal().toBigInteger() 를 사용하십시오. 특히 Decimal128 같은 큰 값은 상당한 메모리를 사용할 수 있음을 유념하세요.

배경

Firebird 4.0은 프로토콜에서 decimal64와 decimal128를 사용하여 SQL DECFLOAT 타입(정밀도 16 및 34자리)을 도입했습니다. Firebird JDBC 드라이버인 Jaybird는 이러한 포맷에 대한 지원이 필요했습니다. 적합한 라이브러리를 찾지 못해 decimal-java를 별도 프로젝트로 만들어 배포했습니다. Jaybird는 Maven/Gradle 환경이 아닌 경우 추가 의존성을 피하기 위해 라이브러리 복사본을 포함합니다.

References

• 일반 십진수 연산
• 십진수 연산 인코딩
• 밀집 십진수 인코딩 요약
• decNumber 라이브러리
• Firebird 4.0 릴리스 노트

SPDX-License-Identifier: MIT