{"id":19923297,"url":"https://github.com/firebirdsql/decimal-java","last_synced_at":"2025-05-03T07:31:03.613Z","repository":{"id":73981580,"uuid":"115275715","full_name":"FirebirdSQL/decimal-java","owner":"FirebirdSQL","description":"Java library to encode and decode IEEE-754 decimals","archived":false,"fork":false,"pushed_at":"2024-10-01T09:56:47.000Z","size":862,"stargazers_count":12,"open_issues_count":1,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-07T13:11:09.589Z","etag":null,"topics":["bigdecimal","decimal","decimal128","decimal32","decimal64","firebird","firebirdsql","ieee-754","ieee754","java"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FirebirdSQL.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null},"funding":{"github":"mrotteveel","custom":"https://firebirdsql.org/en/donate/"}},"created_at":"2017-12-24T16:41:49.000Z","updated_at":"2025-02-13T07:54:11.000Z","dependencies_parsed_at":"2023-12-15T15:50:54.936Z","dependency_job_id":null,"html_url":"https://github.com/FirebirdSQL/decimal-java","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FirebirdSQL%2Fdecimal-java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FirebirdSQL%2Fdecimal-java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FirebirdSQL%2Fdecimal-java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FirebirdSQL%2Fdecimal-java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FirebirdSQL","download_url":"https://codeload.github.com/FirebirdSQL/decimal-java/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252156832,"owners_count":21703362,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bigdecimal","decimal","decimal128","decimal32","decimal64","firebird","firebirdsql","ieee-754","ieee754","java"],"created_at":"2024-11-12T22:13:42.692Z","updated_at":"2025-05-03T07:31:03.046Z","avatar_url":"https://github.com/FirebirdSQL.png","language":"Java","readme":"decimal-java\n============\n\nDecimal-java is a library to convert `java.math.BigDecimal` to and from \nIEEE-754r (IEEE-754-2008) decimal byte representations.\n\n[![Java CI with Gradle](https://github.com/FirebirdSQL/decimal-java/actions/workflows/gradle.yml/badge.svg?branch=master)](https://github.com/FirebirdSQL/decimal-java/actions/workflows/gradle.yml?query=branch%3Amaster)\n[![MavenCentral](https://maven-badges.herokuapp.com/maven-central/org.firebirdsql/decimal-java/badge.svg)](https://maven-badges.herokuapp.com/maven-central/org.firebirdsql/decimal-java/)\n\nMaven\n-----\n\nGet decimal-java from Maven:\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eorg.firebirdsql\u003c/groupId\u003e\n    \u003cartifactId\u003edecimal-java\u003c/artifactId\u003e\n    \u003cversion\u003e2.0.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nLicense\n-------\n\nThis library is licensed under the [MIT license](https://opensource.org/licenses/MIT),\nsee also LICENSE.md.\n\nStatus\n------\n\nThe API is stable and is not expected to change.\n\nVersion 2.0.0 and higher require Java 17 or higher and is modularized with\nmodule name `org.firebirdsql.decimal`. Version 1.0.2 requires Java 7 or higher,\nand declares the automatic module name `org.firebirdsql.decimal`.\n\nGoals\n-----\n\nThis library provides conversion between `java.math.BigDecimal` and  IEEE-754r \ndecimal formats.\n\nSpecifically supported are byte representations of:\n\n- decimal32\n- decimal64\n- decimal128\n\nOther formats (arbitrary precision decimal) are not planned to be supported.\n\nNon-goals\n---------\n\nThis library explicitly does not include mathematical operations on decimal.\nAs an alternative, consider using `BigDecimal` with `MathContext.DECIMAL128`,\n`MathContext.DECIMAL64`, or `MathContext.DECIMAL32`.\n\nUsage\n-----\n\nFor full javadoc (of latest tagged release), see https://firebirdsql.github.io/decimal-java/javadoc/\n\nDecoding a 4-byte Decimal32 to a `java.math.BigDecimal`:\n\n```java\nbyte[] bytes = {(byte) 0xc7, (byte) 0xf4, (byte) 0xd2, (byte) 0xe7};\nDecimal32 decimal32 = Decimal32.parseBytes(bytes);\nBigDecimal bigDecimal = decimal32.toBigDecimal();\nassertEquals(new BigDecimal(\"-1.234567E+96\"), bigDecimal);\n```\n\nThe method `toBigDecimal` throws `DecimalInconvertibleException` if the decimal\nvalue is an infinity or NaN value. The actual type and sign can be obtained from\nthe exception.\n\nEncoding a `java.math.BigDecimal` to Decimal32 byte array:\n\n```java\nBigDecimal bigDecimal = new BigDecimal(\"-7.50E-7\");\nDecimal32 decimal32 = Decimal32.valueOf(bigDecimal);\nbyte[] bytes = decimal32.toBytes();\nassertArrayEquals(new byte[] {(byte) 0xa1, (byte) 0xc0, 0x03, (byte) 0xd0}, bytes);\n```\n\nThis will apply rounding if `bigDecimal` value doesn't fit a Decimal32, and\noverflow will 'round' to infinity.\n\nIf overflow to infinity is unwanted, then use:\n\n```java\nBigDecimal bigDecimal = new BigDecimal(\"-7.50E-7\");\nDecimal32 decimal32 = Decimal32.valueOf(bigDecimal, OverflowHandling.THROW_EXCEPTION);\nbyte[] bytes = decimal32.toBytes();\nassertArrayEquals(new byte[] {(byte) 0xa1, (byte) 0xc0, 0x03, (byte) 0xd0}, bytes);\n```\n\nConversion works the same for `Decimal64` and `Decimal128`.\n\nThe `valueOf` methods exists for:\n\n- `BigDecimal`\n- `BigInteger`\n  - In addition, there is `valueOfExact(BigInteger)` which throws \n `DecimalOverflowException` if the `BigInteger` needs to be rounded to fit the\n target decimal type.\n- `String`\n- `double`\n- `Decimal` (parent class of `Decimal32`, `Decimal64` and `Decimal128`) to allow\nconversion between decimal types\n\nThe `valueOf` methods will round values to fit the target decimal type, and -\ndepending on the specified overflow handling - will either return +/- infinity\nor throw an exception on overflow.\n\nConversion to a type is provided by:\n\n- `toBytes()`\n- `toBigDecimal()` - will throw `DecimalInconvertibleException` if the value is\nan infinity or NaN value\n- `toString()`\n- `doubleValue()`\n- `toDecimal(Class)` and `toDecimal(Class, OverflowHandling)`\n\nTo obtain a `BigInteger`, use `toBigDecimal().toBigInteger()` but be aware that \nlarge values (especially of `Decimal128`) can result in significant memory use. \n\nBackground\n----------\n\nThe reason this library exists is that [Firebird](https://www.firebirdsql.org/) \nversion 4.0 added support for the SQL `DECFLOAT` type (with a precision of 16 \nand 34 digits) using _decimal64_ and _decimal128_ in the protocol, and this \nsupport needed to be added to [Jaybird](https://github.com/FirebirdSQL/jaybird), \nthe Firebird JDBC driver.\n\nAs I was unable to find an existing library for this (maybe my Google-fu is\nlacking though), I created one. As I believe others may have similar needs, I \ndecided to release it as a separate library.\n\nI have tried to keep this library generically usable, but I'm sure this \n_raison d'être_ has informed a number of design and implementation decisions. \nPull requests and suggestions for improvements are welcome.\n\nJaybird does not directly depend on this library, but instead contains a copy to\nreduce the number of dependencies. External dependencies for JDBC drivers are\nan annoyance in non-Maven/Gradle environments.\n\nReferences\n----------\n\n-   [General Decimal Arithmetic](http://speleotrove.com/decimal/)\n    -   [Decimal Arithmetic Encodings](http://speleotrove.com/decimal/decbits.html)\n    -   [A Summary of Densely Packed Decimal encoding](http://speleotrove.com/decimal/DPDecimal.html)\n    -   [The decNumber Library](http://speleotrove.com/decimal/decnumber.html)\n-   [Firebird 4.0 Release Notes](https://www.firebirdsql.org/file/documentation/release_notes/html/en/4_0/rlsnotes40.html)\n\nSPDX-License-Identifier: MIT ","funding_links":["https://github.com/sponsors/mrotteveel","https://firebirdsql.org/en/donate/"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffirebirdsql%2Fdecimal-java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffirebirdsql%2Fdecimal-java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffirebirdsql%2Fdecimal-java/lists"}