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 */
206 public static boolean isFinite(double d) {
207 return Math.abs(d) <= DoubleConsts.MAX_VALUE;
208 }
209
210 /**
211 * Returns {@code true} if the argument is a finite
212 * floating-point value; returns {@code false} otherwise (for
213 * NaN and infinity arguments).
214 *
215 * @param f the {@code float} value to be tested
216 * @return {@code true} if the argument is a finite
217 * floating-point value, {@code false} otherwise.
218 */
219 public static boolean isFinite(float f) {
220 return Math.abs(f) <= FloatConsts.MAX_VALUE;
221 }
222
223 /**
224 * Returns {@code true} if the specified number is infinitely
225 * large in magnitude, {@code false} otherwise.
226 *
227 * <p>Note that this method is equivalent to the {@link
228 * Double#isInfinite(double) Double.isInfinite} method; the
229 * functionality is included in this class for convenience.
230 *
231 * @param d the value to be tested.
232 * @return {@code true} if the value of the argument is positive
233 * infinity or negative infinity; {@code false} otherwise.
234 */
235 public static boolean isInfinite(double d) {
236 return Double.isInfinite(d);
237 }
238
239 /**
240 * Returns {@code true} if the specified number is infinitely
241 * large in magnitude, {@code false} otherwise.
242 *
243 * <p>Note that this method is equivalent to the {@link
244 * Float#isInfinite(float) Float.isInfinite} method; the
245 * functionality is included in this class for convenience.
246 *
247 * @param f the value to be tested.
248 * @return {@code true} if the argument is positive infinity or
249 * negative infinity; {@code false} otherwise.
250 */
251 public static boolean isInfinite(float f) {
252 return Float.isInfinite(f);
253 }
254
255 /**
256 * Returns {@code true} if the specified number is a
257 * Not-a-Number (NaN) value, {@code false} otherwise.
258 *
259 * <p>Note that this method is equivalent to the {@link
260 * Double#isNaN(double) Double.isNaN} method; the functionality is
261 * included in this class for convenience.
262 *
263 * @param d the value to be tested.
264 * @return {@code true} if the value of the argument is NaN;
265 * {@code false} otherwise.
266 */
267 public static boolean isNaN(double d) {
268 return Double.isNaN(d);
269 }
270
271 /**
272 * Returns {@code true} if the specified number is a
273 * Not-a-Number (NaN) value, {@code false} otherwise.
274 *
275 * <p>Note that this method is equivalent to the {@link
276 * Float#isNaN(float) Float.isNaN} method; the functionality is
277 * included in this class for convenience.
278 *
279 * @param f the value to be tested.
280 * @return {@code true} if the argument is NaN;
281 * {@code false} otherwise.
282 */
283 public static boolean isNaN(float f) {
284 return Float.isNaN(f);
285 }
286
287 /**
288 * Returns {@code true} if the unordered relation holds
289 * between the two arguments. When two floating-point values are
290 * unordered, one value is neither less than, equal to, nor
291 * greater than the other. For the unordered relation to be true,
292 * at least one argument must be a {@code NaN}.
293 *
294 * @param arg1 the first argument
295 * @param arg2 the second argument
296 * @return {@code true} if at least one argument is a NaN,
297 * {@code false} otherwise.
298 */
299 public static boolean isUnordered(double arg1, double arg2) {
300 return isNaN(arg1) || isNaN(arg2);
301 }
302
303 /**
304 * Returns {@code true} if the unordered relation holds
305 * between the two arguments. When two floating-point values are
306 * unordered, one value is neither less than, equal to, nor
307 * greater than the other. For the unordered relation to be true,
308 * at least one argument must be a {@code NaN}.
309 *
310 * @param arg1 the first argument
311 * @param arg2 the second argument
312 * @return {@code true} if at least one argument is a NaN,
313 * {@code false} otherwise.
314 */
315 public static boolean isUnordered(float arg1, float arg2) {
316 return isNaN(arg1) || isNaN(arg2);
317 }
318
319 /**
320 * Returns unbiased exponent of a {@code double}; for
321 * subnormal values, the number is treated as if it were
322 * normalized. That is for all finite, non-zero, positive numbers
323 * <i>x</i>, <code>scalb(<i>x</i>, -ilogb(<i>x</i>))</code> is
324 * always in the range [1, 2).
325 * <p>
326 * Special cases:
327 * <ul>
328 * <li> If the argument is NaN, then the result is 2<sup>30</sup>.
329 * <li> If the argument is infinite, then the result is 2<sup>28</sup>.
330 * <li> If the argument is zero, then the result is -(2<sup>28</sup>).
331 * </ul>
332 *
333 * @param d floating-point number whose exponent is to be extracted
334 * @return unbiased exponent of the argument.
335 * @author Joseph D. Darcy
336 */
337 public static int ilogb(double d) {
338 int exponent = getExponent(d);
339
340 switch (exponent) {
341 case DoubleConsts.MAX_EXPONENT+1: // NaN or infinity
342 if( isNaN(d) )
343 return (1<<30); // 2^30
344 else // infinite value
345 return (1<<28); // 2^28
346
347 case DoubleConsts.MIN_EXPONENT-1: // zero or subnormal
348 if(d == 0.0) {
349 return -(1<<28); // -(2^28)
350 }
351 else {
352 long transducer = Double.doubleToRawLongBits(d);
353
354 /*
355 * To avoid causing slow arithmetic on subnormals,
356 * the scaling to determine when d's significand
357 * is normalized is done in integer arithmetic.
358 * (there must be at least one "1" bit in the
359 * significand since zero has been screened out.
360 */
361
362 // isolate significand bits
363 transducer &= DoubleConsts.SIGNIF_BIT_MASK;
364 assert(transducer != 0L);
365
366 // This loop is simple and functional. We might be
367 // able to do something more clever that was faster;
368 // e.g. number of leading zero detection on
369 // (transducer << (# exponent and sign bits).
370 while (transducer <
371 (1L << (DoubleConsts.SIGNIFICAND_WIDTH - 1))) {
372 transducer *= 2;
373 exponent--;
374 }
375 exponent++;
376 assert( exponent >=
377 DoubleConsts.MIN_EXPONENT - (DoubleConsts.SIGNIFICAND_WIDTH-1) &&
378 exponent < DoubleConsts.MIN_EXPONENT);
379 return exponent;
380 }
381
382 default:
383 assert( exponent >= DoubleConsts.MIN_EXPONENT &&
384 exponent <= DoubleConsts.MAX_EXPONENT);
385 return exponent;
386 }
387 }
388
389 /**
390 * Returns unbiased exponent of a {@code float}; for
391 * subnormal values, the number is treated as if it were
392 * normalized. That is for all finite, non-zero, positive numbers
393 * <i>x</i>, <code>scalb(<i>x</i>, -ilogb(<i>x</i>))</code> is
394 * always in the range [1, 2).
395 * <p>
396 * Special cases:
397 * <ul>
398 * <li> If the argument is NaN, then the result is 2<sup>30</sup>.
399 * <li> If the argument is infinite, then the result is 2<sup>28</sup>.
400 * <li> If the argument is zero, then the result is -(2<sup>28</sup>).
401 * </ul>
402 *
403 * @param f floating-point number whose exponent is to be extracted
404 * @return unbiased exponent of the argument.
405 * @author Joseph D. Darcy
406 */
407 public static int ilogb(float f) {
408 int exponent = getExponent(f);
409
410 switch (exponent) {
411 case FloatConsts.MAX_EXPONENT+1: // NaN or infinity
412 if( isNaN(f) )
413 return (1<<30); // 2^30
414 else // infinite value
415 return (1<<28); // 2^28
416
417 case FloatConsts.MIN_EXPONENT-1: // zero or subnormal
418 if(f == 0.0f) {
419 return -(1<<28); // -(2^28)
420 }
421 else {
422 int transducer = Float.floatToRawIntBits(f);
423
424 /*
425 * To avoid causing slow arithmetic on subnormals,
426 * the scaling to determine when f's significand
427 * is normalized is done in integer arithmetic.
428 * (there must be at least one "1" bit in the
429 * significand since zero has been screened out.
430 */
431
432 // isolate significand bits
433 transducer &= FloatConsts.SIGNIF_BIT_MASK;
434 assert(transducer != 0);
435
436 // This loop is simple and functional. We might be
437 // able to do something more clever that was faster;
438 // e.g. number of leading zero detection on
439 // (transducer << (# exponent and sign bits).
440 while (transducer <
441 (1 << (FloatConsts.SIGNIFICAND_WIDTH - 1))) {
442 transducer *= 2;
443 exponent--;
444 }
445 exponent++;
446 assert( exponent >=
447 FloatConsts.MIN_EXPONENT - (FloatConsts.SIGNIFICAND_WIDTH-1) &&
448 exponent < FloatConsts.MIN_EXPONENT);
449 return exponent;
450 }
451
452 default:
453 assert( exponent >= FloatConsts.MIN_EXPONENT &&
454 exponent <= FloatConsts.MAX_EXPONENT);
455 return exponent;
456 }
457 }
458
459
460 /*
461 * The scalb operation should be reasonably fast; however, there
462 * are tradeoffs in writing a method to minimize the worst case
463 * performance and writing a method to minimize the time for
464 * expected common inputs. Some processors operate very slowly on
465 * subnormal operands, taking hundreds or thousands of cycles for
466 * one floating-point add or multiply as opposed to, say, four
467 * cycles for normal operands. For processors with very slow
468 * subnormal execution, scalb would be fastest if written entirely
469 * with integer operations; in other words, scalb would need to
470 * include the logic of performing correct rounding of subnormal
471 * values. This could be reasonably done in at most a few hundred
472 * cycles. However, this approach may penalize normal operations
473 * since at least the exponent of the floating-point argument must
474 * be examined.
475 *
476 * The approach taken in this implementation is a compromise.
477 * Floating-point multiplication is used to do most of the work;
478 * but knowingly multiplying by a subnormal scaling factor is
479 * avoided. However, the floating-point argument is not examined
480 * to see whether or not it is subnormal since subnormal inputs
481 * are assumed to be rare. At most three multiplies are needed to
482 * scale from the largest to smallest exponent ranges (scaling
483 * down, at most two multiplies are needed if subnormal scaling
484 * factors are allowed). However, in this implementation an
485 * expensive integer remainder operation is avoided at the cost of
486 * requiring five floating-point multiplies in the worst case,
487 * which should still be a performance win.
488 *
489 * If scaling of entire arrays is a concern, it would probably be
490 * more efficient to provide a double[] scalb(double[], int)
491 * version of scalb to avoid having to recompute the needed
492 * scaling factors for each floating-point value.
493 */
494
495 /**
496 * Return {@code d} ×
497 * 2<sup>{@code scale_factor}</sup> rounded as if performed
498 * by a single correctly rounded floating-point multiply to a
499 * member of the double value set. See section 4.2.3 of
500 * <cite>The Java™ Language Specification</cite>
501 * for a discussion of floating-point
502 * value sets. If the exponent of the result is between the
503 * {@code double}'s minimum exponent and maximum exponent,
504 * the answer is calculated exactly. If the exponent of the
505 * result would be larger than {@code doubles}'s maximum
506 * exponent, an infinity is returned. Note that if the result is
507 * subnormal, precision may be lost; that is, when {@code scalb(x,
508 * n)} is subnormal, {@code scalb(scalb(x, n), -n)} may
509 * not equal <i>x</i>. When the result is non-NaN, the result has
510 * the same sign as {@code d}.
511 *
512 *<p>
513 * Special cases:
514 * <ul>
515 * <li> If the first argument is NaN, NaN is returned.
516 * <li> If the first argument is infinite, then an infinity of the
517 * same sign is returned.
518 * <li> If the first argument is zero, then a zero of the same
519 * sign is returned.
520 * </ul>
521 *
522 * @param d number to be scaled by a power of two.
523 * @param scale_factor power of 2 used to scale {@code d}
524 * @return {@code d * }2<sup>{@code scale_factor}</sup>
525 * @author Joseph D. Darcy
526 * @deprecated Use Math.scalb.
527 */
528 @Deprecated
529 public static double scalb(double d, int scale_factor) {
530 return Math.scalb(d, scale_factor);
531 }
532
533 /**
534 * Return {@code f} ×
535 * 2<sup>{@code scale_factor}</sup> rounded as if performed
536 * by a single correctly rounded floating-point multiply to a
537 * member of the float value set. See section 4.2.3 of
538 * <cite>The Java™ Language Specification</cite>
539 * for a discussion of floating-point
540 * value sets. If the exponent of the result is between the
541 * {@code float}'s minimum exponent and maximum exponent, the
542 * answer is calculated exactly. If the exponent of the result
543 * would be larger than {@code float}'s maximum exponent, an
544 * infinity is returned. Note that if the result is subnormal,
545 * precision may be lost; that is, when {@code scalb(x, n)}
546 * is subnormal, {@code scalb(scalb(x, n), -n)} may not equal
547 * <i>x</i>. When the result is non-NaN, the result has the same
548 * sign as {@code f}.
549 *
550 *<p>
551 * Special cases:
552 * <ul>
553 * <li> If the first argument is NaN, NaN is returned.
554 * <li> If the first argument is infinite, then an infinity of the
555 * same sign is returned.
556 * <li> If the first argument is zero, then a zero of the same
557 * sign is returned.
558 * </ul>
559 *
560 * @param f number to be scaled by a power of two.
561 * @param scale_factor power of 2 used to scale {@code f}
562 * @return {@code f * }2<sup>{@code scale_factor}</sup>
563 * @author Joseph D. Darcy
564 * @deprecated Use Math.scalb.
565 */
566 @Deprecated
567 public static float scalb(float f, int scale_factor) {
568 return Math.scalb(f, scale_factor);
569 }
570
571 /**
572 * Returns the floating-point number adjacent to the first
573 * argument in the direction of the second argument. If both
574 * arguments compare as equal the second argument is returned.
575 *
576 * <p>
577 * Special cases:
578 * <ul>
579 * <li> If either argument is a NaN, then NaN is returned.
580 *
581 * <li> If both arguments are signed zeros, {@code direction}
582 * is returned unchanged (as implied by the requirement of
583 * returning the second argument if the arguments compare as
584 * equal).
585 *
586 * <li> If {@code start} is
587 * ±{@code Double.MIN_VALUE} and {@code direction}
588 * has a value such that the result should have a smaller
589 * magnitude, then a zero with the same sign as {@code start}
590 * is returned.
591 *
592 * <li> If {@code start} is infinite and
593 * {@code direction} has a value such that the result should
594 * have a smaller magnitude, {@code Double.MAX_VALUE} with the
595 * same sign as {@code start} is returned.
596 *
597 * <li> If {@code start} is equal to ±
598 * {@code Double.MAX_VALUE} and {@code direction} has a
599 * value such that the result should have a larger magnitude, an
600 * infinity with same sign as {@code start} is returned.
601 * </ul>
602 *
603 * @param start starting floating-point value
604 * @param direction value indicating which of
605 * {@code start}'s neighbors or {@code start} should
606 * be returned
607 * @return The floating-point number adjacent to {@code start} in the
608 * direction of {@code direction}.
609 * @author Joseph D. Darcy
610 * @deprecated Use Math.nextAfter
611 */
612 @Deprecated
613 public static double nextAfter(double start, double direction) {
614 return Math.nextAfter(start, direction);
615 }
616
617 /**
618 * Returns the floating-point number adjacent to the first
619 * argument in the direction of the second argument. If both
620 * arguments compare as equal, the second argument is returned.
621 *
622 * <p>
623 * Special cases:
624 * <ul>
625 * <li> If either argument is a NaN, then NaN is returned.
626 *
627 * <li> If both arguments are signed zeros, a {@code float}
628 * zero with the same sign as {@code direction} is returned
629 * (as implied by the requirement of returning the second argument
630 * if the arguments compare as equal).
631 *
632 * <li> If {@code start} is
633 * ±{@code Float.MIN_VALUE} and {@code direction}
634 * has a value such that the result should have a smaller
635 * magnitude, then a zero with the same sign as {@code start}
636 * is returned.
637 *
638 * <li> If {@code start} is infinite and
639 * {@code direction} has a value such that the result should
640 * have a smaller magnitude, {@code Float.MAX_VALUE} with the
641 * same sign as {@code start} is returned.
642 *
643 * <li> If {@code start} is equal to ±
644 * {@code Float.MAX_VALUE} and {@code direction} has a
645 * value such that the result should have a larger magnitude, an
646 * infinity with same sign as {@code start} is returned.
647 * </ul>
648 *
649 * @param start starting floating-point value
650 * @param direction value indicating which of
651 * {@code start}'s neighbors or {@code start} should
652 * be returned
653 * @return The floating-point number adjacent to {@code start} in the
654 * direction of {@code direction}.
655 * @author Joseph D. Darcy
656 * @deprecated Use Math.nextAfter.
657 */
658 @Deprecated
659 public static float nextAfter(float start, double direction) {
660 return Math.nextAfter(start, direction);
661 }
662
663 /**
664 * Returns the floating-point value adjacent to {@code d} in
665 * the direction of positive infinity. This method is
666 * semantically equivalent to {@code nextAfter(d,
667 * Double.POSITIVE_INFINITY)}; however, a {@code nextUp}
668 * implementation may run faster than its equivalent
669 * {@code nextAfter} call.
670 *
671 * <p>Special Cases:
672 * <ul>
673 * <li> If the argument is NaN, the result is NaN.
674 *
675 * <li> If the argument is positive infinity, the result is
676 * positive infinity.
677 *
678 * <li> If the argument is zero, the result is
679 * {@code Double.MIN_VALUE}
680 *
681 * </ul>
682 *
683 * @param d starting floating-point value
684 * @return The adjacent floating-point value closer to positive
685 * infinity.
686 * @author Joseph D. Darcy
687 * @deprecated use Math.nextUp.
688 */
689 @Deprecated
690 public static double nextUp(double d) {
691 return Math.nextUp(d);
692 }
693
694 /**
695 * Returns the floating-point value adjacent to {@code f} in
696 * the direction of positive infinity. This method is
697 * semantically equivalent to {@code nextAfter(f,
698 * Double.POSITIVE_INFINITY)}; however, a {@code nextUp}
699 * implementation may run faster than its equivalent
700 * {@code nextAfter} call.
701 *
702 * <p>Special Cases:
703 * <ul>
704 * <li> If the argument is NaN, the result is NaN.
705 *
706 * <li> If the argument is positive infinity, the result is
707 * positive infinity.
708 *
709 * <li> If the argument is zero, the result is
710 * {@code Float.MIN_VALUE}
711 *
712 * </ul>
713 *
714 * @param f starting floating-point value
715 * @return The adjacent floating-point value closer to positive
716 * infinity.
717 * @author Joseph D. Darcy
718 * @deprecated Use Math.nextUp.
719 */
720 @Deprecated
721 public static float nextUp(float f) {
722 return Math.nextUp(f);
723 }
724
725 /**
726 * Returns the floating-point value adjacent to {@code d} in
727 * the direction of negative infinity. This method is
728 * semantically equivalent to {@code nextAfter(d,
729 * Double.NEGATIVE_INFINITY)}; however, a
730 * {@code nextDown} implementation may run faster than its
731 * equivalent {@code nextAfter} call.
732 *
733 * <p>Special Cases:
734 * <ul>
735 * <li> If the argument is NaN, the result is NaN.
736 *
737 * <li> If the argument is negative infinity, the result is
738 * negative infinity.
739 *
740 * <li> If the argument is zero, the result is
741 * {@code -Double.MIN_VALUE}
742 *
743 * </ul>
744 *
745 * @param d starting floating-point value
746 * @return The adjacent floating-point value closer to negative
747 * infinity.
748 * @author Joseph D. Darcy
749 */
750 public static double nextDown(double d) {
751 if( isNaN(d) || d == Double.NEGATIVE_INFINITY)
752 return d;
753 else {
754 if (d == 0.0)
755 return -Double.MIN_VALUE;
756 else
757 return Double.longBitsToDouble(Double.doubleToRawLongBits(d) +
758 ((d > 0.0d)?-1L:+1L));
759 }
760 }
761
762 /**
763 * Returns the floating-point value adjacent to {@code f} in
764 * the direction of negative infinity. This method is
765 * semantically equivalent to {@code nextAfter(f,
766 * Float.NEGATIVE_INFINITY)}; however, a
767 * {@code nextDown} implementation may run faster than its
768 * equivalent {@code nextAfter} call.
769 *
770 * <p>Special Cases:
771 * <ul>
772 * <li> If the argument is NaN, the result is NaN.
773 *
774 * <li> If the argument is negative infinity, the result is
775 * negative infinity.
776 *
777 * <li> If the argument is zero, the result is
778 * {@code -Float.MIN_VALUE}
779 *
780 * </ul>
781 *
782 * @param f starting floating-point value
783 * @return The adjacent floating-point value closer to negative
784 * infinity.
785 * @author Joseph D. Darcy
786 */
787 public static double nextDown(float f) {
788 if( isNaN(f) || f == Float.NEGATIVE_INFINITY)
789 return f;
790 else {
791 if (f == 0.0f)
792 return -Float.MIN_VALUE;
793 else
794 return Float.intBitsToFloat(Float.floatToRawIntBits(f) +
795 ((f > 0.0f)?-1:+1));
796 }
797 }
798
799 /**
800 * Returns the first floating-point argument with the sign of the
801 * second floating-point argument. For this method, a NaN
802 * {@code sign} argument is always treated as if it were
803 * positive.
804 *
805 * @param magnitude the parameter providing the magnitude of the result
806 * @param sign the parameter providing the sign of the result
807 * @return a value with the magnitude of {@code magnitude}
808 * and the sign of {@code sign}.
809 * @author Joseph D. Darcy
810 * @since 1.5
811 * @deprecated Use StrictMath.copySign.
812 */
813 @Deprecated
814 public static double copySign(double magnitude, double sign) {
815 return StrictMath.copySign(magnitude, sign);
816 }
817
818 /**
819 * Returns the first floating-point argument with the sign of the
820 * second floating-point argument. For this method, a NaN
821 * {@code sign} argument is always treated as if it were
822 * positive.
823 *
824 * @param magnitude the parameter providing the magnitude of the result
825 * @param sign the parameter providing the sign of the result
826 * @return a value with the magnitude of {@code magnitude}
827 * and the sign of {@code sign}.
828 * @author Joseph D. Darcy
829 * @deprecated Use StrictMath.copySign.
830 */
831 @Deprecated
832 public static float copySign(float magnitude, float sign) {
833 return StrictMath.copySign(magnitude, sign);
834 }
835
836 /**
837 * Returns the size of an ulp of the argument. An ulp of a
838 * {@code double} value is the positive distance between this
839 * floating-point value and the {@code double} value next
840 * larger in magnitude. Note that for non-NaN <i>x</i>,
841 * <code>ulp(-<i>x</i>) == ulp(<i>x</i>)</code>.
842 *
843 * <p>Special Cases:
844 * <ul>
845 * <li> If the argument is NaN, then the result is NaN.
846 * <li> If the argument is positive or negative infinity, then the
847 * result is positive infinity.
848 * <li> If the argument is positive or negative zero, then the result is
849 * {@code Double.MIN_VALUE}.
850 * <li> If the argument is ±{@code Double.MAX_VALUE}, then
851 * the result is equal to 2<sup>971</sup>.
852 * </ul>
853 *
854 * @param d the floating-point value whose ulp is to be returned
855 * @return the size of an ulp of the argument
856 * @author Joseph D. Darcy
857 * @since 1.5
858 * @deprecated Use Math.ulp.
859 */
860 @Deprecated
861 public static double ulp(double d) {
862 return Math.ulp(d);
863 }
864
865 /**
866 * Returns the size of an ulp of the argument. An ulp of a
867 * {@code float} value is the positive distance between this
868 * floating-point value and the {@code float} value next
869 * larger in magnitude. Note that for non-NaN <i>x</i>,
870 * <code>ulp(-<i>x</i>) == ulp(<i>x</i>)</code>.
871 *
872 * <p>Special Cases:
873 * <ul>
874 * <li> If the argument is NaN, then the result is NaN.
875 * <li> If the argument is positive or negative infinity, then the
876 * result is positive infinity.
877 * <li> If the argument is positive or negative zero, then the result is
878 * {@code Float.MIN_VALUE}.
879 * <li> If the argument is ±{@code Float.MAX_VALUE}, then
880 * the result is equal to 2<sup>104</sup>.
881 * </ul>
882 *
883 * @param f the floating-point value whose ulp is to be returned
884 * @return the size of an ulp of the argument
885 * @author Joseph D. Darcy
886 * @since 1.5
887 * @deprecated Use Math.ulp.
888 */
889 @Deprecated
890 public static float ulp(float f) {
891 return Math.ulp(f);
892 }
893
894 /**
895 * Returns the signum function of the argument; zero if the argument
896 * is zero, 1.0 if the argument is greater than zero, -1.0 if the
897 * argument is less than zero.
898 *
899 * <p>Special Cases:
900 * <ul>
901 * <li> If the argument is NaN, then the result is NaN.
902 * <li> If the argument is positive zero or negative zero, then the
903 * result is the same as the argument.
904 * </ul>
905 *
906 * @param d the floating-point value whose signum is to be returned
907 * @return the signum function of the argument
908 * @author Joseph D. Darcy
909 * @since 1.5
910 * @deprecated Use Math.signum.
911 */
912 @Deprecated
913 public static double signum(double d) {
914 return Math.signum(d);
915 }
916
917 /**
918 * Returns the signum function of the argument; zero if the argument
919 * is zero, 1.0f if the argument is greater than zero, -1.0f if the
920 * argument is less than zero.
921 *
922 * <p>Special Cases:
923 * <ul>
924 * <li> If the argument is NaN, then the result is NaN.
925 * <li> If the argument is positive zero or negative zero, then the
926 * result is the same as the argument.
927 * </ul>
928 *
929 * @param f the floating-point value whose signum is to be returned
930 * @return the signum function of the argument
931 * @author Joseph D. Darcy
932 * @since 1.5
933 * @deprecated Use Math.signum.
934 */
935 @Deprecated
936 public static float signum(float f) {
937 return Math.signum(f);
938 }
939 }