Issue | Fix Version | Assignee | Priority | Status | Resolution | Resolved In Build |
---|---|---|---|---|---|---|
JDK-8084459 | emb-9 | Brian Burkhalter | P4 | Resolved | Fixed | team |
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
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
- backported by
-
JDK-8084459 Documentation for methods in Number incomplete regarding too large values.
-
- Resolved
-