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-accumulate of the three arguments;
1139 * that is, returns the exact product of the first two arguments
1140 * summed with the third argument and then rounded once to the
1141 * nearest {@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 * @param a a value
1175 * @param b a value
1176 * @param c a value
1177 *
1178 * @return (<i>a</i> × <i>b</i> + <i>c</i>)
1179 * computed, as if with unlimited range and precision, and rounded
1180 * once to the nearest {@code double} value
1181 */
1182 public static double fusedMac(double a, double b, double c) {
1183 return Math.fusedMac(a, b, c);
1184 }
1185
1186 /**
1187 * Returns the fused multiply-accumulate of the three arguments;
1188 * that is, returns the exact product of the first two arguments
1189 * summed with the third argument and then rounded once to the
1190 * nearest {@code float}.
1191 *
1192 * The rounding is done using the {@linkplain
1193 * java.math.RoundingMode#HALF_EVEN round to nearest even
1194 * rounding mode}.
1195 *
1196 * In contrast, if {@code a * b + c} is evaluated as a regular
1197 * floating-point expression, two rounding errors are involved,
1198 * the first for the multiply operation, the second for the
1199 * addition operation.
1200 *
1201 * <p>Special cases:
1202 * <ul>
1203 * <li> If any argument is NaN, the result is NaN.
1204 *
1205 * <li> If one of the first two arguments is infinite and the
1206 * other is zero, the result is NaN.
1207 *
1208 * <li> If the exact product of the first two arguments is infinite
1209 * (in other words, at least one of the arguments is infinite and
1210 * the other is neither zero nor NaN) and the third argument is an
1211 * infinity of the opposite sign, the result is NaN.
1212 *
1213 * </ul>
1214 *
1215 * <p>Note that {@code fusedMac(a, 1.0f, c)} returns the same
1216 * result as ({@code a + c}). However,
1217 * {@code fusedMac(a, b, +0.0f)} does <em>not</em> always return the
1218 * same result as ({@code a * b}) since
1219 * {@code fusedMac(-0.0f, +0.0f, +0.0f)} is {@code +0.0f} while
1220 * ({@code 0.0f * +0.0f}) is {@code -0.0f}; {@code fusedMac(a, b, -0.0f)} is
1221 * equivalent to ({@code a * b}) however.
1222 *
1223 * @param a a value
1224 * @param b a value
1225 * @param c a value
1226 *
1227 * @return (<i>a</i> × <i>b</i> + <i>c</i>)
1228 * computed, as if with unlimited range and precision, and rounded
1229 * once to the nearest {@code float} value
1230 */
1231 public static float fusedMac(float a, float b, float c) {
1232 return Math.fusedMac(a, b, c);
1233 }
1234
1235 /**
1236 * Returns the size of an ulp of the argument. An ulp, unit in
1237 * the last place, of a {@code double} value is the positive
1238 * distance between this floating-point value and the {@code
1239 * double} value next larger in magnitude. Note that for non-NaN
1240 * <i>x</i>, <code>ulp(-<i>x</i>) == ulp(<i>x</i>)</code>.
1241 *
1242 * <p>Special Cases:
1243 * <ul>
1244 * <li> If the argument is NaN, then the result is NaN.
1245 * <li> If the argument is positive or negative infinity, then the
1246 * result is positive infinity.
1247 * <li> If the argument is positive or negative zero, then the result is
1248 * {@code Double.MIN_VALUE}.
1249 * <li> If the argument is ±{@code Double.MAX_VALUE}, then
1250 * the result is equal to 2<sup>971</sup>.
1251 * </ul>
1252 *
1253 * @param d the floating-point value whose ulp is to be returned
1254 * @return the size of an ulp of the argument
1255 * @author Joseph D. Darcy
|