Merge pull request #2 from Synt4xErr0r4/rounding

Added support for different rouding modes (version 2.1.0)

Author: Synt4xErr0r4

README.md

@@ -8,7 +8,7 @@ This library can convert `java.math.BigDecimal`s into IEEE 754 binary representa
 
 ## Getting started
 
-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:
+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.1.0.jar), or use the Maven dependency:
 
 ```xml
 <!-- Repository -->
@@ -23,7 +23,7 @@ In order to use the code, you can either [download the jar](https://github.com/S
 <dependency>
   <groupId>at.syntaxerror</groupId>
   <artifactId>ieee754-java</artifactId>
-  <version>2.0.0</version>
+  <version>2.1.0</version>
 </dependency>
 ```
 
@@ -67,6 +67,8 @@ import at.syntaxerror.ieee754.binary.Binary32;
 Binary32 value = Binary32.FACTORY.create(3.14159);
 ```
 
+*Note: using native `float` and `double` might lead to inaccurate results due to rounding errors. It is recommended to use `BigDecimal` instead.*
+
 Now, the function `encode` in `Binary32` can be used to get the number's binary representation:
 
 ```java
@@ -89,7 +91,7 @@ The value can then be retrieved for further computations as a `BigDecimal` via t
 BigDecimal bigdec = decoded.getBigDecimal();
 ```
 
-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).
+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).
 
 ### Decimal Encoding
 
@@ -132,13 +134,50 @@ Take a look at the various predefined types to see how they are implemented.
 
 ### Rounding
 
-Not all numbers can be encoded with full precision. In such cases, rounding is performed.
-The rounding mode used in this library is the default rounding mode for IEEE 754 floating points: round to nearest, ties to even.
+Some numbers cannot be encoded with full precision. In such cases, rounding is performed.
+
+There are five IEEE 754 rounding modes:
+
+- `TIES_EVEN`: round to nearest, ties to even
+  - rounds to the nearest value
+  - if the number falls midway, it is rounded to the nearest even value.
+- `TIES_AWAY`: round to nearest, ties away from 0
+  - rounds to the nearest value
+  - if the number falls midway, it is rounded to the nearest value above (positive numbers) or below (negative numbers).
+- `TOWARD_ZERO`: round toward 0 (aka. truncating)
+- `TOWARD_POSITIVE`: round toward +∞ (aka. rounding up, ceiling)
+- `TOWARD_NEGATIVE`: round toward -∞ (aka. rounding down, floor)
+
+The default rounding mode used for encoding is `TIES_EVEN`. This can be changed by altering the `DEFAULT_ROUNDING` field
+in the `Rounding` class, e.g.:
+
+```java
+import at.syntaxerror.ieee754.rounding.Rounding;
+
+/* ... */
+
+Rounding.DEFAULT_ROUNDING = Rounding.TOWARD_ZERO;
+```
 
 ## Documentation
 
 The JavaDoc for the latest version can be found [here](https://javadoc.syntaxerror.at/ieee754-java/latest).
 
+## Changelog
+
+### 2.1.0
+
+- Added support for different rounding modes
+- Improved performance for very small numbers
+
+### 2.0.0
+
+- Added decimal floating-point formats `Decimal32`, `Decimal64` and `Decimal128`
+
+### 1.0.0
+
+- Added binary floating-point formats `Binary16`, `Binary32`, `Binary64`, `Binary80`, `Binary128`, `Binary256`, `Binary512`, `Binary1024` and `Binary2048`
+
 ## Dependencies
 
 This project makes use of the following dependencies:

pom.xml

@@ -2,7 +2,7 @@
   <modelVersion>4.0.0</modelVersion>
   <groupId>at.syntaxerror</groupId>
   <artifactId>ieee754-java</artifactId>
-  <version>2.0.0</version>
+  <version>2.1.0</version>
   <name>IEEE754-Java</name>
   <description>A Java 19 library for converting between IEEE 754 binary and decimal and BigDecimal</description>
   <licenses>

src/main/java/at/syntaxerror/ieee754/Floating.java

@@ -253,7 +253,7 @@ public int intValue() {
 		if(type != FloatingType.FINITE)
 			throw new UnsupportedOperationException("Cannot convert non-finite number to integer");
 
-		return (int) intValue();
+		return (int) longValue();
 	}
 
 	/** {@inheritDoc} */

src/main/java/at/syntaxerror/ieee754/binary/BinaryCodec.java

@@ -33,6 +33,7 @@
 import at.syntaxerror.ieee754.FloatingCodec;
 import at.syntaxerror.ieee754.FloatingFactory;
 import at.syntaxerror.ieee754.FloatingType;
+import at.syntaxerror.ieee754.rounding.Rounding;
 import ch.obermuhlner.math.big.BigDecimalMath;
 import lombok.NonNull;
 
@@ -47,6 +48,7 @@
 public final class BinaryCodec<T extends Binary<T>> extends FloatingCodec<T> {
 
 	private static final MathContext FLOOR = new MathContext(0, RoundingMode.FLOOR);
+	private static final MathContext CONTEXT = new MathContext(800);
 
 	private static final BigDecimal TWO = BigDecimal.valueOf(2);
 	private static final BigDecimal LOG10_2 = BigDecimalMath.log10(TWO, new MathContext(604, RoundingMode.HALF_EVEN));
@@ -163,7 +165,8 @@ public BigInteger encode(T value) {
 		BigInteger significand = bigdec.toBigInteger();
 
 		// strip integer part
-		BigDecimal fraction = bigdec.subtract(new BigDecimal(significand)).abs();
+		BigDecimal fraction = bigdec.subtract(new BigDecimal(significand))
+			.abs().stripTrailingZeros();
 
 		// remove sign
 		significand = significand.abs();
@@ -178,6 +181,45 @@ public BigInteger encode(T value) {
 		final int off = getOffset();
 		final int eMin = getExponentRange().getKey();
 
+		boolean requireRounding = false;
+		boolean guard = false;
+		boolean round = false;
+		boolean sticky = false;
+		
+		if(fraction.compareTo(BigDecimal.ZERO) != 0) {
+			// skip leading zeros. this heavily improves the performance for larger types
+			
+			zeros = BigDecimalMath.log2(
+				BigDecimalMath.reciprocal(fraction, CONTEXT),
+				CONTEXT
+			).setScale(0, RoundingMode.CEILING).intValue() - 1;
+			
+			fraction = fraction.multiply(pow2(zeros)).stripTrailingZeros();
+
+			significand = significand.shiftLeft(zeros);
+			
+			int bitCount = significand.bitLength();
+			int threshold = this.significand + off;
+			
+			if(zeros > -eMin)
+				bitCount += zeros + eMin;
+			
+			if(bitCount > threshold) {
+				requireRounding = true;
+				
+				fraction = fraction.multiply(BigDecimal.TWO);
+
+				round = fraction.intValue() != 0;
+				
+				if(round)
+					fraction = fraction.subtract(BigDecimal.ONE);
+				
+				sticky = fraction.compareTo(BigDecimal.ZERO) != 0;
+				
+				fraction = BigDecimal.ZERO;
+			}
+		}
+		
 		/* - left-shift the significand by 1
 		 * - multiply the fraction by two
 		 * - bit-or the significand with the integer part of result (0 or 1)
@@ -204,30 +246,11 @@ public BigInteger encode(T value) {
 
 			// max number of bits reached
 			if(significandLength > this.significand + off) {
+				requireRounding = true;
 
-				// Round to nearest, ties to even
-				
-				boolean guard = significand.testBit(0);
-				boolean round = integerPart == 1;
-				boolean sticky = fraction.compareTo(BigDecimal.ONE) != 0;
-				
-				if((guard && round) || (round && sticky)) { // round up
-					int bits = significand.bitLength();
-					
-					significand = significand.add(BigInteger.ONE);
-
-					if(bits != significand.bitLength()) { // overflow occured, adjust exponent
-						
-						significand = significand.clearBit(bits); // clear overflown bit					
-						++exp;
-						
-						// if exponent is all 1s now, return Infinity
-						if(exp == mask(this.exponent).intValue())
-							return sign == -1
-								? getNegativeInfinity()
-								: getPositiveInfinity();
-					}
-				}
+				guard = significand.testBit(0);
+				round = integerPart == 1;
+				sticky = fraction.compareTo(BigDecimal.ONE) != 0;
 
 				break;
 			}
@@ -242,6 +265,25 @@ else if(bitCount == 0)
 				++zeros;
 		}
 
+		if(requireRounding && Rounding.DEFAULT_ROUNDING.roundBinary(sign == -1, guard, round, sticky)) {
+			// round up
+			int bits = significand.bitLength();
+			
+			significand = significand.add(BigInteger.ONE);
+
+			if(bits != significand.bitLength()) { // overflow occured, adjust exponent
+				
+				significand = significand.clearBit(bits); // clear overflown bit					
+				++exp;
+				
+				// if exponent is all 1s now, return Infinity
+				if(exp == mask(this.exponent).intValue())
+					return sign == -1
+						? getNegativeInfinity()
+						: getPositiveInfinity();
+			}
+		}
+		
 		int len = significand.bitLength();
 
 		// fix exponent if < 1
@@ -357,9 +399,12 @@ private BigDecimal pow2(int n) {
 			return BigDecimal.ONE;
 
 		if(n < 0)
-			return BigDecimal.ONE.divide(pow2(-n));
+			return BigDecimalMath.reciprocal(pow2(-n), CONTEXT);
 
-		return BigDecimal.TWO.pow(n);
+		return new BigDecimal(
+			BigInteger.ONE.shiftLeft(n),
+			0
+		).stripTrailingZeros();
 	}
 
 	// computes 2^(e_min-1)

src/main/java/at/syntaxerror/ieee754/decimal/DecimalCodec.java

@@ -24,7 +24,6 @@
 
 import java.math.BigDecimal;
 import java.math.BigInteger;
-import java.math.RoundingMode;
 import java.util.HashMap;
 import java.util.Map;
 import java.util.function.Supplier;
@@ -33,6 +32,7 @@
 import at.syntaxerror.ieee754.FloatingFactory;
 import at.syntaxerror.ieee754.FloatingType;
 import at.syntaxerror.ieee754.binary.Binary;
+import at.syntaxerror.ieee754.rounding.Rounding;
 import lombok.NonNull;
 
 /**
@@ -359,12 +359,14 @@ else if(scale < 2 - maxExp - max) {
 
 	// truncate the n least significant digits of the value
 	private BigDecimal truncateLeastSignificant(BigDecimal value, int n) {
+		BigDecimal precise = new BigDecimal(
+			value.unscaledValue()
+			.divide(BigInteger.TEN.pow(n - 1))
+		).divide(BigDecimal.TEN);
+		
 		return new BigDecimal(
-			new BigDecimal(
-				value.unscaledValue()
-					.divide(BigInteger.TEN.pow(n - 1))
-			).divide(BigDecimal.TEN)
-				.setScale(0, RoundingMode.HALF_EVEN)
+			Rounding.DEFAULT_ROUNDING
+				.roundDecimal(precise)
 				.toBigInteger(),
 			value.scale() - n
 		).stripTrailingZeros();