Source code
package com.google.common.math;
import static com.google.common.base.Preconditions.checkArgument;
import static java.lang.Double.MAX_EXPONENT;
import static java.lang.Double.MIN_EXPONENT;
import static java.lang.Double.POSITIVE_INFINITY;
import static java.lang.Double.doubleToRawLongBits;
import static java.lang.Double.isNaN;
import static java.lang.Double.longBitsToDouble;
import static java.lang.Math.getExponent;
import static java.lang.Math.max;
import com.google.common.annotations.GwtIncompatible;
import com.google.common.annotations.VisibleForTesting;
import java.math.BigInteger;
/**
* Utilities for {@code double} primitives.
*
* @author Louis Wasserman
*/
@GwtIncompatible
final class DoubleUtils {
private DoubleUtils() {}
// The mask for the significand, according to the {@link
// Double#doubleToRawLongBits(double)} spec.
static final long SIGNIFICAND_MASK = 0x000fffffffffffffL;
// The mask for the exponent, according to the {@link
// Double#doubleToRawLongBits(double)} spec.
static final long EXPONENT_MASK = 0x7ff0000000000000L;
// The mask for the sign, according to the {@link
// Double#doubleToRawLongBits(double)} spec.
static final long SIGN_MASK = 0x8000000000000000L;
static final int SIGNIFICAND_BITS = 52;
static final int EXPONENT_BIAS = 1023;
/** The implicit 1 bit that is omitted in significands of normal doubles. */
static final long IMPLICIT_BIT = SIGNIFICAND_MASK + 1;
static long getSignificand(double d) {
checkArgument(isFinite(d), "not a normal value");
int exponent = getExponent(d);
long bits = doubleToRawLongBits(d);
bits &= SIGNIFICAND_MASK;
return (exponent == MIN_EXPONENT - 1) ? bits << 1 : bits | IMPLICIT_BIT;
}
static boolean isFinite(double d) {
return getExponent(d) <= MAX_EXPONENT;
}
static boolean isNormal(double d) {
return getExponent(d) >= MIN_EXPONENT;
}
/*
* Returns x scaled by a power of 2 such that it is in the range [1, 2). Assumes x is positive,
* normal, and finite.
*/
static double scaleNormalize(double x) {
long significand = doubleToRawLongBits(x) & SIGNIFICAND_MASK;
return longBitsToDouble(significand | ONE_BITS);
}
static double bigToDouble(BigInteger x) {
// This is an extremely fast implementation of BigInteger.doubleValue(). JDK patch pending.
BigInteger absX = x.abs();
int exponent = absX.bitLength() - 1;
// exponent == floor(log2(abs(x)))
if (exponent < Long.SIZE - 1) {
return x.longValue();
} else if (exponent > MAX_EXPONENT) {
return x.signum() * POSITIVE_INFINITY;
}
/*
* We need the top SIGNIFICAND_BITS + 1 bits, including the "implicit" one bit. To make rounding
* easier, we pick out the top SIGNIFICAND_BITS + 2 bits, so we have one to help us round up or
* down. twiceSignifFloor will contain the top SIGNIFICAND_BITS + 2 bits, and signifFloor the
* top SIGNIFICAND_BITS + 1.
*
* It helps to consider the real number signif = absX * 2^(SIGNIFICAND_BITS - exponent).
*/
int shift = exponent - SIGNIFICAND_BITS - 1;
long twiceSignifFloor = absX.shiftRight(shift).longValue();
long signifFloor = twiceSignifFloor >> 1;
signifFloor &= SIGNIFICAND_MASK; // remove the implied bit
/*
* We round up if either the fractional part of signif is strictly greater than 0.5 (which is
* true if the 0.5 bit is set and any lower bit is set), or if the fractional part of signif is
* >= 0.5 and signifFloor is odd (which is true if both the 0.5 bit and the 1 bit are set).
*/
boolean increment =
(twiceSignifFloor & 1) != 0 && ((signifFloor & 1) != 0 || absX.getLowestSetBit() < shift);
long signifRounded = increment ? signifFloor + 1 : signifFloor;
long bits = (long) (exponent + EXPONENT_BIAS) << SIGNIFICAND_BITS;
bits += signifRounded;
/*
* If signifRounded == 2^53, we'd need to set all of the significand bits to zero and add 1 to
* the exponent. This is exactly the behavior we get from just adding signifRounded to bits
* directly. If the exponent is MAX_DOUBLE_EXPONENT, we round up (correctly) to
* Double.POSITIVE_INFINITY.
*/
bits |= x.signum() & SIGN_MASK;
return longBitsToDouble(bits);
}
/** Returns its argument if it is non-negative, zero if it is negative. */
static double ensureNonNegative(double value) {
checkArgument(!isNaN(value));
return max(value, 0.0);
}
@VisibleForTesting static final long ONE_BITS = 0x3ff0000000000000L;
}
Run 1
The code demonstrates strong readability through clear organization: constants are grouped with documented purposes, methods follow a logical flow, and there is a good balance of comments explaining complex logic (like the bit manipulation in bigToDouble) without over-commenting simple operations. Nesting is minimal — the deepest logic in bigToDouble uses early returns and clear conditional blocks, avoiding unnecessary indentation. Intent is generally clear from method and variable names (e.g., getSignificand, isFinite, isNormal), though the bit-level operations in bigToDouble require domain knowledge. Code length is appropriate for the functionality; no obvious redundancy. Action granularity is mostly one action per line, though some dense lines (e.g., the boolean increment expression) could be split for clarity. Reading flow is natural, moving from simple utilities to more complex conversions. Deductions stem from the inherent complexity of low-level floating-point bit handling and a few slightly terse comment blocks.
Run 2
The code is generally well-structured with clear constants, helper methods, and logical organization. It avoids deep nesting and keeps most expressions concise. However, the `bigToDouble` method contains dense bit-manipulation logic with lengthy inline comments that, while helpful, make the flow harder to follow. Some lines combine multiple operations, and the use of magic numbers/bit masks requires domain knowledge. The reading flow is reasonable but interrupted by complex rounding logic.
Run 3
The code is highly readable due to its clear structure, consistent formatting, and well-documented constants and methods. Logical grouping of constants at the top aids understanding. Nesting is minimal, keeping the flow flat and straightforward. The intent of each utility method is clear from its name and Javadoc comments. Action granularity is good—each line performs a single, focused operation, particularly in the complex `bigToDouble` method. However, that method's bit-manipulation logic with long comments is inherently complex and could still be challenging for less experienced readers. The reading flow is natural and top-down. Minor improvement could come from extracting parts of `bigToDouble` into smaller helper methods, but overall, it is excellent.
Run 1
Code Structure: Well-organized utility class with focused methods and named constants, though ONE_BITS is separated from related constants. Nesting: Shallow conditionals and early returns keep control flow simple. Clarity of intent: Descriptive method names and detailed comments explain floating-point operations, but abbreviated variables and dense bitwise rounding expressions require specialized knowledge. Code length: Appropriately concise implementation; lengthy comments largely justify themselves by explaining numerical subtleties. Action granularity: Statements generally perform one action per line, with only a few expressions combining several logical operations. Reading flow: Consistent formatting and a logical progression support easy scanning, although bigToDouble requires careful reading and the 'not a normal value' validation message does not precisely describe its finite-value check.
Run 2
Code Structure: Logically organized utility methods and named constants provide clear separation of responsibilities, although ONE_BITS is declared away from related constants. Nesting: Shallow conditionals and early returns keep control flow straightforward. Clarity of intent: Descriptive method names and detailed comments explain floating-point operations, but abbreviated variables and dense bitwise rounding logic require specialist knowledge. Code length: Mostly concise; the longer conversion method and comments are justified by algorithmic complexity. Action granularity: Statements generally perform one action per line, though the rounding condition combines several tests. Reading flow: Consistent formatting and sequential calculation steps support natural reading, with minor friction from compressed import spacing and technically demanding expressions.
Run 3
Code Structure: Well-organized utility class with focused methods and named constants, though ONE_BITS appears after its use rather than alongside related constants. Nesting: Shallow conditionals and early returns keep control flow simple. Clarity of intent: Descriptive method names and detailed comments explain specialized floating-point operations, but abbreviated variables and dense bitwise rounding expressions require careful reading. Code length: Appropriately concise for the mathematical complexity; longer comments provide useful context rather than unnecessary verbosity. Action granularity: Statements generally perform one action per line, although some expressions combine several bitwise and logical operations. Reading flow: Methods progress naturally from extracting properties to normalization and conversion, with comments guiding the complex conversion algorithm. Minor inconsistencies, such as the 'not a normal value' message for a finiteness check, slightly weaken clarity.