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.lundb...@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?)