View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.lang3.math;
18  
19  import java.lang.reflect.Array;
20  import java.math.BigDecimal;
21  import java.math.BigInteger;
22  import java.math.RoundingMode;
23  
24  import org.apache.commons.lang3.StringUtils;
25  import org.apache.commons.lang3.Validate;
26  
27  /**
28   * <p>Provides extra functionality for Java Number classes.</p>
29   *
30   * @since 2.0
31   */
32  public class NumberUtils {
33  
34      /** Reusable Long constant for zero. */
35      public static final Long LONG_ZERO = Long.valueOf(0L);
36      /** Reusable Long constant for one. */
37      public static final Long LONG_ONE = Long.valueOf(1L);
38      /** Reusable Long constant for minus one. */
39      public static final Long LONG_MINUS_ONE = Long.valueOf(-1L);
40      /** Reusable Integer constant for zero. */
41      public static final Integer INTEGER_ZERO = Integer.valueOf(0);
42      /** Reusable Integer constant for one. */
43      public static final Integer INTEGER_ONE = Integer.valueOf(1);
44      /** Reusable Integer constant for two */
45      public static final Integer INTEGER_TWO = Integer.valueOf(2);
46      /** Reusable Integer constant for minus one. */
47      public static final Integer INTEGER_MINUS_ONE = Integer.valueOf(-1);
48      /** Reusable Short constant for zero. */
49      public static final Short SHORT_ZERO = Short.valueOf((short) 0);
50      /** Reusable Short constant for one. */
51      public static final Short SHORT_ONE = Short.valueOf((short) 1);
52      /** Reusable Short constant for minus one. */
53      public static final Short SHORT_MINUS_ONE = Short.valueOf((short) -1);
54      /** Reusable Byte constant for zero. */
55      public static final Byte BYTE_ZERO = Byte.valueOf((byte) 0);
56      /** Reusable Byte constant for one. */
57      public static final Byte BYTE_ONE = Byte.valueOf((byte) 1);
58      /** Reusable Byte constant for minus one. */
59      public static final Byte BYTE_MINUS_ONE = Byte.valueOf((byte) -1);
60      /** Reusable Double constant for zero. */
61      public static final Double DOUBLE_ZERO = Double.valueOf(0.0d);
62      /** Reusable Double constant for one. */
63      public static final Double DOUBLE_ONE = Double.valueOf(1.0d);
64      /** Reusable Double constant for minus one. */
65      public static final Double DOUBLE_MINUS_ONE = Double.valueOf(-1.0d);
66      /** Reusable Float constant for zero. */
67      public static final Float FLOAT_ZERO = Float.valueOf(0.0f);
68      /** Reusable Float constant for one. */
69      public static final Float FLOAT_ONE = Float.valueOf(1.0f);
70      /** Reusable Float constant for minus one. */
71      public static final Float FLOAT_MINUS_ONE = Float.valueOf(-1.0f);
72  
73      /**
74       * {@link Integer#MAX_VALUE} as a {@link Long}.
75       *
76       * @since 3.12.0
77       */
78      public static final Long LONG_INT_MAX_VALUE = Long.valueOf(Integer.MAX_VALUE);
79  
80      /**
81       * {@link Integer#MIN_VALUE} as a {@link Long}.
82       *
83       * @since 3.12.0
84       */
85      public static final Long LONG_INT_MIN_VALUE = Long.valueOf(Integer.MIN_VALUE);
86  
87  
88      /**
89       * <p>{@code NumberUtils} instances should NOT be constructed in standard programming.
90       * Instead, the class should be used as {@code NumberUtils.toInt("6");}.</p>
91       *
92       * <p>This constructor is public to permit tools that require a JavaBean instance
93       * to operate.</p>
94       */
95      public NumberUtils() {
96      }
97  
98      //-----------------------------------------------------------------------
99      /**
100      * <p>Convert a {@code String} to an {@code int}, returning
101      * {@code zero} if the conversion fails.</p>
102      *
103      * <p>If the string is {@code null}, {@code zero} is returned.</p>
104      *
105      * <pre>
106      *   NumberUtils.toInt(null) = 0
107      *   NumberUtils.toInt("")   = 0
108      *   NumberUtils.toInt("1")  = 1
109      * </pre>
110      *
111      * @param str  the string to convert, may be null
112      * @return the int represented by the string, or {@code zero} if
113      *  conversion fails
114      * @since 2.1
115      */
116     public static int toInt(final String str) {
117         return toInt(str, 0);
118     }
119 
120     /**
121      * <p>Convert a {@code String} to an {@code int}, returning a
122      * default value if the conversion fails.</p>
123      *
124      * <p>If the string is {@code null}, the default value is returned.</p>
125      *
126      * <pre>
127      *   NumberUtils.toInt(null, 1) = 1
128      *   NumberUtils.toInt("", 1)   = 1
129      *   NumberUtils.toInt("1", 0)  = 1
130      * </pre>
131      *
132      * @param str  the string to convert, may be null
133      * @param defaultValue  the default value
134      * @return the int represented by the string, or the default if conversion fails
135      * @since 2.1
136      */
137     public static int toInt(final String str, final int defaultValue) {
138         if (str == null) {
139             return defaultValue;
140         }
141         try {
142             return Integer.parseInt(str);
143         } catch (final NumberFormatException nfe) {
144             return defaultValue;
145         }
146     }
147 
148     /**
149      * <p>Convert a {@code String} to a {@code long}, returning
150      * {@code zero} if the conversion fails.</p>
151      *
152      * <p>If the string is {@code null}, {@code zero} is returned.</p>
153      *
154      * <pre>
155      *   NumberUtils.toLong(null) = 0L
156      *   NumberUtils.toLong("")   = 0L
157      *   NumberUtils.toLong("1")  = 1L
158      * </pre>
159      *
160      * @param str  the string to convert, may be null
161      * @return the long represented by the string, or {@code 0} if
162      *  conversion fails
163      * @since 2.1
164      */
165     public static long toLong(final String str) {
166         return toLong(str, 0L);
167     }
168 
169     /**
170      * <p>Convert a {@code String} to a {@code long}, returning a
171      * default value if the conversion fails.</p>
172      *
173      * <p>If the string is {@code null}, the default value is returned.</p>
174      *
175      * <pre>
176      *   NumberUtils.toLong(null, 1L) = 1L
177      *   NumberUtils.toLong("", 1L)   = 1L
178      *   NumberUtils.toLong("1", 0L)  = 1L
179      * </pre>
180      *
181      * @param str  the string to convert, may be null
182      * @param defaultValue  the default value
183      * @return the long represented by the string, or the default if conversion fails
184      * @since 2.1
185      */
186     public static long toLong(final String str, final long defaultValue) {
187         if (str == null) {
188             return defaultValue;
189         }
190         try {
191             return Long.parseLong(str);
192         } catch (final NumberFormatException nfe) {
193             return defaultValue;
194         }
195     }
196 
197     /**
198      * <p>Convert a {@code String} to a {@code float}, returning
199      * {@code 0.0f} if the conversion fails.</p>
200      *
201      * <p>If the string {@code str} is {@code null},
202      * {@code 0.0f} is returned.</p>
203      *
204      * <pre>
205      *   NumberUtils.toFloat(null)   = 0.0f
206      *   NumberUtils.toFloat("")     = 0.0f
207      *   NumberUtils.toFloat("1.5")  = 1.5f
208      * </pre>
209      *
210      * @param str the string to convert, may be {@code null}
211      * @return the float represented by the string, or {@code 0.0f}
212      *  if conversion fails
213      * @since 2.1
214      */
215     public static float toFloat(final String str) {
216         return toFloat(str, 0.0f);
217     }
218 
219     /**
220      * <p>Convert a {@code String} to a {@code float}, returning a
221      * default value if the conversion fails.</p>
222      *
223      * <p>If the string {@code str} is {@code null}, the default
224      * value is returned.</p>
225      *
226      * <pre>
227      *   NumberUtils.toFloat(null, 1.1f)   = 1.0f
228      *   NumberUtils.toFloat("", 1.1f)     = 1.1f
229      *   NumberUtils.toFloat("1.5", 0.0f)  = 1.5f
230      * </pre>
231      *
232      * @param str the string to convert, may be {@code null}
233      * @param defaultValue the default value
234      * @return the float represented by the string, or defaultValue
235      *  if conversion fails
236      * @since 2.1
237      */
238     public static float toFloat(final String str, final float defaultValue) {
239       if (str == null) {
240           return defaultValue;
241       }
242       try {
243           return Float.parseFloat(str);
244       } catch (final NumberFormatException nfe) {
245           return defaultValue;
246       }
247     }
248 
249     /**
250      * <p>Convert a {@code String} to a {@code double}, returning
251      * {@code 0.0d} if the conversion fails.</p>
252      *
253      * <p>If the string {@code str} is {@code null},
254      * {@code 0.0d} is returned.</p>
255      *
256      * <pre>
257      *   NumberUtils.toDouble(null)   = 0.0d
258      *   NumberUtils.toDouble("")     = 0.0d
259      *   NumberUtils.toDouble("1.5")  = 1.5d
260      * </pre>
261      *
262      * @param str the string to convert, may be {@code null}
263      * @return the double represented by the string, or {@code 0.0d}
264      *  if conversion fails
265      * @since 2.1
266      */
267     public static double toDouble(final String str) {
268         return toDouble(str, 0.0d);
269     }
270 
271     /**
272      * <p>Convert a {@code String} to a {@code double}, returning a
273      * default value if the conversion fails.</p>
274      *
275      * <p>If the string {@code str} is {@code null}, the default
276      * value is returned.</p>
277      *
278      * <pre>
279      *   NumberUtils.toDouble(null, 1.1d)   = 1.1d
280      *   NumberUtils.toDouble("", 1.1d)     = 1.1d
281      *   NumberUtils.toDouble("1.5", 0.0d)  = 1.5d
282      * </pre>
283      *
284      * @param str the string to convert, may be {@code null}
285      * @param defaultValue the default value
286      * @return the double represented by the string, or defaultValue
287      *  if conversion fails
288      * @since 2.1
289      */
290     public static double toDouble(final String str, final double defaultValue) {
291       if (str == null) {
292           return defaultValue;
293       }
294       try {
295           return Double.parseDouble(str);
296       } catch (final NumberFormatException nfe) {
297           return defaultValue;
298       }
299     }
300 
301     /**
302      * <p>Convert a {@code BigDecimal} to a {@code double}.</p>
303      *
304      * <p>If the {@code BigDecimal} {@code value} is
305      * {@code null}, then the specified default value is returned.</p>
306      *
307      * <pre>
308      *   NumberUtils.toDouble(null)                     = 0.0d
309      *   NumberUtils.toDouble(BigDecimal.valudOf(8.5d)) = 8.5d
310      * </pre>
311      *
312      * @param value the {@code BigDecimal} to convert, may be {@code null}.
313      * @return the double represented by the {@code BigDecimal} or
314      *  {@code 0.0d} if the {@code BigDecimal} is {@code null}.
315      * @since 3.8
316      */
317     public static double toDouble(final BigDecimal value) {
318         return toDouble(value, 0.0d);
319     }
320 
321     /**
322      * <p>Convert a {@code BigDecimal} to a {@code double}.</p>
323      *
324      * <p>If the {@code BigDecimal} {@code value} is
325      * {@code null}, then the specified default value is returned.</p>
326      *
327      * <pre>
328      *   NumberUtils.toDouble(null, 1.1d)                     = 1.1d
329      *   NumberUtils.toDouble(BigDecimal.valudOf(8.5d), 1.1d) = 8.5d
330      * </pre>
331      *
332      * @param value the {@code BigDecimal} to convert, may be {@code null}.
333      * @param defaultValue the default value
334      * @return the double represented by the {@code BigDecimal} or the
335      *  defaultValue if the {@code BigDecimal} is {@code null}.
336      * @since 3.8
337      */
338     public static double toDouble(final BigDecimal value, final double defaultValue) {
339         return value == null ? defaultValue : value.doubleValue();
340     }
341 
342      //-----------------------------------------------------------------------
343      /**
344      * <p>Convert a {@code String} to a {@code byte}, returning
345      * {@code zero} if the conversion fails.</p>
346      *
347      * <p>If the string is {@code null}, {@code zero} is returned.</p>
348      *
349      * <pre>
350      *   NumberUtils.toByte(null) = 0
351      *   NumberUtils.toByte("")   = 0
352      *   NumberUtils.toByte("1")  = 1
353      * </pre>
354      *
355      * @param str  the string to convert, may be null
356      * @return the byte represented by the string, or {@code zero} if
357      *  conversion fails
358      * @since 2.5
359      */
360     public static byte toByte(final String str) {
361         return toByte(str, (byte) 0);
362     }
363 
364     /**
365      * <p>Convert a {@code String} to a {@code byte}, returning a
366      * default value if the conversion fails.</p>
367      *
368      * <p>If the string is {@code null}, the default value is returned.</p>
369      *
370      * <pre>
371      *   NumberUtils.toByte(null, 1) = 1
372      *   NumberUtils.toByte("", 1)   = 1
373      *   NumberUtils.toByte("1", 0)  = 1
374      * </pre>
375      *
376      * @param str  the string to convert, may be null
377      * @param defaultValue  the default value
378      * @return the byte represented by the string, or the default if conversion fails
379      * @since 2.5
380      */
381     public static byte toByte(final String str, final byte defaultValue) {
382         if (str == null) {
383             return defaultValue;
384         }
385         try {
386             return Byte.parseByte(str);
387         } catch (final NumberFormatException nfe) {
388             return defaultValue;
389         }
390     }
391 
392     /**
393      * <p>Convert a {@code String} to a {@code short}, returning
394      * {@code zero} if the conversion fails.</p>
395      *
396      * <p>If the string is {@code null}, {@code zero} is returned.</p>
397      *
398      * <pre>
399      *   NumberUtils.toShort(null) = 0
400      *   NumberUtils.toShort("")   = 0
401      *   NumberUtils.toShort("1")  = 1
402      * </pre>
403      *
404      * @param str  the string to convert, may be null
405      * @return the short represented by the string, or {@code zero} if
406      *  conversion fails
407      * @since 2.5
408      */
409     public static short toShort(final String str) {
410         return toShort(str, (short) 0);
411     }
412 
413     /**
414      * <p>Convert a {@code String} to an {@code short}, returning a
415      * default value if the conversion fails.</p>
416      *
417      * <p>If the string is {@code null}, the default value is returned.</p>
418      *
419      * <pre>
420      *   NumberUtils.toShort(null, 1) = 1
421      *   NumberUtils.toShort("", 1)   = 1
422      *   NumberUtils.toShort("1", 0)  = 1
423      * </pre>
424      *
425      * @param str  the string to convert, may be null
426      * @param defaultValue  the default value
427      * @return the short represented by the string, or the default if conversion fails
428      * @since 2.5
429      */
430     public static short toShort(final String str, final short defaultValue) {
431         if (str == null) {
432             return defaultValue;
433         }
434         try {
435             return Short.parseShort(str);
436         } catch (final NumberFormatException nfe) {
437             return defaultValue;
438         }
439     }
440 
441     /**
442      * Convert a {@code BigDecimal} to a {@code BigDecimal} with a scale of
443      * two that has been rounded using {@code RoundingMode.HALF_EVEN}. If the supplied
444      * {@code value} is null, then {@code BigDecimal.ZERO} is returned.
445      *
446      * <p>Note, the scale of a {@code BigDecimal} is the number of digits to the right of the
447      * decimal point.</p>
448      *
449      * @param value the {@code BigDecimal} to convert, may be null.
450      * @return the scaled, with appropriate rounding, {@code BigDecimal}.
451      * @since 3.8
452      */
453     public static BigDecimal toScaledBigDecimal(final BigDecimal value) {
454         return toScaledBigDecimal(value, INTEGER_TWO, RoundingMode.HALF_EVEN);
455     }
456 
457     /**
458      * Convert a {@code BigDecimal} to a {@code BigDecimal} whose scale is the
459      * specified value with a {@code RoundingMode} applied. If the input {@code value}
460      * is {@code null}, we simply return {@code BigDecimal.ZERO}.
461      *
462      * @param value the {@code BigDecimal} to convert, may be null.
463      * @param scale the number of digits to the right of the decimal point.
464      * @param roundingMode a rounding behavior for numerical operations capable of
465      *  discarding precision.
466      * @return the scaled, with appropriate rounding, {@code BigDecimal}.
467      * @since 3.8
468      */
469     public static BigDecimal toScaledBigDecimal(final BigDecimal value, final int scale, final RoundingMode roundingMode) {
470         if (value == null) {
471             return BigDecimal.ZERO;
472         }
473         return value.setScale(
474             scale,
475             (roundingMode == null) ? RoundingMode.HALF_EVEN : roundingMode
476         );
477     }
478 
479     /**
480      * Convert a {@code Float} to a {@code BigDecimal} with a scale of
481      * two that has been rounded using {@code RoundingMode.HALF_EVEN}. If the supplied
482      * {@code value} is null, then {@code BigDecimal.ZERO} is returned.
483      *
484      * <p>Note, the scale of a {@code BigDecimal} is the number of digits to the right of the
485      * decimal point.</p>
486      *
487      * @param value the {@code Float} to convert, may be null.
488      * @return the scaled, with appropriate rounding, {@code BigDecimal}.
489      * @since 3.8
490      */
491     public static BigDecimal toScaledBigDecimal(final Float value) {
492         return toScaledBigDecimal(value, INTEGER_TWO, RoundingMode.HALF_EVEN);
493     }
494 
495     /**
496      * Convert a {@code Float} to a {@code BigDecimal} whose scale is the
497      * specified value with a {@code RoundingMode} applied. If the input {@code value}
498      * is {@code null}, we simply return {@code BigDecimal.ZERO}.
499      *
500      * @param value the {@code Float} to convert, may be null.
501      * @param scale the number of digits to the right of the decimal point.
502      * @param roundingMode a rounding behavior for numerical operations capable of
503      *  discarding precision.
504      * @return the scaled, with appropriate rounding, {@code BigDecimal}.
505      * @since 3.8
506      */
507     public static BigDecimal toScaledBigDecimal(final Float value, final int scale, final RoundingMode roundingMode) {
508         if (value == null) {
509             return BigDecimal.ZERO;
510         }
511         return toScaledBigDecimal(
512             BigDecimal.valueOf(value),
513             scale,
514             roundingMode
515         );
516     }
517 
518     /**
519      * Convert a {@code Double} to a {@code BigDecimal} with a scale of
520      * two that has been rounded using {@code RoundingMode.HALF_EVEN}. If the supplied
521      * {@code value} is null, then {@code BigDecimal.ZERO} is returned.
522      *
523      * <p>Note, the scale of a {@code BigDecimal} is the number of digits to the right of the
524      * decimal point.</p>
525      *
526      * @param value the {@code Double} to convert, may be null.
527      * @return the scaled, with appropriate rounding, {@code BigDecimal}.
528      * @since 3.8
529      */
530     public static BigDecimal toScaledBigDecimal(final Double value) {
531         return toScaledBigDecimal(value, INTEGER_TWO, RoundingMode.HALF_EVEN);
532     }
533 
534     /**
535      * Convert a {@code Double} to a {@code BigDecimal} whose scale is the
536      * specified value with a {@code RoundingMode} applied. If the input {@code value}
537      * is {@code null}, we simply return {@code BigDecimal.ZERO}.
538      *
539      * @param value the {@code Double} to convert, may be null.
540      * @param scale the number of digits to the right of the decimal point.
541      * @param roundingMode a rounding behavior for numerical operations capable of
542      *  discarding precision.
543      * @return the scaled, with appropriate rounding, {@code BigDecimal}.
544      * @since 3.8
545      */
546     public static BigDecimal toScaledBigDecimal(final Double value, final int scale, final RoundingMode roundingMode) {
547         if (value == null) {
548             return BigDecimal.ZERO;
549         }
550         return toScaledBigDecimal(
551             BigDecimal.valueOf(value),
552             scale,
553             roundingMode
554         );
555     }
556 
557     /**
558      * Convert a {@code String} to a {@code BigDecimal} with a scale of
559      * two that has been rounded using {@code RoundingMode.HALF_EVEN}. If the supplied
560      * {@code value} is null, then {@code BigDecimal.ZERO} is returned.
561      *
562      * <p>Note, the scale of a {@code BigDecimal} is the number of digits to the right of the
563      * decimal point.</p>
564      *
565      * @param value the {@code String} to convert, may be null.
566      * @return the scaled, with appropriate rounding, {@code BigDecimal}.
567      * @since 3.8
568      */
569     public static BigDecimal toScaledBigDecimal(final String value) {
570         return toScaledBigDecimal(value, INTEGER_TWO, RoundingMode.HALF_EVEN);
571     }
572 
573     /**
574      * Convert a {@code String} to a {@code BigDecimal} whose scale is the
575      * specified value with a {@code RoundingMode} applied. If the input {@code value}
576      * is {@code null}, we simply return {@code BigDecimal.ZERO}.
577      *
578      * @param value the {@code String} to convert, may be null.
579      * @param scale the number of digits to the right of the decimal point.
580      * @param roundingMode a rounding behavior for numerical operations capable of
581      *  discarding precision.
582      * @return the scaled, with appropriate rounding, {@code BigDecimal}.
583      * @since 3.8
584      */
585     public static BigDecimal toScaledBigDecimal(final String value, final int scale, final RoundingMode roundingMode) {
586         if (value == null) {
587             return BigDecimal.ZERO;
588         }
589         return toScaledBigDecimal(
590             createBigDecimal(value),
591             scale,
592             roundingMode
593         );
594     }
595 
596     //-----------------------------------------------------------------------
597     // must handle Long, Float, Integer, Float, Short,
598     //                  BigDecimal, BigInteger and Byte
599     // useful methods:
600     // Byte.decode(String)
601     // Byte.valueOf(String, int radix)
602     // Byte.valueOf(String)
603     // Double.valueOf(String)
604     // Float.valueOf(String)
605     // Float.valueOf(String)
606     // Integer.valueOf(String, int radix)
607     // Integer.valueOf(String)
608     // Integer.decode(String)
609     // Integer.getInteger(String)
610     // Integer.getInteger(String, int val)
611     // Integer.getInteger(String, Integer val)
612     // Integer.valueOf(String)
613     // Double.valueOf(String)
614     // new Byte(String)
615     // Long.valueOf(String)
616     // Long.getLong(String)
617     // Long.getLong(String, int)
618     // Long.getLong(String, Integer)
619     // Long.valueOf(String, int)
620     // Long.valueOf(String)
621     // Short.valueOf(String)
622     // Short.decode(String)
623     // Short.valueOf(String, int)
624     // Short.valueOf(String)
625     // new BigDecimal(String)
626     // new BigInteger(String)
627     // new BigInteger(String, int radix)
628     // Possible inputs:
629     // 45 45.5 45E7 4.5E7 Hex Oct Binary xxxF xxxD xxxf xxxd
630     // plus minus everything. Prolly more. A lot are not separable.
631 
632     /**
633      * <p>Turns a string value into a java.lang.Number.</p>
634      *
635      * <p>If the string starts with {@code 0x} or {@code -0x} (lower or upper case) or {@code #} or {@code -#}, it
636      * will be interpreted as a hexadecimal Integer - or Long, if the number of digits after the
637      * prefix is more than 8 - or BigInteger if there are more than 16 digits.
638      * </p>
639      * <p>Then, the value is examined for a type qualifier on the end, i.e. one of
640      * {@code 'f', 'F', 'd', 'D', 'l', 'L'}.  If it is found, it starts
641      * trying to create successively larger types from the type specified
642      * until one is found that can represent the value.</p>
643      *
644      * <p>If a type specifier is not found, it will check for a decimal point
645      * and then try successively larger types from {@code Integer} to
646      * {@code BigInteger} and from {@code Float} to
647     * {@code BigDecimal}.</p>
648     *
649      * <p>
650      * Integral values with a leading {@code 0} will be interpreted as octal; the returned number will
651      * be Integer, Long or BigDecimal as appropriate.
652      * </p>
653      *
654      * <p>Returns {@code null} if the string is {@code null}.</p>
655      *
656      * <p>This method does not trim the input string, i.e., strings with leading
657      * or trailing spaces will generate NumberFormatExceptions.</p>
658      *
659      * @param str  String containing a number, may be null
660      * @return Number created from the string (or null if the input is null)
661      * @throws NumberFormatException if the value cannot be converted
662      */
663     public static Number createNumber(final String str) {
664         if (str == null) {
665             return null;
666         }
667         if (StringUtils.isBlank(str)) {
668             throw new NumberFormatException("A blank string is not a valid number");
669         }
670         // Need to deal with all possible hex prefixes here
671         final String[] hex_prefixes = {"0x", "0X", "-0x", "-0X", "#", "-#"};
672         final int length = str.length();
673         int pfxLen = 0;
674         for (final String pfx : hex_prefixes) {
675             if (str.startsWith(pfx)) {
676                 pfxLen += pfx.length();
677                 break;
678             }
679         }
680         if (pfxLen > 0) { // we have a hex number
681             char firstSigDigit = 0; // strip leading zeroes
682             for (int i = pfxLen; i < length; i++) {
683                 firstSigDigit = str.charAt(i);
684                 if (firstSigDigit == '0') { // count leading zeroes
685                     pfxLen++;
686                 } else {
687                     break;
688                 }
689             }
690             final int hexDigits = length - pfxLen;
691             if (hexDigits > 16 || hexDigits == 16 && firstSigDigit > '7') { // too many for Long
692                 return createBigInteger(str);
693             }
694             if (hexDigits > 8 || hexDigits == 8 && firstSigDigit > '7') { // too many for an int
695                 return createLong(str);
696             }
697             return createInteger(str);
698         }
699         final char lastChar = str.charAt(length - 1);
700         final String mant;
701         final String dec;
702         final String exp;
703         final int decPos = str.indexOf('.');
704         final int expPos = str.indexOf('e') + str.indexOf('E') + 1; // assumes both not present
705         // if both e and E are present, this is caught by the checks on expPos (which prevent IOOBE)
706         // and the parsing which will detect if e or E appear in a number due to using the wrong offset
707 
708         if (decPos > -1) { // there is a decimal point
709             if (expPos > -1) { // there is an exponent
710                 if (expPos < decPos || expPos > length) { // prevents double exponent causing IOOBE
711                     throw new NumberFormatException(str + " is not a valid number.");
712                 }
713                 dec = str.substring(decPos + 1, expPos);
714             } else {
715                 dec = str.substring(decPos + 1);
716             }
717             mant = getMantissa(str, decPos);
718         } else {
719             if (expPos > -1) {
720                 if (expPos > length) { // prevents double exponent causing IOOBE
721                     throw new NumberFormatException(str + " is not a valid number.");
722                 }
723                 mant = getMantissa(str, expPos);
724             } else {
725                 mant = getMantissa(str);
726             }
727             dec = null;
728         }
729         if (!Character.isDigit(lastChar) && lastChar != '.') {
730             if (expPos > -1 && expPos < length - 1) {
731                 exp = str.substring(expPos + 1, length - 1);
732             } else {
733                 exp = null;
734             }
735             //Requesting a specific type..
736             final String numeric = str.substring(0, length - 1);
737             final boolean allZeros = isAllZeros(mant) && isAllZeros(exp);
738             switch (lastChar) {
739                 case 'l' :
740                 case 'L' :
741                     if (dec == null
742                         && exp == null
743                         && (!numeric.isEmpty() && numeric.charAt(0) == '-' && isDigits(numeric.substring(1)) || isDigits(numeric))) {
744                         try {
745                             return createLong(numeric);
746                         } catch (final NumberFormatException nfe) { // NOPMD
747                             // Too big for a long
748                         }
749                         return createBigInteger(numeric);
750 
751                     }
752                     throw new NumberFormatException(str + " is not a valid number.");
753                 case 'f' :
754                 case 'F' :
755                     try {
756                         final Float f = createFloat(str);
757                         if (!(f.isInfinite() || f.floatValue() == 0.0F && !allZeros)) {
758                             //If it's too big for a float or the float value = 0 and the string
759                             //has non-zeros in it, then float does not have the precision we want
760                             return f;
761                         }
762 
763                     } catch (final NumberFormatException nfe) { // NOPMD
764                         // ignore the bad number
765                     }
766                     //$FALL-THROUGH$
767                 case 'd' :
768                 case 'D' :
769                     try {
770                         final Double d = createDouble(str);
771                         if (!(d.isInfinite() || d.doubleValue() == 0.0D && !allZeros)) {
772                             return d;
773                         }
774                     } catch (final NumberFormatException nfe) { // NOPMD
775                         // ignore the bad number
776                     }
777                     try {
778                         return createBigDecimal(numeric);
779                     } catch (final NumberFormatException e) { // NOPMD
780                         // ignore the bad number
781                     }
782                     //$FALL-THROUGH$
783                 default :
784                     throw new NumberFormatException(str + " is not a valid number.");
785 
786             }
787         }
788         //User doesn't have a preference on the return type, so let's start
789         //small and go from there...
790         if (expPos > -1 && expPos < length - 1) {
791             exp = str.substring(expPos + 1);
792         } else {
793             exp = null;
794         }
795         if (dec == null && exp == null) { // no decimal point and no exponent
796             //Must be an Integer, Long, Biginteger
797             try {
798                 return createInteger(str);
799             } catch (final NumberFormatException nfe) { // NOPMD
800                 // ignore the bad number
801             }
802             try {
803                 return createLong(str);
804             } catch (final NumberFormatException nfe) { // NOPMD
805                 // ignore the bad number
806             }
807             return createBigInteger(str);
808         }
809 
810         //Must be a Float, Double, BigDecimal
811         final boolean allZeros = isAllZeros(mant) && isAllZeros(exp);
812         try {
813             final Float f = createFloat(str);
814             final Double d = createDouble(str);
815             if (!f.isInfinite()
816                     && !(f.floatValue() == 0.0F && !allZeros)
817                     && f.toString().equals(d.toString())) {
818                 return f;
819             }
820             if (!d.isInfinite() && !(d.doubleValue() == 0.0D && !allZeros)) {
821                 final BigDecimal b = createBigDecimal(str);
822                 if (b.compareTo(BigDecimal.valueOf(d.doubleValue())) == 0) {
823                     return d;
824                 }
825                 return b;
826             }
827         } catch (final NumberFormatException nfe) { // NOPMD
828             // ignore the bad number
829         }
830         return createBigDecimal(str);
831     }
832 
833     /**
834      * <p>Utility method for {@link #createNumber(java.lang.String)}.</p>
835      *
836      * <p>Returns mantissa of the given number.</p>
837      *
838      * @param str the string representation of the number
839      * @return mantissa of the given number
840      */
841     private static String getMantissa(final String str) {
842         return getMantissa(str, str.length());
843     }
844 
845     /**
846      * <p>Utility method for {@link #createNumber(java.lang.String)}.</p>
847      *
848      * <p>Returns mantissa of the given number.</p>
849      *
850      * @param str the string representation of the number
851      * @param stopPos the position of the exponent or decimal point
852      * @return mantissa of the given number
853      */
854     private static String getMantissa(final String str, final int stopPos) {
855         final char firstChar = str.charAt(0);
856         final boolean hasSign = firstChar == '-' || firstChar == '+';
857 
858         return hasSign ? str.substring(1, stopPos) : str.substring(0, stopPos);
859     }
860 
861     /**
862      * <p>Utility method for {@link #createNumber(java.lang.String)}.</p>
863      *
864      * <p>Returns {@code true} if s is {@code null}.</p>
865      *
866      * @param str  the String to check
867      * @return if it is all zeros or {@code null}
868      */
869     private static boolean isAllZeros(final String str) {
870         if (str == null) {
871             return true;
872         }
873         for (int i = str.length() - 1; i >= 0; i--) {
874             if (str.charAt(i) != '0') {
875                 return false;
876             }
877         }
878         return !str.isEmpty();
879     }
880 
881     //-----------------------------------------------------------------------
882     /**
883      * <p>Convert a {@code String} to a {@code Float}.</p>
884      *
885      * <p>Returns {@code null} if the string is {@code null}.</p>
886      *
887      * @param str  a {@code String} to convert, may be null
888      * @return converted {@code Float} (or null if the input is null)
889      * @throws NumberFormatException if the value cannot be converted
890      */
891     public static Float createFloat(final String str) {
892         if (str == null) {
893             return null;
894         }
895         return Float.valueOf(str);
896     }
897 
898     /**
899      * <p>Convert a {@code String} to a {@code Double}.</p>
900      *
901      * <p>Returns {@code null} if the string is {@code null}.</p>
902      *
903      * @param str  a {@code String} to convert, may be null
904      * @return converted {@code Double} (or null if the input is null)
905      * @throws NumberFormatException if the value cannot be converted
906      */
907     public static Double createDouble(final String str) {
908         if (str == null) {
909             return null;
910         }
911         return Double.valueOf(str);
912     }
913 
914     /**
915      * <p>Convert a {@code String} to a {@code Integer}, handling
916      * hex (0xhhhh) and octal (0dddd) notations.
917      * N.B. a leading zero means octal; spaces are not trimmed.</p>
918      *
919      * <p>Returns {@code null} if the string is {@code null}.</p>
920      *
921      * @param str  a {@code String} to convert, may be null
922      * @return converted {@code Integer} (or null if the input is null)
923      * @throws NumberFormatException if the value cannot be converted
924      */
925     public static Integer createInteger(final String str) {
926         if (str == null) {
927             return null;
928         }
929         // decode() handles 0xAABD and 0777 (hex and octal) as well.
930         return Integer.decode(str);
931     }
932 
933     /**
934      * <p>Convert a {@code String} to a {@code Long};
935      * since 3.1 it handles hex (0Xhhhh) and octal (0ddd) notations.
936      * N.B. a leading zero means octal; spaces are not trimmed.</p>
937      *
938      * <p>Returns {@code null} if the string is {@code null}.</p>
939      *
940      * @param str  a {@code String} to convert, may be null
941      * @return converted {@code Long} (or null if the input is null)
942      * @throws NumberFormatException if the value cannot be converted
943      */
944     public static Long createLong(final String str) {
945         if (str == null) {
946             return null;
947         }
948         return Long.decode(str);
949     }
950 
951     /**
952      * <p>Convert a {@code String} to a {@code BigInteger};
953      * since 3.2 it handles hex (0x or #) and octal (0) notations.</p>
954      *
955      * <p>Returns {@code null} if the string is {@code null}.</p>
956      *
957      * @param str  a {@code String} to convert, may be null
958      * @return converted {@code BigInteger} (or null if the input is null)
959      * @throws NumberFormatException if the value cannot be converted
960      */
961     public static BigInteger createBigInteger(final String str) {
962         if (str == null) {
963             return null;
964         }
965         int pos = 0; // offset within string
966         int radix = 10;
967         boolean negate = false; // need to negate later?
968         if (str.startsWith("-")) {
969             negate = true;
970             pos = 1;
971         }
972         if (str.startsWith("0x", pos) || str.startsWith("0X", pos)) { // hex
973             radix = 16;
974             pos += 2;
975         } else if (str.startsWith("#", pos)) { // alternative hex (allowed by Long/Integer)
976             radix = 16;
977             pos++;
978         } else if (str.startsWith("0", pos) && str.length() > pos + 1) { // octal; so long as there are additional digits
979             radix = 8;
980             pos++;
981         } // default is to treat as decimal
982 
983         final BigInteger value = new BigInteger(str.substring(pos), radix);
984         return negate ? value.negate() : value;
985     }
986 
987     /**
988      * <p>Convert a {@code String} to a {@code BigDecimal}.</p>
989      *
990      * <p>Returns {@code null} if the string is {@code null}.</p>
991      *
992      * @param str  a {@code String} to convert, may be null
993      * @return converted {@code BigDecimal} (or null if the input is null)
994      * @throws NumberFormatException if the value cannot be converted
995      */
996     public static BigDecimal createBigDecimal(final String str) {
997         if (str == null) {
998             return null;
999         }
1000         // handle JDK1.3.1 bug where "" throws IndexOutOfBoundsException
1001         if (StringUtils.isBlank(str)) {
1002             throw new NumberFormatException("A blank string is not a valid number");
1003         }
1004         return new BigDecimal(str);
1005     }
1006 
1007     // Min in array
1008     //--------------------------------------------------------------------
1009     /**
1010      * <p>Returns the minimum value in an array.</p>
1011      *
1012      * @param array  an array, must not be null or empty
1013      * @return the minimum value in the array
1014      * @throws IllegalArgumentException if {@code array} is {@code null}
1015      * @throws IllegalArgumentException if {@code array} is empty
1016      * @since 3.4 Changed signature from min(long[]) to min(long...)
1017      */
1018     public static long min(final long... array) {
1019         // Validates input
1020         validateArray(array);
1021 
1022         // Finds and returns min
1023         long min = array[0];
1024         for (int i = 1; i < array.length; i++) {
1025             if (array[i] < min) {
1026                 min = array[i];
1027             }
1028         }
1029 
1030         return min;
1031     }
1032 
1033     /**
1034      * <p>Returns the minimum value in an array.</p>
1035      *
1036      * @param array  an array, must not be null or empty
1037      * @return the minimum value in the array
1038      * @throws IllegalArgumentException if {@code array} is {@code null}
1039      * @throws IllegalArgumentException if {@code array} is empty
1040      * @since 3.4 Changed signature from min(int[]) to min(int...)
1041      */
1042     public static int min(final int... array) {
1043         // Validates input
1044         validateArray(array);
1045 
1046         // Finds and returns min
1047         int min = array[0];
1048         for (int j = 1; j < array.length; j++) {
1049             if (array[j] < min) {
1050                 min = array[j];
1051             }
1052         }
1053 
1054         return min;
1055     }
1056 
1057     /**
1058      * <p>Returns the minimum value in an array.</p>
1059      *
1060      * @param array  an array, must not be null or empty
1061      * @return the minimum value in the array
1062      * @throws IllegalArgumentException if {@code array} is {@code null}
1063      * @throws IllegalArgumentException if {@code array} is empty
1064      * @since 3.4 Changed signature from min(short[]) to min(short...)
1065      */
1066     public static short min(final short... array) {
1067         // Validates input
1068         validateArray(array);
1069 
1070         // Finds and returns min
1071         short min = array[0];
1072         for (int i = 1; i < array.length; i++) {
1073             if (array[i] < min) {
1074                 min = array[i];
1075             }
1076         }
1077 
1078         return min;
1079     }
1080 
1081     /**
1082      * <p>Returns the minimum value in an array.</p>
1083      *
1084      * @param array  an array, must not be null or empty
1085      * @return the minimum value in the array
1086      * @throws IllegalArgumentException if {@code array} is {@code null}
1087      * @throws IllegalArgumentException if {@code array} is empty
1088      * @since 3.4 Changed signature from min(byte[]) to min(byte...)
1089      */
1090     public static byte min(final byte... array) {
1091         // Validates input
1092         validateArray(array);
1093 
1094         // Finds and returns min
1095         byte min = array[0];
1096         for (int i = 1; i < array.length; i++) {
1097             if (array[i] < min) {
1098                 min = array[i];
1099             }
1100         }
1101 
1102         return min;
1103     }
1104 
1105      /**
1106      * <p>Returns the minimum value in an array.</p>
1107      *
1108      * @param array  an array, must not be null or empty
1109      * @return the minimum value in the array
1110      * @throws IllegalArgumentException if {@code array} is {@code null}
1111      * @throws IllegalArgumentException if {@code array} is empty
1112      * @see IEEE754rUtils#min(double[]) IEEE754rUtils for a version of this method that handles NaN differently
1113      * @since 3.4 Changed signature from min(double[]) to min(double...)
1114      */
1115     public static double min(final double... array) {
1116         // Validates input
1117         validateArray(array);
1118 
1119         // Finds and returns min
1120         double min = array[0];
1121         for (int i = 1; i < array.length; i++) {
1122             if (Double.isNaN(array[i])) {
1123                 return Double.NaN;
1124             }
1125             if (array[i] < min) {
1126                 min = array[i];
1127             }
1128         }
1129 
1130         return min;
1131     }
1132 
1133     /**
1134      * <p>Returns the minimum value in an array.</p>
1135      *
1136      * @param array  an array, must not be null or empty
1137      * @return the minimum value in the array
1138      * @throws IllegalArgumentException if {@code array} is {@code null}
1139      * @throws IllegalArgumentException if {@code array} is empty
1140      * @see IEEE754rUtils#min(float[]) IEEE754rUtils for a version of this method that handles NaN differently
1141      * @since 3.4 Changed signature from min(float[]) to min(float...)
1142      */
1143     public static float min(final float... array) {
1144         // Validates input
1145         validateArray(array);
1146 
1147         // Finds and returns min
1148         float min = array[0];
1149         for (int i = 1; i < array.length; i++) {
1150             if (Float.isNaN(array[i])) {
1151                 return Float.NaN;
1152             }
1153             if (array[i] < min) {
1154                 min = array[i];
1155             }
1156         }
1157 
1158         return min;
1159     }
1160 
1161     // Max in array
1162     //--------------------------------------------------------------------
1163     /**
1164      * <p>Returns the maximum value in an array.</p>
1165      *
1166      * @param array  an array, must not be null or empty
1167      * @return the maximum value in the array
1168      * @throws IllegalArgumentException if {@code array} is {@code null}
1169      * @throws IllegalArgumentException if {@code array} is empty
1170      * @since 3.4 Changed signature from max(long[]) to max(long...)
1171      */
1172     public static long max(final long... array) {
1173         // Validates input
1174         validateArray(array);
1175 
1176         // Finds and returns max
1177         long max = array[0];
1178         for (int j = 1; j < array.length; j++) {
1179             if (array[j] > max) {
1180                 max = array[j];
1181             }
1182         }
1183 
1184         return max;
1185     }
1186 
1187     /**
1188      * <p>Returns the maximum value in an array.</p>
1189      *
1190      * @param array  an array, must not be null or empty
1191      * @return the maximum value in the array
1192      * @throws IllegalArgumentException if {@code array} is {@code null}
1193      * @throws IllegalArgumentException if {@code array} is empty
1194      * @since 3.4 Changed signature from max(int[]) to max(int...)
1195      */
1196     public static int max(final int... array) {
1197         // Validates input
1198         validateArray(array);
1199 
1200         // Finds and returns max
1201         int max = array[0];
1202         for (int j = 1; j < array.length; j++) {
1203             if (array[j] > max) {
1204                 max = array[j];
1205             }
1206         }
1207 
1208         return max;
1209     }
1210 
1211     /**
1212      * <p>Returns the maximum value in an array.</p>
1213      *
1214      * @param array  an array, must not be null or empty
1215      * @return the maximum value in the array
1216      * @throws IllegalArgumentException if {@code array} is {@code null}
1217      * @throws IllegalArgumentException if {@code array} is empty
1218      * @since 3.4 Changed signature from max(short[]) to max(short...)
1219      */
1220     public static short max(final short... array) {
1221         // Validates input
1222         validateArray(array);
1223 
1224         // Finds and returns max
1225         short max = array[0];
1226         for (int i = 1; i < array.length; i++) {
1227             if (array[i] > max) {
1228                 max = array[i];
1229             }
1230         }
1231 
1232         return max;
1233     }
1234 
1235     /**
1236      * <p>Returns the maximum value in an array.</p>
1237      *
1238      * @param array  an array, must not be null or empty
1239      * @return the maximum value in the array
1240      * @throws IllegalArgumentException if {@code array} is {@code null}
1241      * @throws IllegalArgumentException if {@code array} is empty
1242      * @since 3.4 Changed signature from max(byte[]) to max(byte...)
1243      */
1244     public static byte max(final byte... array) {
1245         // Validates input
1246         validateArray(array);
1247 
1248         // Finds and returns max
1249         byte max = array[0];
1250         for (int i = 1; i < array.length; i++) {
1251             if (array[i] > max) {
1252                 max = array[i];
1253             }
1254         }
1255 
1256         return max;
1257     }
1258 
1259     /**
1260      * <p>Returns the maximum value in an array.</p>
1261      *
1262      * @param array  an array, must not be null or empty
1263      * @return the maximum value in the array
1264      * @throws IllegalArgumentException if {@code array} is {@code null}
1265      * @throws IllegalArgumentException if {@code array} is empty
1266      * @see IEEE754rUtils#max(double[]) IEEE754rUtils for a version of this method that handles NaN differently
1267      * @since 3.4 Changed signature from max(double[]) to max(double...)
1268      */
1269     public static double max(final double... array) {
1270         // Validates input
1271         validateArray(array);
1272 
1273         // Finds and returns max
1274         double max = array[0];
1275         for (int j = 1; j < array.length; j++) {
1276             if (Double.isNaN(array[j])) {
1277                 return Double.NaN;
1278             }
1279             if (array[j] > max) {
1280                 max = array[j];
1281             }
1282         }
1283 
1284         return max;
1285     }
1286 
1287     /**
1288      * <p>Returns the maximum value in an array.</p>
1289      *
1290      * @param array  an array, must not be null or empty
1291      * @return the maximum value in the array
1292      * @throws IllegalArgumentException if {@code array} is {@code null}
1293      * @throws IllegalArgumentException if {@code array} is empty
1294      * @see IEEE754rUtils#max(float[]) IEEE754rUtils for a version of this method that handles NaN differently
1295      * @since 3.4 Changed signature from max(float[]) to max(float...)
1296      */
1297     public static float max(final float... array) {
1298         // Validates input
1299         validateArray(array);
1300 
1301         // Finds and returns max
1302         float max = array[0];
1303         for (int j = 1; j < array.length; j++) {
1304             if (Float.isNaN(array[j])) {
1305                 return Float.NaN;
1306             }
1307             if (array[j] > max) {
1308                 max = array[j];
1309             }
1310         }
1311 
1312         return max;
1313     }
1314 
1315     /**
1316      * Checks if the specified array is neither null nor empty.
1317      *
1318      * @param array  the array to check
1319      * @throws IllegalArgumentException if {@code array} is either {@code null} or empty
1320      */
1321     private static void validateArray(final Object array) {
1322         Validate.notNull(array, "array");
1323         Validate.isTrue(Array.getLength(array) != 0, "Array cannot be empty.");
1324     }
1325 
1326     // 3 param min
1327     //-----------------------------------------------------------------------
1328     /**
1329      * <p>Gets the minimum of three {@code long} values.</p>
1330      *
1331      * @param a  value 1
1332      * @param b  value 2
1333      * @param c  value 3
1334      * @return  the smallest of the values
1335      */
1336     public static long min(long a, final long b, final long c) {
1337         if (b < a) {
1338             a = b;
1339         }
1340         if (c < a) {
1341             a = c;
1342         }
1343         return a;
1344     }
1345 
1346     /**
1347      * <p>Gets the minimum of three {@code int} values.</p>
1348      *
1349      * @param a  value 1
1350      * @param b  value 2
1351      * @param c  value 3
1352      * @return  the smallest of the values
1353      */
1354     public static int min(int a, final int b, final int c) {
1355         if (b < a) {
1356             a = b;
1357         }
1358         if (c < a) {
1359             a = c;
1360         }
1361         return a;
1362     }
1363 
1364     /**
1365      * <p>Gets the minimum of three {@code short} values.</p>
1366      *
1367      * @param a  value 1
1368      * @param b  value 2
1369      * @param c  value 3
1370      * @return  the smallest of the values
1371      */
1372     public static short min(short a, final short b, final short c) {
1373         if (b < a) {
1374             a = b;
1375         }
1376         if (c < a) {
1377             a = c;
1378         }
1379         return a;
1380     }
1381 
1382     /**
1383      * <p>Gets the minimum of three {@code byte} values.</p>
1384      *
1385      * @param a  value 1
1386      * @param b  value 2
1387      * @param c  value 3
1388      * @return  the smallest of the values
1389      */
1390     public static byte min(byte a, final byte b, final byte c) {
1391         if (b < a) {
1392             a = b;
1393         }
1394         if (c < a) {
1395             a = c;
1396         }
1397         return a;
1398     }
1399 
1400     /**
1401      * <p>Gets the minimum of three {@code double} values.</p>
1402      *
1403      * <p>If any value is {@code NaN}, {@code NaN} is
1404      * returned. Infinity is handled.</p>
1405      *
1406      * @param a  value 1
1407      * @param b  value 2
1408      * @param c  value 3
1409      * @return  the smallest of the values
1410      * @see IEEE754rUtils#min(double, double, double) for a version of this method that handles NaN differently
1411      */
1412     public static double min(final double a, final double b, final double c) {
1413         return Math.min(Math.min(a, b), c);
1414     }
1415 
1416     /**
1417      * <p>Gets the minimum of three {@code float} values.</p>
1418      *
1419      * <p>If any value is {@code NaN}, {@code NaN} is
1420      * returned. Infinity is handled.</p>
1421      *
1422      * @param a  value 1
1423      * @param b  value 2
1424      * @param c  value 3
1425      * @return  the smallest of the values
1426      * @see IEEE754rUtils#min(float, float, float) for a version of this method that handles NaN differently
1427      */
1428     public static float min(final float a, final float b, final float c) {
1429         return Math.min(Math.min(a, b), c);
1430     }
1431 
1432     // 3 param max
1433     //-----------------------------------------------------------------------
1434     /**
1435      * <p>Gets the maximum of three {@code long} values.</p>
1436      *
1437      * @param a  value 1
1438      * @param b  value 2
1439      * @param c  value 3
1440      * @return  the largest of the values
1441      */
1442     public static long max(long a, final long b, final long c) {
1443         if (b > a) {
1444             a = b;
1445         }
1446         if (c > a) {
1447             a = c;
1448         }
1449         return a;
1450     }
1451 
1452     /**
1453      * <p>Gets the maximum of three {@code int} values.</p>
1454      *
1455      * @param a  value 1
1456      * @param b  value 2
1457      * @param c  value 3
1458      * @return  the largest of the values
1459      */
1460     public static int max(int a, final int b, final int c) {
1461         if (b > a) {
1462             a = b;
1463         }
1464         if (c > a) {
1465             a = c;
1466         }
1467         return a;
1468     }
1469 
1470     /**
1471      * <p>Gets the maximum of three {@code short} values.</p>
1472      *
1473      * @param a  value 1
1474      * @param b  value 2
1475      * @param c  value 3
1476      * @return  the largest of the values
1477      */
1478     public static short max(short a, final short b, final short c) {
1479         if (b > a) {
1480             a = b;
1481         }
1482         if (c > a) {
1483             a = c;
1484         }
1485         return a;
1486     }
1487 
1488     /**
1489      * <p>Gets the maximum of three {@code byte} values.</p>
1490      *
1491      * @param a  value 1
1492      * @param b  value 2
1493      * @param c  value 3
1494      * @return  the largest of the values
1495      */
1496     public static byte max(byte a, final byte b, final byte c) {
1497         if (b > a) {
1498             a = b;
1499         }
1500         if (c > a) {
1501             a = c;
1502         }
1503         return a;
1504     }
1505 
1506     /**
1507      * <p>Gets the maximum of three {@code double} values.</p>
1508      *
1509      * <p>If any value is {@code NaN}, {@code NaN} is
1510      * returned. Infinity is handled.</p>
1511      *
1512      * @param a  value 1
1513      * @param b  value 2
1514      * @param c  value 3
1515      * @return  the largest of the values
1516      * @see IEEE754rUtils#max(double, double, double) for a version of this method that handles NaN differently
1517      */
1518     public static double max(final double a, final double b, final double c) {
1519         return Math.max(Math.max(a, b), c);
1520     }
1521 
1522     /**
1523      * <p>Gets the maximum of three {@code float} values.</p>
1524      *
1525      * <p>If any value is {@code NaN}, {@code NaN} is
1526      * returned. Infinity is handled.</p>
1527      *
1528      * @param a  value 1
1529      * @param b  value 2
1530      * @param c  value 3
1531      * @return  the largest of the values
1532      * @see IEEE754rUtils#max(float, float, float) for a version of this method that handles NaN differently
1533      */
1534     public static float max(final float a, final float b, final float c) {
1535         return Math.max(Math.max(a, b), c);
1536     }
1537 
1538     //-----------------------------------------------------------------------
1539     /**
1540      * <p>Checks whether the {@code String} contains only
1541      * digit characters.</p>
1542      *
1543      * <p>{@code Null} and empty String will return
1544      * {@code false}.</p>
1545      *
1546      * @param str  the {@code String} to check
1547      * @return {@code true} if str contains only Unicode numeric
1548      */
1549     public static boolean isDigits(final String str) {
1550         return StringUtils.isNumeric(str);
1551     }
1552 
1553     /**
1554      * <p>Checks whether the String a valid Java number.</p>
1555      *
1556      * <p>Valid numbers include hexadecimal marked with the {@code 0x} or
1557      * {@code 0X} qualifier, octal numbers, scientific notation and
1558      * numbers marked with a type qualifier (e.g. 123L).</p>
1559      *
1560      * <p>Non-hexadecimal strings beginning with a leading zero are
1561      * treated as octal values. Thus the string {@code 09} will return
1562      * {@code false}, since {@code 9} is not a valid octal value.
1563      * However, numbers beginning with {@code 0.} are treated as decimal.</p>
1564      *
1565      * <p>{@code null} and empty/blank {@code String} will return
1566      * {@code false}.</p>
1567      *
1568      * <p>Note, {@link #createNumber(String)} should return a number for every
1569      * input resulting in {@code true}.</p>
1570      *
1571      * @param str  the {@code String} to check
1572      * @return {@code true} if the string is a correctly formatted number
1573      * @since 3.3 the code supports hex {@code 0Xhhh} an
1574      *        octal {@code 0ddd} validation
1575      * @deprecated This feature will be removed in Lang 4.0,
1576      *             use {@link NumberUtils#isCreatable(String)} instead
1577      */
1578     @Deprecated
1579     public static boolean isNumber(final String str) {
1580         return isCreatable(str);
1581     }
1582 
1583     /**
1584      * <p>Checks whether the String a valid Java number.</p>
1585      *
1586      * <p>Valid numbers include hexadecimal marked with the {@code 0x} or
1587      * {@code 0X} qualifier, octal numbers, scientific notation and
1588      * numbers marked with a type qualifier (e.g. 123L).</p>
1589      *
1590      * <p>Non-hexadecimal strings beginning with a leading zero are
1591      * treated as octal values. Thus the string {@code 09} will return
1592      * {@code false}, since {@code 9} is not a valid octal value.
1593      * However, numbers beginning with {@code 0.} are treated as decimal.</p>
1594      *
1595      * <p>{@code null} and empty/blank {@code String} will return
1596      * {@code false}.</p>
1597      *
1598      * <p>Note, {@link #createNumber(String)} should return a number for every
1599      * input resulting in {@code true}.</p>
1600      *
1601      * @param str  the {@code String} to check
1602      * @return {@code true} if the string is a correctly formatted number
1603      * @since 3.5
1604      */
1605     public static boolean isCreatable(final String str) {
1606         if (StringUtils.isEmpty(str)) {
1607             return false;
1608         }
1609         final char[] chars = str.toCharArray();
1610         int sz = chars.length;
1611         boolean hasExp = false;
1612         boolean hasDecPoint = false;
1613         boolean allowSigns = false;
1614         boolean foundDigit = false;
1615         // deal with any possible sign up front
1616         final int start = chars[0] == '-' || chars[0] == '+' ? 1 : 0;
1617         if (sz > start + 1 && chars[start] == '0' && !StringUtils.contains(str, '.')) { // leading 0, skip if is a decimal number
1618             if (chars[start + 1] == 'x' || chars[start + 1] == 'X') { // leading 0x/0X
1619                 int i = start + 2;
1620                 if (i == sz) {
1621                     return false; // str == "0x"
1622                 }
1623                 // checking hex (it can't be anything else)
1624                 for (; i < chars.length; i++) {
1625                     if ((chars[i] < '0' || chars[i] > '9')
1626                         && (chars[i] < 'a' || chars[i] > 'f')
1627                         && (chars[i] < 'A' || chars[i] > 'F')) {
1628                         return false;
1629                     }
1630                 }
1631                 return true;
1632            } else if (Character.isDigit(chars[start + 1])) {
1633                // leading 0, but not hex, must be octal
1634                int i = start + 1;
1635                for (; i < chars.length; i++) {
1636                    if (chars[i] < '0' || chars[i] > '7') {
1637                        return false;
1638                    }
1639                }
1640                return true;
1641            }
1642         }
1643         sz--; // don't want to loop to the last char, check it afterwords
1644               // for type qualifiers
1645         int i = start;
1646         // loop to the next to last char or to the last char if we need another digit to
1647         // make a valid number (e.g. chars[0..5] = "1234E")
1648         while (i < sz || i < sz + 1 && allowSigns && !foundDigit) {
1649             if (chars[i] >= '0' && chars[i] <= '9') {
1650                 foundDigit = true;
1651                 allowSigns = false;
1652 
1653             } else if (chars[i] == '.') {
1654                 if (hasDecPoint || hasExp) {
1655                     // two decimal points or dec in exponent
1656                     return false;
1657                 }
1658                 hasDecPoint = true;
1659             } else if (chars[i] == 'e' || chars[i] == 'E') {
1660                 // we've already taken care of hex.
1661                 if (hasExp) {
1662                     // two E's
1663                     return false;
1664                 }
1665                 if (!foundDigit) {
1666                     return false;
1667                 }
1668                 hasExp = true;
1669                 allowSigns = true;
1670             } else if (chars[i] == '+' || chars[i] == '-') {
1671                 if (!allowSigns) {
1672                     return false;
1673                 }
1674                 allowSigns = false;
1675                 foundDigit = false; // we need a digit after the E
1676             } else {
1677                 return false;
1678             }
1679             i++;
1680         }
1681         if (i < chars.length) {
1682             if (chars[i] >= '0' && chars[i] <= '9') {
1683                 // no type qualifier, OK
1684                 return true;
1685             }
1686             if (chars[i] == 'e' || chars[i] == 'E') {
1687                 // can't have an E at the last byte
1688                 return false;
1689             }
1690             if (chars[i] == '.') {
1691                 if (hasDecPoint || hasExp) {
1692                     // two decimal points or dec in exponent
1693                     return false;
1694                 }
1695                 // single trailing decimal point after non-exponent is ok
1696                 return foundDigit;
1697             }
1698             if (!allowSigns
1699                 && (chars[i] == 'd'
1700                     || chars[i] == 'D'
1701                     || chars[i] == 'f'
1702                     || chars[i] == 'F')) {
1703                 return foundDigit;
1704             }
1705             if (chars[i] == 'l'
1706                 || chars[i] == 'L') {
1707                 // not allowing L with an exponent or decimal point
1708                 return foundDigit && !hasExp && !hasDecPoint;
1709             }
1710             // last character is illegal
1711             return false;
1712         }
1713         // allowSigns is true iff the val ends in 'E'
1714         // found digit it to make sure weird stuff like '.' and '1E-' doesn't pass
1715         return !allowSigns && foundDigit;
1716     }
1717 
1718     /**
1719      * <p>Checks whether the given String is a parsable number.</p>
1720      *
1721      * <p>Parsable numbers include those Strings understood by {@link Integer#parseInt(String)},
1722      * {@link Long#parseLong(String)}, {@link Float#parseFloat(String)} or
1723      * {@link Double#parseDouble(String)}. This method can be used instead of catching {@link java.text.ParseException}
1724      * when calling one of those methods.</p>
1725      *
1726      * <p>Hexadecimal and scientific notations are <strong>not</strong> considered parsable.
1727      * See {@link #isCreatable(String)} on those cases.</p>
1728      *
1729      * <p>{@code Null} and empty String will return {@code false}.</p>
1730      *
1731      * @param str the String to check.
1732      * @return {@code true} if the string is a parsable number.
1733      * @since 3.4
1734      */
1735     public static boolean isParsable(final String str) {
1736         if (StringUtils.isEmpty(str)) {
1737             return false;
1738         }
1739         if (str.charAt(str.length() - 1) == '.') {
1740             return false;
1741         }
1742         if (str.charAt(0) == '-') {
1743             if (str.length() == 1) {
1744                 return false;
1745             }
1746             return withDecimalsParsing(str, 1);
1747         }
1748         return withDecimalsParsing(str, 0);
1749     }
1750 
1751     private static boolean withDecimalsParsing(final String str, final int beginIdx) {
1752         int decimalPoints = 0;
1753         for (int i = beginIdx; i < str.length(); i++) {
1754             final boolean isDecimalPoint = str.charAt(i) == '.';
1755             if (isDecimalPoint) {
1756                 decimalPoints++;
1757             }
1758             if (decimalPoints > 1) {
1759                 return false;
1760             }
1761             if (!isDecimalPoint && !Character.isDigit(str.charAt(i))) {
1762                 return false;
1763             }
1764         }
1765         return true;
1766     }
1767 
1768     /**
1769      * <p>Compares two {@code int} values numerically. This is the same functionality as provided in Java 7.</p>
1770      *
1771      * @param x the first {@code int} to compare
1772      * @param y the second {@code int} to compare
1773      * @return the value {@code 0} if {@code x == y};
1774      *         a value less than {@code 0} if {@code x < y}; and
1775      *         a value greater than {@code 0} if {@code x > y}
1776      * @since 3.4
1777      */
1778     public static int compare(final int x, final int y) {
1779         if (x == y) {
1780             return 0;
1781         }
1782         return x < y ? -1 : 1;
1783     }
1784 
1785     /**
1786      * <p>Compares to {@code long} values numerically. This is the same functionality as provided in Java 7.</p>
1787      *
1788      * @param x the first {@code long} to compare
1789      * @param y the second {@code long} to compare
1790      * @return the value {@code 0} if {@code x == y};
1791      *         a value less than {@code 0} if {@code x < y}; and
1792      *         a value greater than {@code 0} if {@code x > y}
1793      * @since 3.4
1794      */
1795     public static int compare(final long x, final long y) {
1796         if (x == y) {
1797             return 0;
1798         }
1799         return x < y ? -1 : 1;
1800     }
1801 
1802     /**
1803      * <p>Compares to {@code short} values numerically. This is the same functionality as provided in Java 7.</p>
1804      *
1805      * @param x the first {@code short} to compare
1806      * @param y the second {@code short} to compare
1807      * @return the value {@code 0} if {@code x == y};
1808      *         a value less than {@code 0} if {@code x < y}; and
1809      *         a value greater than {@code 0} if {@code x > y}
1810      * @since 3.4
1811      */
1812     public static int compare(final short x, final short y) {
1813         if (x == y) {
1814             return 0;
1815         }
1816         return x < y ? -1 : 1;
1817     }
1818 
1819     /**
1820      * <p>Compares two {@code byte} values numerically. This is the same functionality as provided in Java 7.</p>
1821      *
1822      * @param x the first {@code byte} to compare
1823      * @param y the second {@code byte} to compare
1824      * @return the value {@code 0} if {@code x == y};
1825      *         a value less than {@code 0} if {@code x < y}; and
1826      *         a value greater than {@code 0} if {@code x > y}
1827      * @since 3.4
1828      */
1829     public static int compare(final byte x, final byte y) {
1830         return x - y;
1831     }
1832 }