Summary

Explicitly specify that BigInteger.bitLength() returns 0 when the value of the BigInteger is zero.

Problem

The pseudo-code in the specification of BigInteger.bitLength() makes it clear that 0 is returned for a zero-valued BigInteger but this is not expressed verbally. This has led to some small confusion. By contrast the specification of java.util.BitSet.length() clearly states that new BitSet(0).length() == 0. Analogous functions in other well-known high level languages also document this special case explicitly.

Solution

Add explicit verbiage stating in effect that BigInteger.ZERO.bitLength() == 0.

Specification

--- a/src/java.base/share/classes/java/math/BigInteger.java
+++ b/src/java.base/share/classes/java/math/BigInteger.java
@@ -3556,8 +3556,8 @@
     * Returns the number of bits in the minimal two's-complement
     * representation of this BigInteger, <em>excluding</em> a sign bit.
     * For positive BigIntegers, this is equivalent to the number of bits in
-     * the ordinary binary representation.  (Computes
-     * {@code (ceil(log2(this < 0 ? -this : this+1)))}.)
+     * the ordinary binary representation.  For zero this method returns
+     * {@code 0}.  (Computes {@code (ceil(log2(this < 0 ? -this : this+1)))}.)
     *
     * @return number of bits in the minimal two's-complement
     *         representation of this BigInteger, <em>excluding</em> a sign bit