Documentation of methods in java.lang.Number

[Brian Burkhalter]

Andreas,

Doesn’t the class documentation of Number [1] provide sufficient clarity, to wit:

" The specific semantics of the conversion from the numeric value of a particular Number implementation to a given primitive type is defined by the Number implementation in question.”

and

“[…] conversions may lose information about the overall magnitude of a numeric value, may lose precision, and may even return a result of a different sign than the input. See the documentation of a given Number implementation for conversion details.”

That said, it might not however hurt slightly to modify the descriptions of {float,double,int,long}Value() to read something like, for longValue() for example:

"Returns the value of the specified number as a {@code long}, which may
 involve rounding, truncation, or some other narrowing conversion."

Brian

[1] http://docs.oracle.com/javase/8/docs/api/java/lang/Number.html

On Dec 16, 2014, at 4:55 AM, Andreas Lundblad <andreas.lundblad at oracle.com> wrote:

> I've noticed that the documentation of Number.longValue says:
> 
>> Returns the value of the specified number as a long, which may involve rounding or truncation.
> 
> BigInteger and BigDecimal does not seem to honor this contract since they implement this method by masking out the lower bits of the number (and I've found no definition of "rounding" or "truncation" that encompass this behavuor). The documentation of these classes even state that "[...] this conversion can lose information about the overall magnitude of the BigInteger value as well as return a result with the opposite sign."
> 
> I suggest the documentation of Number.byteValue/shortValue/intValue/longValue should be updated to give room for this type of implementation.
> 
> (I filed an issue on this and got a confirmation email with the following link: http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=7000825 Since then this page has gone missing. Where did the bug report go, and why didn't I get any notification about the removal?)