Documentation of methods in java.lang.Number

2014-12-16 Thread Andreas Lundblad
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 n

Re: Documentation of methods in java.lang.Number

2014-12-16 Thread Seán Coffey
Andreas, this didn't get attention in the past. You can now find your report at https://bugs.openjdk.java.net/browse/JDK-8067669 I'll leave it up to maths engineers to determine if the Number API needs improving. regards, Sean. On 16/12/2014 12:55, Andreas Lundblad wrote: I've noticed that

Re: Documentation of methods in java.lang.Number

2014-12-16 Thread 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 “[…] conversi

Re: Documentation of methods in java.lang.Number

2014-12-17 Thread Andreas Lundblad
On Tue, Dec 16, 2014 at 03:18:49PM -0800, Brian Burkhalter wrote: > 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

Re: Documentation of methods in java.lang.Number

2014-12-17 Thread Brian Burkhalter
On Dec 17, 2014, at 2:26 AM, Andreas Lundblad wrote: > Right. As it stands now the class level description says "the semantics of > the conversion is defined by the Number implementation in question", and then > the documentation of longValue narrows this down to "rounding or truncation". >

Re: Documentation of methods in java.lang.Number

2014-12-19 Thread Brian Burkhalter
On Dec 17, 2014, at 2:26 AM, Andreas Lundblad wrote: > Another suggestion would be: > > "Returns the value of the specified number as a {@code long}. The specific > semantics of the conversion is defined by the subclass in question." Does something like the following seem reasonable? Brian

Re: Documentation of methods in java.lang.Number

2014-12-19 Thread joe darcy
Hello, On 12/19/2014 2:39 PM, Brian Burkhalter wrote: On Dec 17, 2014, at 2:26 AM, Andreas Lundblad wrote: Another suggestion would be: "Returns the value of the specified number as a {@code long}. The specific semantics of the conversion is defined by the subclass in question." Does some

Re: Documentation of methods in java.lang.Number

2014-12-19 Thread Brian Burkhalter
On Dec 19, 2014, at 3:26 PM, joe darcy wrote: > I don't really think the current text is problematic; however, if it is to be > changed, I recommending including a citation to the "Narrowing primitive > conversion" section of the Java Language Specification. This can be > accomplished using t