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

Documentation for methods in Number incomplete regarding too large values.

    Details

    • Type: Enhancement
    • Status: Resolved
    • Priority: P4
    • Resolution: Fixed
    • Affects Version/s: 6u22
    • Fix Version/s: 9
    • Component/s: core-libs
    • Subcomponent:
    • Resolved In Build:
      b50
    • CPU:
      x86
    • OS:
      linux_ubuntu

      Backports

        Description

        A DESCRIPTION OF THE PROBLEM :
        The documentation of floatValue and doubleValue say that the returned value may involve rounding.

        The documentation of the byteValue, shortValue, intValue and longValue also allow for truncation.

        However, this doesn't seem compatible with the documentation of the subclasses of Number, as many of these chose to return only the lower bits of the number they represent. (See for example Long.intValue, or BigInteger.longValue.)

        Discarding the high bits of a value does not count as "truncation". The JLS 5.1.3 for instance describes the same process (when narrowing integral primitive types) as follows:

            A narrowing conversion of a signed integer to an integral type T simply discards all but the n lowest order bits, where n is the number of bits used to represent type T.


        EXPECTED VERSUS ACTUAL BEHAVIOR :
        EXPECTED -
        Either the documentation for the methods in the Number class should be expanded to also describe and allow for the behavior of discarding high bits. (Alternatively documentation and implementation of all subclasses of Number should be changed, which is obviously not feasible.)

        For example:

        public abstract long longValue()

            Returns the value of the specified number as a long. This may involve rounding, truncation or discarding of high bits.


        ACTUAL -
        public abstract long longValue()

            Returns the value of the specified number as a long. This may involve rounding or truncation.

        URL OF FAULTY DOCUMENTATION :
        http://download.oracle.com/javase/6/docs/api/java/lang/Number.html

          Attachments

            Issue Links

              Activity

                People

                • Assignee:
                  bpb Brian Burkhalter
                  Reporter:
                  duke J. Duke (Inactive)
                • Votes:
                  0 Vote for this issue
                  Watchers:
                  4 Start watching this issue

                  Dates

                  • Created:
                    Updated:
                    Resolved:
                    Imported: