1 /*
2 * Copyright (c) 2003, 2011, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package sun.misc;
27
28 import sun.misc.FloatConsts;
29 import sun.misc.DoubleConsts;
30
31 /**
32 * The class {@code FpUtils} contains static utility methods for
33 * manipulating and inspecting {@code float} and
34 * {@code double} floating-point numbers. These methods include
35 * functionality recommended or required by the IEEE 754
36 * floating-point standard.
37 *
38 * @author Joseph D. Darcy
39 */
40
41 public class FpUtils {
42 /*
43 * The methods in this class are reasonably implemented using
44 * direct or indirect bit-level manipulation of floating-point
45 * values. However, having access to the IEEE 754 recommended
46 * functions would obviate the need for most programmers to engage
47 * in floating-point bit-twiddling.
48 *
49 * An IEEE 754 number has three fields, from most significant bit
50 * to to least significant, sign, exponent, and significand.
51 *
52 * msb lsb
53 * [sign|exponent| fractional_significand]
54 *
55 * Using some encoding cleverness, explained below, the high order
56 * bit of the logical significand does not need to be explicitly
57 * stored, thus "fractional_significand" instead of simply
58 * "significand" in the figure above.
59 *
60 * For finite normal numbers, the numerical value encoded is
61 *
62 * (-1)^sign * 2^(exponent)*(1.fractional_significand)
63 *
64 * Most finite floating-point numbers are normalized; the exponent
65 * value is reduced until the leading significand bit is 1.
66 * Therefore, the leading 1 is redundant and is not explicitly
67 * stored. If a numerical value is so small it cannot be
68 * normalized, it has a subnormal representation. Subnormal
69 * numbers don't have a leading 1 in their significand; subnormals
70 * are encoding using a special exponent value. In other words,
71 * the high-order bit of the logical significand can be elided in
72 * from the representation in either case since the bit's value is
73 * implicit from the exponent value.
74 *
75 * The exponent field uses a biased representation; if the bits of
76 * the exponent are interpreted as a unsigned integer E, the
77 * exponent represented is E - E_bias where E_bias depends on the
78 * floating-point format. E can range between E_min and E_max,
79 * constants which depend on the floating-point format. E_min and
80 * E_max are -126 and +127 for float, -1022 and +1023 for double.
81 *
82 * The 32-bit float format has 1 sign bit, 8 exponent bits, and 23
83 * bits for the significand (which is logically 24 bits wide
84 * because of the implicit bit). The 64-bit double format has 1
85 * sign bit, 11 exponent bits, and 52 bits for the significand
86 * (logically 53 bits).
87 *
88 * Subnormal numbers and zero have the special exponent value
89 * E_min -1; the numerical value represented by a subnormal is:
90 *
91 * (-1)^sign * 2^(E_min)*(0.fractional_significand)
92 *
93 * Zero is represented by all zero bits in the exponent and all
94 * zero bits in the significand; zero can have either sign.
95 *
96 * Infinity and NaN are encoded using the exponent value E_max +
97 * 1. Signed infinities have all significand bits zero; NaNs have
98 * at least one non-zero significand bit.
99 *
100 * The details of IEEE 754 floating-point encoding will be used in
101 * the methods below without further comment. For further
102 * exposition on IEEE 754 numbers, see "IEEE Standard for Binary
103 * Floating-Point Arithmetic" ANSI/IEEE Std 754-1985 or William
104 * Kahan's "Lecture Notes on the Status of IEEE Standard 754 for
105 * Binary Floating-Point Arithmetic",
106 * http://www.cs.berkeley.edu/~wkahan/ieee754status/ieee754.ps.
107 *
108 * Many of this class's methods are members of the set of IEEE 754
109 * recommended functions or similar functions recommended or
110 * required by IEEE 754R. Discussion of various implementation
111 * techniques for these functions have occurred in:
112 *
113 * W.J. Cody and Jerome T. Coonen, "Algorithm 772 Functions to
114 * Support the IEEE Standard for Binary Floating-Point
115 * Arithmetic," ACM Transactions on Mathematical Software,
116 * vol. 19, no. 4, December 1993, pp. 443-451.
117 *
118 * Joseph D. Darcy, "Writing robust IEEE recommended functions in
119 * ``100% Pure Java''(TM)," University of California, Berkeley
120 * technical report UCB//CSD-98-1009.
121 */
122
123 /**
124 * Don't let anyone instantiate this class.
125 */
126 private FpUtils() {}
127
128 // Helper Methods
129
130 // The following helper methods are used in the implementation of
131 // the public recommended functions; they generally omit certain
132 // tests for exception cases.
133
134 /**
135 * Returns unbiased exponent of a {@code double}.
136 * @deprecated Use Math.getExponent.
137 */
138 @Deprecated
139 public static int getExponent(double d){
140 return Math.getExponent(d);
141 }
142
143 /**
144 * Returns unbiased exponent of a {@code float}.
145 * @deprecated Use Math.getExponent.
146 */
147 @Deprecated
148 public static int getExponent(float f){
149 return Math.getExponent(f);
150 }
151
152
153 /**
154 * Returns the first floating-point argument with the sign of the
155 * second floating-point argument. Note that unlike the {@link
156 * FpUtils#copySign(double, double) copySign} method, this method
157 * does not require NaN {@code sign} arguments to be treated
158 * as positive values; implementations are permitted to treat some
159 * NaN arguments as positive and other NaN arguments as negative
160 * to allow greater performance.
161 *
162 * @param magnitude the parameter providing the magnitude of the result
163 * @param sign the parameter providing the sign of the result
164 * @return a value with the magnitude of {@code magnitude}
165 * and the sign of {@code sign}.
166 * @author Joseph D. Darcy
167 * @deprecated Use Math.copySign.
168 */
169 @Deprecated
170 public static double rawCopySign(double magnitude, double sign) {
171 return Math.copySign(magnitude, sign);
172 }
173
174 /**
175 * Returns the first floating-point argument with the sign of the
176 * second floating-point argument. Note that unlike the {@link
177 * FpUtils#copySign(float, float) copySign} method, this method
178 * does not require NaN {@code sign} arguments to be treated
179 * as positive values; implementations are permitted to treat some
180 * NaN arguments as positive and other NaN arguments as negative
181 * to allow greater performance.
182 *
183 * @param magnitude the parameter providing the magnitude of the result
184 * @param sign the parameter providing the sign of the result
185 * @return a value with the magnitude of {@code magnitude}
186 * and the sign of {@code sign}.
187 * @author Joseph D. Darcy
188 * @deprecated Use Math.copySign.
189 */
190 @Deprecated
191 public static float rawCopySign(float magnitude, float sign) {
192 return Math.copySign(magnitude, sign);
193 }
194
195 /* ***************************************************************** */
196
197 /**
198 * Returns {@code true} if the argument is a finite
199 * floating-point value; returns {@code false} otherwise (for
200 * NaN and infinity arguments).
201 *
202 * @param d the {@code double} value to be tested
203 * @return {@code true} if the argument is a finite
204 * floating-point value, {@code false} otherwise.
205 * @deprecated Use Double.isFinite.
206 */
207 @Deprecated
208 public static boolean isFinite(double d) {
209 return Double.isFinite(d);
210 }
211
212 /**
213 * Returns {@code true} if the argument is a finite
214 * floating-point value; returns {@code false} otherwise (for
215 * NaN and infinity arguments).
216 *
217 * @param f the {@code float} value to be tested
218 * @return {@code true} if the argument is a finite
219 * floating-point value, {@code false} otherwise.
220 * @deprecated Use Float.isFinite.
221 */
222 @Deprecated
223 public static boolean isFinite(float f) {
224 return Float.isFinite(f);
225 }
226
227 /**
228 * Returns {@code true} if the specified number is infinitely
229 * large in magnitude, {@code false} otherwise.
230 *
231 * <p>Note that this method is equivalent to the {@link
232 * Double#isInfinite(double) Double.isInfinite} method; the
233 * functionality is included in this class for convenience.
234 *
235 * @param d the value to be tested.
236 * @return {@code true} if the value of the argument is positive
237 * infinity or negative infinity; {@code false} otherwise.
238 */
239 public static boolean isInfinite(double d) {
240 return Double.isInfinite(d);
241 }
242
243 /**
244 * Returns {@code true} if the specified number is infinitely
245 * large in magnitude, {@code false} otherwise.
246 *
247 * <p>Note that this method is equivalent to the {@link
248 * Float#isInfinite(float) Float.isInfinite} method; the
249 * functionality is included in this class for convenience.
250 *
251 * @param f the value to be tested.
252 * @return {@code true} if the argument is positive infinity or
253 * negative infinity; {@code false} otherwise.
254 */
255 public static boolean isInfinite(float f) {
256 return Float.isInfinite(f);
257 }
258
259 /**
260 * Returns {@code true} if the specified number is a
261 * Not-a-Number (NaN) value, {@code false} otherwise.
262 *
263 * <p>Note that this method is equivalent to the {@link
264 * Double#isNaN(double) Double.isNaN} method; the functionality is
265 * included in this class for convenience.
266 *
267 * @param d the value to be tested.
268 * @return {@code true} if the value of the argument is NaN;
269 * {@code false} otherwise.
270 */
271 public static boolean isNaN(double d) {
272 return Double.isNaN(d);
273 }
274
275 /**
276 * Returns {@code true} if the specified number is a
277 * Not-a-Number (NaN) value, {@code false} otherwise.
278 *
279 * <p>Note that this method is equivalent to the {@link
280 * Float#isNaN(float) Float.isNaN} method; the functionality is
281 * included in this class for convenience.
282 *
283 * @param f the value to be tested.
284 * @return {@code true} if the argument is NaN;
285 * {@code false} otherwise.
286 */
287 public static boolean isNaN(float f) {
288 return Float.isNaN(f);
289 }
290
291 /**
292 * Returns {@code true} if the unordered relation holds
293 * between the two arguments. When two floating-point values are
294 * unordered, one value is neither less than, equal to, nor
295 * greater than the other. For the unordered relation to be true,
296 * at least one argument must be a {@code NaN}.
297 *
298 * @param arg1 the first argument
299 * @param arg2 the second argument
300 * @return {@code true} if at least one argument is a NaN,
301 * {@code false} otherwise.
302 */
303 public static boolean isUnordered(double arg1, double arg2) {
304 return isNaN(arg1) || isNaN(arg2);
305 }
306
307 /**
308 * Returns {@code true} if the unordered relation holds
309 * between the two arguments. When two floating-point values are
310 * unordered, one value is neither less than, equal to, nor
311 * greater than the other. For the unordered relation to be true,
312 * at least one argument must be a {@code NaN}.
313 *
314 * @param arg1 the first argument
315 * @param arg2 the second argument
316 * @return {@code true} if at least one argument is a NaN,
317 * {@code false} otherwise.
318 */
319 public static boolean isUnordered(float arg1, float arg2) {
320 return isNaN(arg1) || isNaN(arg2);
321 }
322
323 /**
324 * Returns unbiased exponent of a {@code double}; for
325 * subnormal values, the number is treated as if it were
326 * normalized. That is for all finite, non-zero, positive numbers
327 * <i>x</i>, <code>scalb(<i>x</i>, -ilogb(<i>x</i>))</code> is
328 * always in the range [1, 2).
329 * <p>
330 * Special cases:
331 * <ul>
332 * <li> If the argument is NaN, then the result is 2<sup>30</sup>.
333 * <li> If the argument is infinite, then the result is 2<sup>28</sup>.
334 * <li> If the argument is zero, then the result is -(2<sup>28</sup>).
335 * </ul>
336 *
337 * @param d floating-point number whose exponent is to be extracted
338 * @return unbiased exponent of the argument.
339 * @author Joseph D. Darcy
340 */
341 public static int ilogb(double d) {
342 int exponent = getExponent(d);
343
344 switch (exponent) {
345 case DoubleConsts.MAX_EXPONENT+1: // NaN or infinity
346 if( isNaN(d) )
347 return (1<<30); // 2^30
348 else // infinite value
349 return (1<<28); // 2^28
350
351 case DoubleConsts.MIN_EXPONENT-1: // zero or subnormal
352 if(d == 0.0) {
353 return -(1<<28); // -(2^28)
354 }
355 else {
356 long transducer = Double.doubleToRawLongBits(d);
357
358 /*
359 * To avoid causing slow arithmetic on subnormals,
360 * the scaling to determine when d's significand
361 * is normalized is done in integer arithmetic.
362 * (there must be at least one "1" bit in the
363 * significand since zero has been screened out.
364 */
365
366 // isolate significand bits
367 transducer &= DoubleConsts.SIGNIF_BIT_MASK;
368 assert(transducer != 0L);
369
370 // This loop is simple and functional. We might be
371 // able to do something more clever that was faster;
372 // e.g. number of leading zero detection on
373 // (transducer << (# exponent and sign bits).
374 while (transducer <
375 (1L << (DoubleConsts.SIGNIFICAND_WIDTH - 1))) {
376 transducer *= 2;
377 exponent--;
378 }
379 exponent++;
380 assert( exponent >=
381 DoubleConsts.MIN_EXPONENT - (DoubleConsts.SIGNIFICAND_WIDTH-1) &&
382 exponent < DoubleConsts.MIN_EXPONENT);
383 return exponent;
384 }
385
386 default:
387 assert( exponent >= DoubleConsts.MIN_EXPONENT &&
388 exponent <= DoubleConsts.MAX_EXPONENT);
389 return exponent;
390 }
391 }
392
393 /**
394 * Returns unbiased exponent of a {@code float}; for
395 * subnormal values, the number is treated as if it were
396 * normalized. That is for all finite, non-zero, positive numbers
397 * <i>x</i>, <code>scalb(<i>x</i>, -ilogb(<i>x</i>))</code> is
398 * always in the range [1, 2).
399 * <p>
400 * Special cases:
401 * <ul>
402 * <li> If the argument is NaN, then the result is 2<sup>30</sup>.
403 * <li> If the argument is infinite, then the result is 2<sup>28</sup>.
404 * <li> If the argument is zero, then the result is -(2<sup>28</sup>).
405 * </ul>
406 *
407 * @param f floating-point number whose exponent is to be extracted
408 * @return unbiased exponent of the argument.
409 * @author Joseph D. Darcy
410 */
411 public static int ilogb(float f) {
412 int exponent = getExponent(f);
413
414 switch (exponent) {
415 case FloatConsts.MAX_EXPONENT+1: // NaN or infinity
416 if( isNaN(f) )
417 return (1<<30); // 2^30
418 else // infinite value
419 return (1<<28); // 2^28
420
421 case FloatConsts.MIN_EXPONENT-1: // zero or subnormal
422 if(f == 0.0f) {
423 return -(1<<28); // -(2^28)
424 }
425 else {
426 int transducer = Float.floatToRawIntBits(f);
427
428 /*
429 * To avoid causing slow arithmetic on subnormals,
430 * the scaling to determine when f's significand
431 * is normalized is done in integer arithmetic.
432 * (there must be at least one "1" bit in the
433 * significand since zero has been screened out.
434 */
435
436 // isolate significand bits
437 transducer &= FloatConsts.SIGNIF_BIT_MASK;
438 assert(transducer != 0);
439
440 // This loop is simple and functional. We might be
441 // able to do something more clever that was faster;
442 // e.g. number of leading zero detection on
443 // (transducer << (# exponent and sign bits).
444 while (transducer <
445 (1 << (FloatConsts.SIGNIFICAND_WIDTH - 1))) {
446 transducer *= 2;
447 exponent--;
448 }
449 exponent++;
450 assert( exponent >=
451 FloatConsts.MIN_EXPONENT - (FloatConsts.SIGNIFICAND_WIDTH-1) &&
452 exponent < FloatConsts.MIN_EXPONENT);
453 return exponent;
454 }
455
456 default:
457 assert( exponent >= FloatConsts.MIN_EXPONENT &&
458 exponent <= FloatConsts.MAX_EXPONENT);
459 return exponent;
460 }
461 }
462
463
464 /*
465 * The scalb operation should be reasonably fast; however, there
466 * are tradeoffs in writing a method to minimize the worst case
467 * performance and writing a method to minimize the time for
468 * expected common inputs. Some processors operate very slowly on
469 * subnormal operands, taking hundreds or thousands of cycles for
470 * one floating-point add or multiply as opposed to, say, four
471 * cycles for normal operands. For processors with very slow
472 * subnormal execution, scalb would be fastest if written entirely
473 * with integer operations; in other words, scalb would need to
474 * include the logic of performing correct rounding of subnormal
475 * values. This could be reasonably done in at most a few hundred
476 * cycles. However, this approach may penalize normal operations
477 * since at least the exponent of the floating-point argument must
478 * be examined.
479 *
480 * The approach taken in this implementation is a compromise.
481 * Floating-point multiplication is used to do most of the work;
482 * but knowingly multiplying by a subnormal scaling factor is
483 * avoided. However, the floating-point argument is not examined
484 * to see whether or not it is subnormal since subnormal inputs
485 * are assumed to be rare. At most three multiplies are needed to
486 * scale from the largest to smallest exponent ranges (scaling
487 * down, at most two multiplies are needed if subnormal scaling
488 * factors are allowed). However, in this implementation an
489 * expensive integer remainder operation is avoided at the cost of
490 * requiring five floating-point multiplies in the worst case,
491 * which should still be a performance win.
492 *
493 * If scaling of entire arrays is a concern, it would probably be
494 * more efficient to provide a double[] scalb(double[], int)
495 * version of scalb to avoid having to recompute the needed
496 * scaling factors for each floating-point value.
497 */
498
499 /**
500 * Return {@code d} ×
501 * 2<sup>{@code scale_factor}</sup> rounded as if performed
502 * by a single correctly rounded floating-point multiply to a
503 * member of the double value set. See section 4.2.3 of
504 * <cite>The Java™ Language Specification</cite>
505 * for a discussion of floating-point
506 * value sets. If the exponent of the result is between the
507 * {@code double}'s minimum exponent and maximum exponent,
508 * the answer is calculated exactly. If the exponent of the
509 * result would be larger than {@code doubles}'s maximum
510 * exponent, an infinity is returned. Note that if the result is
511 * subnormal, precision may be lost; that is, when {@code scalb(x,
512 * n)} is subnormal, {@code scalb(scalb(x, n), -n)} may
513 * not equal <i>x</i>. When the result is non-NaN, the result has
514 * the same sign as {@code d}.
515 *
516 *<p>
517 * Special cases:
518 * <ul>
519 * <li> If the first argument is NaN, NaN is returned.
520 * <li> If the first argument is infinite, then an infinity of the
521 * same sign is returned.
522 * <li> If the first argument is zero, then a zero of the same
523 * sign is returned.
524 * </ul>
525 *
526 * @param d number to be scaled by a power of two.
527 * @param scale_factor power of 2 used to scale {@code d}
528 * @return {@code d * }2<sup>{@code scale_factor}</sup>
529 * @author Joseph D. Darcy
530 * @deprecated Use Math.scalb.
531 */
532 @Deprecated
533 public static double scalb(double d, int scale_factor) {
534 return Math.scalb(d, scale_factor);
535 }
536
537 /**
538 * Return {@code f} ×
539 * 2<sup>{@code scale_factor}</sup> rounded as if performed
540 * by a single correctly rounded floating-point multiply to a
541 * member of the float value set. See section 4.2.3 of
542 * <cite>The Java™ Language Specification</cite>
543 * for a discussion of floating-point
544 * value sets. If the exponent of the result is between the
545 * {@code float}'s minimum exponent and maximum exponent, the
546 * answer is calculated exactly. If the exponent of the result
547 * would be larger than {@code float}'s maximum exponent, an
548 * infinity is returned. Note that if the result is subnormal,
549 * precision may be lost; that is, when {@code scalb(x, n)}
550 * is subnormal, {@code scalb(scalb(x, n), -n)} may not equal
551 * <i>x</i>. When the result is non-NaN, the result has the same
552 * sign as {@code f}.
553 *
554 *<p>
555 * Special cases:
556 * <ul>
557 * <li> If the first argument is NaN, NaN is returned.
558 * <li> If the first argument is infinite, then an infinity of the
559 * same sign is returned.
560 * <li> If the first argument is zero, then a zero of the same
561 * sign is returned.
562 * </ul>
563 *
564 * @param f number to be scaled by a power of two.
565 * @param scale_factor power of 2 used to scale {@code f}
566 * @return {@code f * }2<sup>{@code scale_factor}</sup>
567 * @author Joseph D. Darcy
568 * @deprecated Use Math.scalb.
569 */
570 @Deprecated
571 public static float scalb(float f, int scale_factor) {
572 return Math.scalb(f, scale_factor);
573 }
574
575 /**
576 * Returns the floating-point number adjacent to the first
577 * argument in the direction of the second argument. If both
578 * arguments compare as equal the second argument is returned.
579 *
580 * <p>
581 * Special cases:
582 * <ul>
583 * <li> If either argument is a NaN, then NaN is returned.
584 *
585 * <li> If both arguments are signed zeros, {@code direction}
586 * is returned unchanged (as implied by the requirement of
587 * returning the second argument if the arguments compare as
588 * equal).
589 *
590 * <li> If {@code start} is
591 * ±{@code Double.MIN_VALUE} and {@code direction}
592 * has a value such that the result should have a smaller
593 * magnitude, then a zero with the same sign as {@code start}
594 * is returned.
595 *
596 * <li> If {@code start} is infinite and
597 * {@code direction} has a value such that the result should
598 * have a smaller magnitude, {@code Double.MAX_VALUE} with the
599 * same sign as {@code start} is returned.
600 *
601 * <li> If {@code start} is equal to ±
602 * {@code Double.MAX_VALUE} and {@code direction} has a
603 * value such that the result should have a larger magnitude, an
604 * infinity with same sign as {@code start} is returned.
605 * </ul>
606 *
607 * @param start starting floating-point value
608 * @param direction value indicating which of
609 * {@code start}'s neighbors or {@code start} should
610 * be returned
611 * @return The floating-point number adjacent to {@code start} in the
612 * direction of {@code direction}.
613 * @author Joseph D. Darcy
614 * @deprecated Use Math.nextAfter
615 */
616 @Deprecated
617 public static double nextAfter(double start, double direction) {
618 return Math.nextAfter(start, direction);
619 }
620
621 /**
622 * Returns the floating-point number adjacent to the first
623 * argument in the direction of the second argument. If both
624 * arguments compare as equal, the second argument is returned.
625 *
626 * <p>
627 * Special cases:
628 * <ul>
629 * <li> If either argument is a NaN, then NaN is returned.
630 *
631 * <li> If both arguments are signed zeros, a {@code float}
632 * zero with the same sign as {@code direction} is returned
633 * (as implied by the requirement of returning the second argument
634 * if the arguments compare as equal).
635 *
636 * <li> If {@code start} is
637 * ±{@code Float.MIN_VALUE} and {@code direction}
638 * has a value such that the result should have a smaller
639 * magnitude, then a zero with the same sign as {@code start}
640 * is returned.
641 *
642 * <li> If {@code start} is infinite and
643 * {@code direction} has a value such that the result should
644 * have a smaller magnitude, {@code Float.MAX_VALUE} with the
645 * same sign as {@code start} is returned.
646 *
647 * <li> If {@code start} is equal to ±
648 * {@code Float.MAX_VALUE} and {@code direction} has a
649 * value such that the result should have a larger magnitude, an
650 * infinity with same sign as {@code start} is returned.
651 * </ul>
652 *
653 * @param start starting floating-point value
654 * @param direction value indicating which of
655 * {@code start}'s neighbors or {@code start} should
656 * be returned
657 * @return The floating-point number adjacent to {@code start} in the
658 * direction of {@code direction}.
659 * @author Joseph D. Darcy
660 * @deprecated Use Math.nextAfter.
661 */
662 @Deprecated
663 public static float nextAfter(float start, double direction) {
664 return Math.nextAfter(start, direction);
665 }
666
667 /**
668 * Returns the floating-point value adjacent to {@code d} in
669 * the direction of positive infinity. This method is
670 * semantically equivalent to {@code nextAfter(d,
671 * Double.POSITIVE_INFINITY)}; however, a {@code nextUp}
672 * implementation may run faster than its equivalent
673 * {@code nextAfter} call.
674 *
675 * <p>Special Cases:
676 * <ul>
677 * <li> If the argument is NaN, the result is NaN.
678 *
679 * <li> If the argument is positive infinity, the result is
680 * positive infinity.
681 *
682 * <li> If the argument is zero, the result is
683 * {@code Double.MIN_VALUE}
684 *
685 * </ul>
686 *
687 * @param d starting floating-point value
688 * @return The adjacent floating-point value closer to positive
689 * infinity.
690 * @author Joseph D. Darcy
691 * @deprecated use Math.nextUp.
692 */
693 @Deprecated
694 public static double nextUp(double d) {
695 return Math.nextUp(d);
696 }
697
698 /**
699 * Returns the floating-point value adjacent to {@code f} in
700 * the direction of positive infinity. This method is
701 * semantically equivalent to {@code nextAfter(f,
702 * Double.POSITIVE_INFINITY)}; however, a {@code nextUp}
703 * implementation may run faster than its equivalent
704 * {@code nextAfter} call.
705 *
706 * <p>Special Cases:
707 * <ul>
708 * <li> If the argument is NaN, the result is NaN.
709 *
710 * <li> If the argument is positive infinity, the result is
711 * positive infinity.
712 *
713 * <li> If the argument is zero, the result is
714 * {@code Float.MIN_VALUE}
715 *
716 * </ul>
717 *
718 * @param f starting floating-point value
719 * @return The adjacent floating-point value closer to positive
720 * infinity.
721 * @author Joseph D. Darcy
722 * @deprecated Use Math.nextUp.
723 */
724 @Deprecated
725 public static float nextUp(float f) {
726 return Math.nextUp(f);
727 }
728
729 /**
730 * Returns the floating-point value adjacent to {@code d} in
731 * the direction of negative infinity. This method is
732 * semantically equivalent to {@code nextAfter(d,
733 * Double.NEGATIVE_INFINITY)}; however, a
734 * {@code nextDown} implementation may run faster than its
735 * equivalent {@code nextAfter} call.
736 *
737 * <p>Special Cases:
738 * <ul>
739 * <li> If the argument is NaN, the result is NaN.
740 *
741 * <li> If the argument is negative infinity, the result is
742 * negative infinity.
743 *
744 * <li> If the argument is zero, the result is
745 * {@code -Double.MIN_VALUE}
746 *
747 * </ul>
748 *
749 * @param d starting floating-point value
750 * @return The adjacent floating-point value closer to negative
751 * infinity.
752 * @author Joseph D. Darcy
753 * @deprecated Use Math.nextDown.
754 */
755 @Deprecated
756 public static double nextDown(double d) {
757 return Math.nextDown(d);
758 }
759
760 /**
761 * Returns the floating-point value adjacent to {@code f} in
762 * the direction of negative infinity. This method is
763 * semantically equivalent to {@code nextAfter(f,
764 * Float.NEGATIVE_INFINITY)}; however, a
765 * {@code nextDown} implementation may run faster than its
766 * equivalent {@code nextAfter} call.
767 *
768 * <p>Special Cases:
769 * <ul>
770 * <li> If the argument is NaN, the result is NaN.
771 *
772 * <li> If the argument is negative infinity, the result is
773 * negative infinity.
774 *
775 * <li> If the argument is zero, the result is
776 * {@code -Float.MIN_VALUE}
777 *
778 * </ul>
779 *
780 * @param f starting floating-point value
781 * @return The adjacent floating-point value closer to negative
782 * infinity.
783 * @author Joseph D. Darcy
784 */
785 @Deprecated
786 public static double nextDown(float f) {
787 return Math.nextDown(f);
788 }
789
790 /**
791 * Returns the first floating-point argument with the sign of the
792 * second floating-point argument. For this method, a NaN
793 * {@code sign} argument is always treated as if it were
794 * positive.
795 *
796 * @param magnitude the parameter providing the magnitude of the result
797 * @param sign the parameter providing the sign of the result
798 * @return a value with the magnitude of {@code magnitude}
799 * and the sign of {@code sign}.
800 * @author Joseph D. Darcy
801 * @since 1.5
802 * @deprecated Use StrictMath.copySign.
803 */
804 @Deprecated
805 public static double copySign(double magnitude, double sign) {
806 return StrictMath.copySign(magnitude, sign);
807 }
808
809 /**
810 * Returns the first floating-point argument with the sign of the
811 * second floating-point argument. For this method, a NaN
812 * {@code sign} argument is always treated as if it were
813 * positive.
814 *
815 * @param magnitude the parameter providing the magnitude of the result
816 * @param sign the parameter providing the sign of the result
817 * @return a value with the magnitude of {@code magnitude}
818 * and the sign of {@code sign}.
819 * @author Joseph D. Darcy
820 * @deprecated Use StrictMath.copySign.
821 */
822 @Deprecated
823 public static float copySign(float magnitude, float sign) {
824 return StrictMath.copySign(magnitude, sign);
825 }
826
827 /**
828 * Returns the size of an ulp of the argument. An ulp of a
829 * {@code double} value is the positive distance between this
830 * floating-point value and the {@code double} value next
831 * larger in magnitude. Note that for non-NaN <i>x</i>,
832 * <code>ulp(-<i>x</i>) == ulp(<i>x</i>)</code>.
833 *
834 * <p>Special Cases:
835 * <ul>
836 * <li> If the argument is NaN, then the result is NaN.
837 * <li> If the argument is positive or negative infinity, then the
838 * result is positive infinity.
839 * <li> If the argument is positive or negative zero, then the result is
840 * {@code Double.MIN_VALUE}.
841 * <li> If the argument is ±{@code Double.MAX_VALUE}, then
842 * the result is equal to 2<sup>971</sup>.
843 * </ul>
844 *
845 * @param d the floating-point value whose ulp is to be returned
846 * @return the size of an ulp of the argument
847 * @author Joseph D. Darcy
848 * @since 1.5
849 * @deprecated Use Math.ulp.
850 */
851 @Deprecated
852 public static double ulp(double d) {
853 return Math.ulp(d);
854 }
855
856 /**
857 * Returns the size of an ulp of the argument. An ulp of a
858 * {@code float} value is the positive distance between this
859 * floating-point value and the {@code float} value next
860 * larger in magnitude. Note that for non-NaN <i>x</i>,
861 * <code>ulp(-<i>x</i>) == ulp(<i>x</i>)</code>.
862 *
863 * <p>Special Cases:
864 * <ul>
865 * <li> If the argument is NaN, then the result is NaN.
866 * <li> If the argument is positive or negative infinity, then the
867 * result is positive infinity.
868 * <li> If the argument is positive or negative zero, then the result is
869 * {@code Float.MIN_VALUE}.
870 * <li> If the argument is ±{@code Float.MAX_VALUE}, then
871 * the result is equal to 2<sup>104</sup>.
872 * </ul>
873 *
874 * @param f the floating-point value whose ulp is to be returned
875 * @return the size of an ulp of the argument
876 * @author Joseph D. Darcy
877 * @since 1.5
878 * @deprecated Use Math.ulp.
879 */
880 @Deprecated
881 public static float ulp(float f) {
882 return Math.ulp(f);
883 }
884
885 /**
886 * Returns the signum function of the argument; zero if the argument
887 * is zero, 1.0 if the argument is greater than zero, -1.0 if the
888 * argument is less than zero.
889 *
890 * <p>Special Cases:
891 * <ul>
892 * <li> If the argument is NaN, then the result is NaN.
893 * <li> If the argument is positive zero or negative zero, then the
894 * result is the same as the argument.
895 * </ul>
896 *
897 * @param d the floating-point value whose signum is to be returned
898 * @return the signum function of the argument
899 * @author Joseph D. Darcy
900 * @since 1.5
901 * @deprecated Use Math.signum.
902 */
903 @Deprecated
904 public static double signum(double d) {
905 return Math.signum(d);
906 }
907
908 /**
909 * Returns the signum function of the argument; zero if the argument
910 * is zero, 1.0f if the argument is greater than zero, -1.0f if the
911 * argument is less than zero.
912 *
913 * <p>Special Cases:
914 * <ul>
915 * <li> If the argument is NaN, then the result is NaN.
916 * <li> If the argument is positive zero or negative zero, then the
917 * result is the same as the argument.
918 * </ul>
919 *
920 * @param f the floating-point value whose signum is to be returned
921 * @return the signum function of the argument
922 * @author Joseph D. Darcy
923 * @since 1.5
924 * @deprecated Use Math.signum.
925 */
926 @Deprecated
927 public static float signum(float f) {
928 return Math.signum(f);
929 }
930 }