8333768: Minor doc updates to java.lang.{Float, Double}
Reviewed-by: rgiulietti
This commit is contained in:
Joe Darcy
parent
245c086648
commit
bbc79a5e01
@ -116,8 +116,8 @@ import jdk.internal.vm.annotation.IntrinsicCandidate;
|
||||
* <p>To provide the appropriate semantics for {@code equals} and
|
||||
* {@code compareTo} methods, those methods cannot simply be wrappers
|
||||
* around {@code ==} or ordered comparison operations. Instead, {@link
|
||||
* Double#equals equals} uses <a href=#repEquivalence> representation
|
||||
* equivalence</a>, defining NaN arguments to be equal to each other,
|
||||
* Double#equals equals} uses {@linkplain ##repEquivalence representation
|
||||
* equivalence}, defining NaN arguments to be equal to each other,
|
||||
* restoring reflexivity, and defining {@code +0.0} to <em>not</em> be
|
||||
* equal to {@code -0.0}. For comparisons, {@link Double#compareTo
|
||||
* compareTo} defines a total order where {@code -0.0} is less than
|
||||
@ -591,6 +591,23 @@ public final class Double 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 double} 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 :
|
||||
* double d = 0.1;
|
||||
* int digits = 25;
|
||||
* BigDecimal bd = new BigDecimal(d);
|
||||
* String result = bd.round(new MathContext(digits, RoundingMode.HALF_UP));
|
||||
* // 0.1000000000000000055511151
|
||||
* }
|
||||
*
|
||||
* @param d the {@code double} to be converted.
|
||||
* @return a string representation of the argument.
|
||||
*/
|
||||
@ -671,6 +688,11 @@ public final class Double extends Number
|
||||
* <td>{@code 0x0.0000000000001p-1022}</td>
|
||||
* </tbody>
|
||||
* </table>
|
||||
*
|
||||
* @apiNote
|
||||
* This method corresponds to the convertToHexCharacter operation
|
||||
* defined in IEEE 754.
|
||||
*
|
||||
* @param d the {@code double} to be converted.
|
||||
* @return a hex string representation of the argument.
|
||||
* @since 1.5
|
||||
@ -897,6 +919,10 @@ public final class Double 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 Double} object holding the value
|
||||
* represented by the {@code String} argument.
|
||||
@ -1087,6 +1113,7 @@ public final class Double extends Number
|
||||
* @jls 5.1.3 Narrowing Primitive Conversion
|
||||
* @since 1.1
|
||||
*/
|
||||
@Override
|
||||
public byte byteValue() {
|
||||
return (byte)value;
|
||||
}
|
||||
@ -1100,6 +1127,7 @@ public final class Double extends Number
|
||||
* @jls 5.1.3 Narrowing Primitive Conversion
|
||||
* @since 1.1
|
||||
*/
|
||||
@Override
|
||||
public short shortValue() {
|
||||
return (short)value;
|
||||
}
|
||||
@ -1109,9 +1137,14 @@ public final class Double extends Number
|
||||
* after a narrowing primitive conversion.
|
||||
* @jls 5.1.3 Narrowing Primitive Conversion
|
||||
*
|
||||
* @apiNote
|
||||
* This method corresponds to the convertToIntegerTowardZero
|
||||
* operation defined in IEEE 754.
|
||||
*
|
||||
* @return the {@code double} value represented by this object
|
||||
* converted to type {@code int}
|
||||
*/
|
||||
@Override
|
||||
public int intValue() {
|
||||
return (int)value;
|
||||
}
|
||||
@ -1120,10 +1153,15 @@ public final class Double extends Number
|
||||
* Returns the value of this {@code Double} as a {@code long}
|
||||
* after a narrowing primitive conversion.
|
||||
*
|
||||
* @apiNote
|
||||
* This method corresponds to the convertToIntegerTowardZero
|
||||
* operation defined in IEEE 754.
|
||||
*
|
||||
* @return the {@code double} value represented by this object
|
||||
* converted to type {@code long}
|
||||
* @jls 5.1.3 Narrowing Primitive Conversion
|
||||
*/
|
||||
@Override
|
||||
public long longValue() {
|
||||
return (long)value;
|
||||
}
|
||||
@ -1141,6 +1179,7 @@ public final class Double extends Number
|
||||
* @jls 5.1.3 Narrowing Primitive Conversion
|
||||
* @since 1.0
|
||||
*/
|
||||
@Override
|
||||
public float floatValue() {
|
||||
return (float)value;
|
||||
}
|
||||
@ -1150,6 +1189,7 @@ public final class Double extends Number
|
||||
*
|
||||
* @return the {@code double} value represented by this object
|
||||
*/
|
||||
@Override
|
||||
@IntrinsicCandidate
|
||||
public double doubleValue() {
|
||||
return value;
|
||||
@ -1210,9 +1250,8 @@ public final class Double extends Number
|
||||
* on {@code double} 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="#equivalenceRelation">this discussion</a> for details of
|
||||
* floating-point equality and equivalence.
|
||||
* relation must be implemented; see {@linkplain ##equivalenceRelation
|
||||
* this discussion for details of floating-point equality and equivalence}.
|
||||
*
|
||||
* @see java.lang.Double#doubleToLongBits(double)
|
||||
* @jls 15.21.1 Numerical Equality Operators == and !=
|
||||
@ -1389,9 +1428,9 @@ public final class Double extends Number
|
||||
|
||||
* This ensures that the <i>natural ordering</i> of {@code Double}
|
||||
* objects imposed by this method is <i>consistent with
|
||||
* equals</i>; see <a href="#equivalenceRelation">this
|
||||
* discussion</a> for details of floating-point comparison and
|
||||
* ordering.
|
||||
* equals</i>; see {@linkplain ##equivalenceRelation this
|
||||
* discussion for details of floating-point comparison and
|
||||
* ordering}.
|
||||
*
|
||||
* @param anotherDouble the {@code Double} to be compared.
|
||||
* @return the value {@code 0} if {@code anotherDouble} is
|
||||
@ -1405,6 +1444,7 @@ public final class Double extends Number
|
||||
* @jls 15.20.1 Numerical Comparison Operators {@code <}, {@code <=}, {@code >}, and {@code >=}
|
||||
* @since 1.2
|
||||
*/
|
||||
@Override
|
||||
public int compareTo(Double anotherDouble) {
|
||||
return Double.compare(value, anotherDouble.value);
|
||||
}
|
||||
|
||||
@ -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);
|
||||
}
|
||||
|
||||
@ -225,7 +225,7 @@ public final class Math {
|
||||
|
||||
/**
|
||||
* Returns the arc sine of a value; the returned angle is in the
|
||||
* range -<i>pi</i>/2 through <i>pi</i>/2. Special cases:
|
||||
* range −<i>pi</i>/2 through <i>pi</i>/2. Special cases:
|
||||
* <ul><li>If the argument is NaN or its absolute value is greater
|
||||
* than 1, then the result is NaN.
|
||||
* <li>If the argument is zero, then the result is a zero with the
|
||||
@ -261,7 +261,7 @@ public final class Math {
|
||||
|
||||
/**
|
||||
* Returns the arc tangent of a value; the returned angle is in the
|
||||
* range -<i>pi</i>/2 through <i>pi</i>/2. Special cases:
|
||||
* range −<i>pi</i>/2 through <i>pi</i>/2. Special cases:
|
||||
* <ul><li>If the argument is NaN, then the result is NaN.
|
||||
* <li>If the argument is zero, then the result is a zero with the
|
||||
* same sign as the argument.
|
||||
@ -553,7 +553,7 @@ public final class Math {
|
||||
* coordinates ({@code x}, {@code y}) to polar
|
||||
* coordinates (r, <i>theta</i>).
|
||||
* This method computes the phase <i>theta</i> by computing an arc tangent
|
||||
* of {@code y/x} in the range of -<i>pi</i> to <i>pi</i>. Special
|
||||
* of {@code y/x} in the range of −<i>pi</i> to <i>pi</i>. Special
|
||||
* cases:
|
||||
* <ul><li>If either argument is NaN, then the result is NaN.
|
||||
* <li>If the first argument is positive zero and the second argument
|
||||
@ -2645,7 +2645,7 @@ public final class Math {
|
||||
/**
|
||||
* Returns the hyperbolic sine of a {@code double} value.
|
||||
* The hyperbolic sine of <i>x</i> is defined to be
|
||||
* (<i>e<sup>x</sup> - e<sup>-x</sup></i>)/2
|
||||
* (<i>e<sup>x</sup> − e<sup>−x</sup></i>)/2
|
||||
* where <i>e</i> is {@linkplain Math#E Euler's number}.
|
||||
*
|
||||
* <p>Special cases:
|
||||
@ -2674,7 +2674,7 @@ public final class Math {
|
||||
/**
|
||||
* Returns the hyperbolic cosine of a {@code double} value.
|
||||
* The hyperbolic cosine of <i>x</i> is defined to be
|
||||
* (<i>e<sup>x</sup> + e<sup>-x</sup></i>)/2
|
||||
* (<i>e<sup>x</sup> + e<sup>−x</sup></i>)/2
|
||||
* where <i>e</i> is {@linkplain Math#E Euler's number}.
|
||||
*
|
||||
* <p>Special cases:
|
||||
@ -2702,7 +2702,7 @@ public final class Math {
|
||||
/**
|
||||
* Returns the hyperbolic tangent of a {@code double} value.
|
||||
* The hyperbolic tangent of <i>x</i> is defined to be
|
||||
* (<i>e<sup>x</sup> - e<sup>-x</sup></i>)/(<i>e<sup>x</sup> + e<sup>-x</sup></i>),
|
||||
* (<i>e<sup>x</sup> − e<sup>−x</sup></i>)/(<i>e<sup>x</sup> + e<sup>−x</sup></i>),
|
||||
* in other words, {@linkplain Math#sinh
|
||||
* sinh(<i>x</i>)}/{@linkplain Math#cosh cosh(<i>x</i>)}. Note
|
||||
* that the absolute value of the exact tanh is always less than
|
||||
@ -2770,7 +2770,7 @@ public final class Math {
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns <i>e</i><sup>x</sup> -1. Note that for values of
|
||||
* Returns <i>e</i><sup>x</sup> −1. Note that for values of
|
||||
* <i>x</i> near 0, the exact sum of
|
||||
* {@code expm1(x)} + 1 is much closer to the true
|
||||
* result of <i>e</i><sup>x</sup> than {@code exp(x)}.
|
||||
@ -2799,7 +2799,7 @@ public final class Math {
|
||||
* returned.
|
||||
*
|
||||
* @param x the exponent to raise <i>e</i> to in the computation of
|
||||
* <i>e</i><sup>{@code x}</sup> -1.
|
||||
* <i>e</i><sup>{@code x}</sup> −1.
|
||||
* @return the value <i>e</i><sup>{@code x}</sup> - 1.
|
||||
* @since 1.5
|
||||
*/
|
||||
|
||||
@ -181,7 +181,7 @@ public final class StrictMath {
|
||||
|
||||
/**
|
||||
* Returns the arc sine of a value; the returned angle is in the
|
||||
* range -<i>pi</i>/2 through <i>pi</i>/2. Special cases:
|
||||
* range −<i>pi</i>/2 through <i>pi</i>/2. Special cases:
|
||||
* <ul><li>If the argument is NaN or its absolute value is greater
|
||||
* than 1, then the result is NaN.
|
||||
* <li>If the argument is zero, then the result is a zero with the
|
||||
@ -211,7 +211,7 @@ public final class StrictMath {
|
||||
|
||||
/**
|
||||
* Returns the arc tangent of a value; the returned angle is in the
|
||||
* range -<i>pi</i>/2 through <i>pi</i>/2. Special cases:
|
||||
* range −<i>pi</i>/2 through <i>pi</i>/2. Special cases:
|
||||
* <ul><li>If the argument is NaN, then the result is NaN.
|
||||
* <li>If the argument is zero, then the result is a zero with the
|
||||
* same sign as the argument.
|
||||
@ -524,7 +524,7 @@ public final class StrictMath {
|
||||
* coordinates ({@code x}, {@code y}) to polar
|
||||
* coordinates (r, <i>theta</i>).
|
||||
* This method computes the phase <i>theta</i> by computing an arc tangent
|
||||
* of {@code y/x} in the range of -<i>pi</i> to <i>pi</i>. Special
|
||||
* of {@code y/x} in the range of −<i>pi</i> to <i>pi</i>. Special
|
||||
* cases:
|
||||
* <ul><li>If either argument is NaN, then the result is NaN.
|
||||
* <li>If the first argument is positive zero and the second argument
|
||||
@ -2093,7 +2093,7 @@ public final class StrictMath {
|
||||
/**
|
||||
* Returns the hyperbolic sine of a {@code double} value.
|
||||
* The hyperbolic sine of <i>x</i> is defined to be
|
||||
* (<i>e<sup>x</sup> - e<sup>-x</sup></i>)/2
|
||||
* (<i>e<sup>x</sup> − e<sup>−x</sup></i>)/2
|
||||
* where <i>e</i> is {@linkplain Math#E Euler's number}.
|
||||
*
|
||||
* <p>Special cases:
|
||||
@ -2120,7 +2120,7 @@ public final class StrictMath {
|
||||
/**
|
||||
* Returns the hyperbolic cosine of a {@code double} value.
|
||||
* The hyperbolic cosine of <i>x</i> is defined to be
|
||||
* (<i>e<sup>x</sup> + e<sup>-x</sup></i>)/2
|
||||
* (<i>e<sup>x</sup> + e<sup>−x</sup></i>)/2
|
||||
* where <i>e</i> is {@linkplain Math#E Euler's number}.
|
||||
*
|
||||
* <p>Special cases:
|
||||
@ -2146,7 +2146,7 @@ public final class StrictMath {
|
||||
/**
|
||||
* Returns the hyperbolic tangent of a {@code double} value.
|
||||
* The hyperbolic tangent of <i>x</i> is defined to be
|
||||
* (<i>e<sup>x</sup> - e<sup>-x</sup></i>)/(<i>e<sup>x</sup> + e<sup>-x</sup></i>),
|
||||
* (<i>e<sup>x</sup> − e<sup>−x</sup></i>)/(<i>e<sup>x</sup> + e<sup>−x</sup></i>),
|
||||
* in other words, {@linkplain Math#sinh
|
||||
* sinh(<i>x</i>)}/{@linkplain Math#cosh cosh(<i>x</i>)}. Note
|
||||
* that the absolute value of the exact tanh is always less than
|
||||
@ -2203,7 +2203,7 @@ public final class StrictMath {
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns <i>e</i><sup>x</sup> -1. Note that for values of
|
||||
* Returns <i>e</i><sup>x</sup> −1. Note that for values of
|
||||
* <i>x</i> near 0, the exact sum of
|
||||
* {@code expm1(x)} + 1 is much closer to the true
|
||||
* result of <i>e</i><sup>x</sup> than {@code exp(x)}.
|
||||
@ -2224,7 +2224,7 @@ public final class StrictMath {
|
||||
* </ul>
|
||||
*
|
||||
* @param x the exponent to raise <i>e</i> to in the computation of
|
||||
* <i>e</i><sup>{@code x}</sup> -1.
|
||||
* <i>e</i><sup>{@code x}</sup> −1.
|
||||
* @return the value <i>e</i><sup>{@code x}</sup> - 1.
|
||||
* @since 1.5
|
||||
*/
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user