Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8199280

BigInteger.bitLength() should explicitly specify behavior when the value is zero

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P4
    • Resolution: Approved
    • Fix Version/s: 11
    • Component/s: core-libs
    • Labels:
      None
    • Subcomponent:
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      No code is being changed so there is nothing testable.
    • Interface Kind:
      Java API
    • Scope:
      JDK

      Description

      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

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                bpb Brian Burkhalter
                Reporter:
                bpb Brian Burkhalter
                Reviewed By:
                Stuart Marks
              • Votes:
                0 Vote for this issue
                Watchers:
                1 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved: