archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-08-28 07:14:30 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

8333768: Minor doc updates to java.lang.{Float, Double}

Browse source 
Reviewed-by: rgiulietti
This commit is contained in:
Joe Darcy 2024-07-18 16:33:48 +00:00
parent 245c086648
commit bbc79a5e01
4 changed files with 111 additions and 31 deletions
Download patch file Download diff file Expand all files Collapse all files

54
src/java.base/share/classes/java/lang/Float.java
View file

@ -307,6 +307,23 @@ public final class Float extends Number
* <p>To create localized string representations of a floating-point
* value, use subclasses of {@link java.text.NumberFormat}.
*
* @apiNote
* This method corresponds to the general functionality of the
* convertToDecimalCharacter operation defined in IEEE 754;
* however, that operation is defined in terms of specifying the
* number of significand digits used in the conversion.
* Code to do such a conversion in the Java platform includes
* converting the {@code float} to a {@link java.math.BigDecimal
* BigDecimal} exactly and then rounding the {@code BigDecimal} to
* the desired number of digits; sample code:
* {@snippet lang=java :
* floatf = 0.1f;
* int digits = 15;
* BigDecimal bd = new BigDecimal(f);
* String result = bd.round(new MathContext(digits, RoundingMode.HALF_UP));
* // 0.100000001490116
* }
*
* @param f the {@code float} to be converted.
* @return a string representation of the argument.
*/
@ -387,6 +404,11 @@ public final class Float extends Number
* <td>{@code 0x0.000002p-126}</td>
* </tbody>
* </table>
*
* @apiNote
* This method corresponds to the convertToHexCharacter operation
* defined in IEEE 754.
*
* @param f the {@code float} to be converted.
* @return a hex string representation of the argument.
* @since 1.5
@ -524,6 +546,10 @@ public final class Float extends Number
* where {@code l} is the desired locale, or
* {@link java.util.Locale#ROOT} if locale insensitive.
*
* @apiNote
* This method corresponds to the convertFromDecimalCharacter and
* convertFromHexCharacter operations defined in IEEE 754.
*
* @param s the string to be parsed.
* @return a {@code Float} object holding the value
* represented by the {@code String} argument.
@ -729,6 +755,7 @@ public final class Float extends Number
* converted to type {@code byte}
* @jls 5.1.3 Narrowing Primitive Conversion
*/
@Override
public byte byteValue() {
return (byte)value;
}
@ -742,6 +769,7 @@ public final class Float extends Number
* @jls 5.1.3 Narrowing Primitive Conversion
* @since 1.1
*/
@Override
public short shortValue() {
return (short)value;
}
@ -750,10 +778,15 @@ public final class Float extends Number
* Returns the value of this {@code Float} as an {@code int} after
* a narrowing primitive conversion.
*
* @apiNote
* This method corresponds to the convertToIntegerTowardZero
* operation defined in IEEE 754.
*
* @return the {@code float} value represented by this object
* converted to type {@code int}
* @jls 5.1.3 Narrowing Primitive Conversion
*/
@Override
public int intValue() {
return (int)value;
}
@ -762,10 +795,15 @@ public final class Float extends Number
* Returns value of this {@code Float} as a {@code long} after a
* narrowing primitive conversion.
*
* @apiNote
* This method corresponds to the convertToIntegerTowardZero
* operation defined in IEEE 754.
*
* @return the {@code float} value represented by this object
* converted to type {@code long}
* @jls 5.1.3 Narrowing Primitive Conversion
*/
@Override
public long longValue() {
return (long)value;
}
@ -775,6 +813,7 @@ public final class Float extends Number
*
* @return the {@code float} value represented by this object
*/
@Override
@IntrinsicCandidate
public float floatValue() {
return value;
@ -792,6 +831,7 @@ public final class Float extends Number
* object converted to type {@code double}
* @jls 5.1.2 Widening Primitive Conversion
*/
@Override
public double doubleValue() {
return (double)value;
}
@ -839,9 +879,8 @@ public final class Float extends Number
* {@code float} values since the {@code ==} operator does
* <em>not</em> define an equivalence relation and to satisfy the
* {@linkplain Object#equals equals contract} an equivalence
* relation must be implemented; see <a
* href="Double.html#equivalenceRelation">this discussion</a> for
* details of floating-point equality and equivalence.
* relation must be implemented; see {@linkplain Double##equivalenceRelation
* this discussion for details of floating-point equality and equivalence}.
*
* @param obj the object to be compared
* @return {@code true} if the objects are the same;
@ -1092,7 +1131,7 @@ public final class Float extends Number
* <li> If the argument is a NaN, the result is a NaN.
* </ul>
*
* The <a href="#binary16Format">binary16 format</a> is discussed in
* The {@linkplain ##binary16Format binary16 format} is discussed in
* more detail in the {@link #float16ToFloat} method.
*
* @apiNote
@ -1208,9 +1247,9 @@ public final class Float extends Number
*
* This ensures that the <i>natural ordering</i> of {@code Float}
* objects imposed by this method is <i>consistent with
* equals</i>; see <a href="Double.html#equivalenceRelation">this
* discussion</a> for details of floating-point comparison and
* ordering.
* equals</i>; see {@linkplain Double##equivalenceRelation this
* discussion for details of floating-point comparison and
* ordering}.
*
*
* @param anotherFloat the {@code Float} to be compared.
@ -1225,6 +1264,7 @@ public final class Float extends Number
* @jls 15.20.1 Numerical Comparison Operators {@code <}, {@code <=}, {@code >}, and {@code >=}
* @since 1.2
*/
@Override
public int compareTo(Float anotherFloat) {
return Float.compare(value, anotherFloat.value);
}