You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
A Java 19 library for converting between IEEE 754 binary floating-point numbers and Java's BigDecimal
3
+
A Java 19 library for converting between IEEE 754 binary and decimal floating-point numbers and Java's BigDecimal
4
4
5
5
## Overview
6
6
7
-
This library can convert `java.math.BigDecimal`s into IEEE 754 binary representations. By default, binary16, binary32, binary64, binary128, binary256, and x87's extended precision (binary80) are supported. There are also 3 larger types (binary512, binary1024, binary2048) available, these are, however, most likely impractial for any purpose due to their *extremely* long encoding/decoding times.
7
+
This library can convert `java.math.BigDecimal`s into IEEE 754 binary representations. By default, binary16, binary32, binary64, binary128, binary256, x87's extended precision (binary80), decimal32, decimal64 and decimal128 are supported. There are also 3 larger types (binary512, binary1024, binary2048) available, these are, however, most likely impractial for any purpose due to their *extremely* long encoding/decoding times.
8
8
9
9
## Getting started
10
10
11
-
In order to use the code, you can either [download the jar](https://github.com/Synt4xErr0r4/ieee754-java/releases/download/1.0.0/ieee754-java-1.0.0.jar), or use the Maven dependency:
11
+
In order to use the code, you can either [download the jar](https://github.com/Synt4xErr0r4/ieee754-java/releases/download/2.0.0/ieee754-java-2.0.0.jar), or use the Maven dependency:
12
12
13
13
```xml
14
14
<!-- Repository -->
@@ -23,7 +23,7 @@ In order to use the code, you can either [download the jar](https://github.com/S
23
23
<dependency>
24
24
<groupId>at.syntaxerror</groupId>
25
25
<artifactId>ieee754-java</artifactId>
26
-
<version>1.0.0</version>
26
+
<version>2.0.0</version>
27
27
</dependency>
28
28
```
29
29
@@ -44,13 +44,16 @@ There are several predefined types:
44
44
-`Binary512`*
45
45
-`Binary1024`*
46
46
-`Binary2048`*
47
+
-`Decimal32`
48
+
-`Decimal64`
49
+
-`Decimal128`
47
50
48
51
\* These types are for demonstration purposes only, their parameters do not follow any official IEEE 754 standard, encoding/decoding might take *very* long and result might not be accurate. Use with caution.
49
52
50
53
For any of the predefined types, there is a static field called `FACTORY`, which is used to create classes of their respective type:
51
54
52
55
-`create(int signum, BinaryType type)`
53
-
-`create(int signum, BigDecimal value)`
56
+
-`create(int signum, BigDecimal value)` (only useful for signed zeros)
54
57
-`create(BigDecimal value)`
55
58
-`create(Number value)`
56
59
@@ -74,7 +77,7 @@ import java.math.BigInteger;
74
77
BigInteger bin = value.encode();
75
78
```
76
79
77
-
The binary representation can also be decoded. The `BinaryCodec` class, accessible via `Binary32`'s `CODEC` field, provides the method `decode`:
80
+
The binary representation can also be decoded. The `FloatingCodec` class, accessible via `Binary32`'s `CODEC` field, provides the method `decode`:
78
81
79
82
```java
80
83
Binary32 decoded =Binary32.CODEC.decode(bin);
@@ -86,13 +89,44 @@ The value can then be retrieved for further computations as a `BigDecimal` via t
86
89
BigDecimal bigdec = decoded.getBigDecimal();
87
90
```
88
91
89
-
This is applicable to all predefined types; Also, any class inheriting from `Binary<T>` has access to various helper methods, which are listed in the [JavaDoc](https://javadoc.syntaxerror.at/ieee754-java/latest/ieee754java/at/syntaxerror/ieee754/binary/Binary.html).
92
+
This is applicable to all predefined types; Also, any class inheriting from `Floating<T>` (or its subclasses `Binary<T>` and `Decimal<T>`) has access to various helper methods, which are listed in the [JavaDoc](https://javadoc.syntaxerror.at/ieee754-java/latest/ieee754java/at/syntaxerror/ieee754/Floating.html).
93
+
94
+
### Decimal Encoding
95
+
96
+
There are two ways IEEE 754 decimal floating-point numbers can be encoded:
97
+
98
+
- BID (binary integer decimal) format
99
+
- DPD (densly packed decimal) format
100
+
101
+
Both formats encode the same range of numbers.
102
+
103
+
The `DecimalCodec<T>` class also provides separate encoding/decoding methods for the two modes:
104
+
105
+
-`encodeBID(T value)`
106
+
-`encodeDPD(T value)`
107
+
-`decodeBID(BigInteger value)`
108
+
-`decodeDPD(BigInteger value)`
109
+
110
+
Similar methods are available in `Decimal<T>`:
111
+
112
+
-`encodeBID()`
113
+
-`encodeDPD()`
114
+
115
+
Methods that do not have a suffix (`BID` or `DPD`) call one of these methods depending on the default mode.
116
+
By default, `BID` is used.
117
+
This can be changed by settings the `DEFAULT_CODING` field in the `Decimal` class
118
+
to either `DecimalCoding.BINARY_INTEGER_DECIMAL` or `DecimalCoding.DENSLY_PACKED_DECIMAL`.
90
119
91
120
### Custom Types
92
121
93
122
You can also create custom floating-point types:
94
123
95
-
When extending `Binary<T>`, you need to implement the method `getCodec`, which returns a `BinaryCodec<T>`. This codec can be created by using its constructor, which takes the number of exponent bits, mantissa bits, whether there is an implicit bit, and a `BinaryFactory<T>`. The factory is an interface where you need to implement constructors for your new class.
124
+
When extending `Floating<T>` (or the subclass `Binary<T>` or `Decimal<T>`), you need to implement the method `getCodec`, which returns a `FloatingCodec<T>`. The `FloatingCodec<T>`, however, is an abstract class. If you want to implement a `Binary`-like codec, use the `BinaryCodec<T>` class instead. For `Decimal`-like codecs, `DecimalCodec<T>` exists. These codecs can be created by using their constructors.
125
+
126
+
The `BinaryCodec<T>` constructor takes the number of exponent bits, significand bits, whether there is an implicit bit and a `FloatingFactory<T>`.
127
+
The `DecimalCodec<T>` constructor takes the number of combination field bits, significand bits and a `FloatingFactory<T>`
128
+
129
+
The factory is an interface where you need to implement constructors for your new class.
96
130
97
131
Take a look at the various predefined types to see how they are implemented.
0 commit comments