1118
1119 /**
1120 * Returns the smaller of two {@code double} values. That
1121 * is, the result is the value closer to negative infinity. If the
1122 * arguments have the same value, the result is that same
1123 * value. If either value is NaN, then the result is NaN. Unlike
1124 * the numerical comparison operators, this method considers
1125 * negative zero to be strictly smaller than positive zero. If one
1126 * argument is positive zero and the other is negative zero, the
1127 * result is negative zero.
1128 *
1129 * @param a an argument.
1130 * @param b another argument.
1131 * @return the smaller of {@code a} and {@code b}.
1132 */
1133 public static double min(double a, double b) {
1134 return Math.min(a, b);
1135 }
1136
1137 /**
1138 * Returns the size of an ulp of the argument. An ulp, unit in
1139 * the last place, of a {@code double} value is the positive
1140 * distance between this floating-point value and the {@code
1141 * double} value next larger in magnitude. Note that for non-NaN
1142 * <i>x</i>, <code>ulp(-<i>x</i>) == ulp(<i>x</i>)</code>.
1143 *
1144 * <p>Special Cases:
1145 * <ul>
1146 * <li> If the argument is NaN, then the result is NaN.
1147 * <li> If the argument is positive or negative infinity, then the
1148 * result is positive infinity.
1149 * <li> If the argument is positive or negative zero, then the result is
1150 * {@code Double.MIN_VALUE}.
1151 * <li> If the argument is ±{@code Double.MAX_VALUE}, then
1152 * the result is equal to 2<sup>971</sup>.
1153 * </ul>
1154 *
1155 * @param d the floating-point value whose ulp is to be returned
1156 * @return the size of an ulp of the argument
1157 * @author Joseph D. Darcy
|
1118
1119 /**
1120 * Returns the smaller of two {@code double} values. That
1121 * is, the result is the value closer to negative infinity. If the
1122 * arguments have the same value, the result is that same
1123 * value. If either value is NaN, then the result is NaN. Unlike
1124 * the numerical comparison operators, this method considers
1125 * negative zero to be strictly smaller than positive zero. If one
1126 * argument is positive zero and the other is negative zero, the
1127 * result is negative zero.
1128 *
1129 * @param a an argument.
1130 * @param b another argument.
1131 * @return the smaller of {@code a} and {@code b}.
1132 */
1133 public static double min(double a, double b) {
1134 return Math.min(a, b);
1135 }
1136
1137 /**
1138 * Returns the fused multiply add of the three arguments; that is,
1139 * returns the exact product of the first two arguments summed
1140 * with the third argument and then rounded once to the nearest
1141 * {@code double}.
1142 *
1143 * The rounding is done using the {@linkplain
1144 * java.math.RoundingMode#HALF_EVEN round to nearest even
1145 * rounding mode}.
1146 *
1147 * In contrast, if {@code a * b + c} is evaluated as a regular
1148 * floating-point expression, two rounding errors are involved,
1149 * the first for the multiply operation, the second for the
1150 * addition operation.
1151 *
1152 * <p>Special cases:
1153 * <ul>
1154 * <li> If any argument is NaN, the result is NaN.
1155 *
1156 * <li> If one of the first two arguments is infinite and the
1157 * other is zero, the result is NaN.
1158 *
1159 * <li> If the exact product of the first two arguments is infinite
1160 * (in other words, at least one of the arguments is infinite and
1161 * the other is neither zero nor NaN) and the third argument is an
1162 * infinity of the opposite sign, the result is NaN.
1163 *
1164 * </ul>
1165 *
1166 * <p>Note that {@code fusedMac(a, 1.0, c)} returns the same
1167 * result as ({@code a + c}). However,
1168 * {@code fusedMac(a, b, +0.0)} does <em>not</em> always return the
1169 * same result as ({@code a * b}) since
1170 * {@code fusedMac(-0.0, +0.0, +0.0)} is {@code +0.0} while
1171 * ({@code -0.0 * +0.0}) is {@code -0.0}; {@code fusedMac(a, b, -0.0)} is
1172 * equivalent to ({@code a * b}) however.
1173 *
1174 * @apiNote This method corresponds to the fusedMultiplyAdd
1175 * operation defined in IEEE 754-2008.
1176 *
1177 * @param a a value
1178 * @param b a value
1179 * @param c a value
1180 *
1181 * @return (<i>a</i> × <i>b</i> + <i>c</i>)
1182 * computed, as if with unlimited range and precision, and rounded
1183 * once to the nearest {@code double} value
1184 */
1185 public static double fma(double a, double b, double c) {
1186 return Math.fma(a, b, c);
1187 }
1188
1189 /**
1190 * Returns the fused multiply add of the three arguments; that is,
1191 * returns the exact product of the first two arguments summed
1192 * with the third argument and then rounded once to the nearest
1193 * {@code float}.
1194 *
1195 * The rounding is done using the {@linkplain
1196 * java.math.RoundingMode#HALF_EVEN round to nearest even
1197 * rounding mode}.
1198 *
1199 * In contrast, if {@code a * b + c} is evaluated as a regular
1200 * floating-point expression, two rounding errors are involved,
1201 * the first for the multiply operation, the second for the
1202 * addition operation.
1203 *
1204 * <p>Special cases:
1205 * <ul>
1206 * <li> If any argument is NaN, the result is NaN.
1207 *
1208 * <li> If one of the first two arguments is infinite and the
1209 * other is zero, the result is NaN.
1210 *
1211 * <li> If the exact product of the first two arguments is infinite
1212 * (in other words, at least one of the arguments is infinite and
1213 * the other is neither zero nor NaN) and the third argument is an
1214 * infinity of the opposite sign, the result is NaN.
1215 *
1216 * </ul>
1217 *
1218 * <p>Note that {@code fma(a, 1.0f, c)} returns the same
1219 * result as ({@code a + c}). However,
1220 * {@code fma(a, b, +0.0f)} does <em>not</em> always return the
1221 * same result as ({@code a * b}) since
1222 * {@code fma(-0.0f, +0.0f, +0.0f)} is {@code +0.0f} while
1223 * ({@code -0.0f * +0.0f}) is {@code -0.0f}; {@code fma(a, b, -0.0f)} is
1224 * equivalent to ({@code a * b}) however.
1225 *
1226 * @apiNote This method corresponds to the fusedMultiplyAdd
1227 * operation defined in IEEE 754-2008.
1228 *
1229 * @param a a value
1230 * @param b a value
1231 * @param c a value
1232 *
1233 * @return (<i>a</i> × <i>b</i> + <i>c</i>)
1234 * computed, as if with unlimited range and precision, and rounded
1235 * once to the nearest {@code float} value
1236 */
1237 public static float fma(float a, float b, float c) {
1238 return Math.fma(a, b, c);
1239 }
1240
1241 /**
1242 * Returns the size of an ulp of the argument. An ulp, unit in
1243 * the last place, of a {@code double} value is the positive
1244 * distance between this floating-point value and the {@code
1245 * double} value next larger in magnitude. Note that for non-NaN
1246 * <i>x</i>, <code>ulp(-<i>x</i>) == ulp(<i>x</i>)</code>.
1247 *
1248 * <p>Special Cases:
1249 * <ul>
1250 * <li> If the argument is NaN, then the result is NaN.
1251 * <li> If the argument is positive or negative infinity, then the
1252 * result is positive infinity.
1253 * <li> If the argument is positive or negative zero, then the result is
1254 * {@code Double.MIN_VALUE}.
1255 * <li> If the argument is ±{@code Double.MAX_VALUE}, then
1256 * the result is equal to 2<sup>971</sup>.
1257 * </ul>
1258 *
1259 * @param d the floating-point value whose ulp is to be returned
1260 * @return the size of an ulp of the argument
1261 * @author Joseph D. Darcy
|