001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one or more
003     * contributor license agreements.  See the NOTICE file distributed with
004     * this work for additional information regarding copyright ownership.
005     * The ASF licenses this file to You under the Apache License, Version 2.0
006     * (the "License"); you may not use this file except in compliance with
007     * the License.  You may obtain a copy of the License at
008     * 
009     *      http://www.apache.org/licenses/LICENSE-2.0
010     * 
011     * Unless required by applicable law or agreed to in writing, software
012     * distributed under the License is distributed on an "AS IS" BASIS,
013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014     * See the License for the specific language governing permissions and
015     * limitations under the License.
016     */
017    package org.apache.commons.lang3.math;
018    
019    import java.math.BigDecimal;
020    import java.math.BigInteger;
021    
022    import org.apache.commons.lang3.StringUtils;
023    
024    /**
025     * <p>Provides extra functionality for Java Number classes.</p>
026     *
027     * @since 2.0
028     * @version $Id: NumberUtils.java 1147520 2011-07-17 03:43:51Z mbenson $
029     */
030    public class NumberUtils {
031        
032        /** Reusable Long constant for zero. */
033        public static final Long LONG_ZERO = new Long(0L);
034        /** Reusable Long constant for one. */
035        public static final Long LONG_ONE = new Long(1L);
036        /** Reusable Long constant for minus one. */
037        public static final Long LONG_MINUS_ONE = new Long(-1L);
038        /** Reusable Integer constant for zero. */
039        public static final Integer INTEGER_ZERO = new Integer(0);
040        /** Reusable Integer constant for one. */
041        public static final Integer INTEGER_ONE = new Integer(1);
042        /** Reusable Integer constant for minus one. */
043        public static final Integer INTEGER_MINUS_ONE = new Integer(-1);
044        /** Reusable Short constant for zero. */
045        public static final Short SHORT_ZERO = new Short((short) 0);
046        /** Reusable Short constant for one. */
047        public static final Short SHORT_ONE = new Short((short) 1);
048        /** Reusable Short constant for minus one. */
049        public static final Short SHORT_MINUS_ONE = new Short((short) -1);
050        /** Reusable Byte constant for zero. */
051        public static final Byte BYTE_ZERO = Byte.valueOf((byte) 0);
052        /** Reusable Byte constant for one. */
053        public static final Byte BYTE_ONE = Byte.valueOf((byte) 1);
054        /** Reusable Byte constant for minus one. */
055        public static final Byte BYTE_MINUS_ONE = Byte.valueOf((byte) -1);
056        /** Reusable Double constant for zero. */
057        public static final Double DOUBLE_ZERO = new Double(0.0d);
058        /** Reusable Double constant for one. */
059        public static final Double DOUBLE_ONE = new Double(1.0d);
060        /** Reusable Double constant for minus one. */
061        public static final Double DOUBLE_MINUS_ONE = new Double(-1.0d);
062        /** Reusable Float constant for zero. */
063        public static final Float FLOAT_ZERO = new Float(0.0f);
064        /** Reusable Float constant for one. */
065        public static final Float FLOAT_ONE = new Float(1.0f);
066        /** Reusable Float constant for minus one. */
067        public static final Float FLOAT_MINUS_ONE = new Float(-1.0f);
068    
069        /**
070         * <p><code>NumberUtils</code> instances should NOT be constructed in standard programming.
071         * Instead, the class should be used as <code>NumberUtils.toInt("6");</code>.</p>
072         *
073         * <p>This constructor is public to permit tools that require a JavaBean instance
074         * to operate.</p>
075         */
076        public NumberUtils() {
077            super();
078        }
079    
080        //-----------------------------------------------------------------------
081        /**
082         * <p>Convert a <code>String</code> to an <code>int</code>, returning
083         * <code>zero</code> if the conversion fails.</p>
084         *
085         * <p>If the string is <code>null</code>, <code>zero</code> is returned.</p>
086         *
087         * <pre>
088         *   NumberUtils.toInt(null) = 0
089         *   NumberUtils.toInt("")   = 0
090         *   NumberUtils.toInt("1")  = 1
091         * </pre>
092         *
093         * @param str  the string to convert, may be null
094         * @return the int represented by the string, or <code>zero</code> if
095         *  conversion fails
096         * @since 2.1
097         */
098        public static int toInt(String str) {
099            return toInt(str, 0);
100        }
101    
102        /**
103         * <p>Convert a <code>String</code> to an <code>int</code>, returning a
104         * default value if the conversion fails.</p>
105         *
106         * <p>If the string is <code>null</code>, the default value is returned.</p>
107         *
108         * <pre>
109         *   NumberUtils.toInt(null, 1) = 1
110         *   NumberUtils.toInt("", 1)   = 1
111         *   NumberUtils.toInt("1", 0)  = 1
112         * </pre>
113         *
114         * @param str  the string to convert, may be null
115         * @param defaultValue  the default value
116         * @return the int represented by the string, or the default if conversion fails
117         * @since 2.1
118         */
119        public static int toInt(String str, int defaultValue) {
120            if(str == null) {
121                return defaultValue;
122            }
123            try {
124                return Integer.parseInt(str);
125            } catch (NumberFormatException nfe) {
126                return defaultValue;
127            }
128        }
129    
130        /**
131         * <p>Convert a <code>String</code> to a <code>long</code>, returning
132         * <code>zero</code> if the conversion fails.</p>
133         *
134         * <p>If the string is <code>null</code>, <code>zero</code> is returned.</p>
135         *
136         * <pre>
137         *   NumberUtils.toLong(null) = 0L
138         *   NumberUtils.toLong("")   = 0L
139         *   NumberUtils.toLong("1")  = 1L
140         * </pre>
141         *
142         * @param str  the string to convert, may be null
143         * @return the long represented by the string, or <code>0</code> if
144         *  conversion fails
145         * @since 2.1
146         */
147        public static long toLong(String str) {
148            return toLong(str, 0L);
149        }
150    
151        /**
152         * <p>Convert a <code>String</code> to a <code>long</code>, returning a
153         * default value if the conversion fails.</p>
154         *
155         * <p>If the string is <code>null</code>, the default value is returned.</p>
156         *
157         * <pre>
158         *   NumberUtils.toLong(null, 1L) = 1L
159         *   NumberUtils.toLong("", 1L)   = 1L
160         *   NumberUtils.toLong("1", 0L)  = 1L
161         * </pre>
162         *
163         * @param str  the string to convert, may be null
164         * @param defaultValue  the default value
165         * @return the long represented by the string, or the default if conversion fails
166         * @since 2.1
167         */
168        public static long toLong(String str, long defaultValue) {
169            if (str == null) {
170                return defaultValue;
171            }
172            try {
173                return Long.parseLong(str);
174            } catch (NumberFormatException nfe) {
175                return defaultValue;
176            }
177        }
178    
179        /**
180         * <p>Convert a <code>String</code> to a <code>float</code>, returning
181         * <code>0.0f</code> if the conversion fails.</p>
182         *
183         * <p>If the string <code>str</code> is <code>null</code>,
184         * <code>0.0f</code> is returned.</p>
185         *
186         * <pre>
187         *   NumberUtils.toFloat(null)   = 0.0f
188         *   NumberUtils.toFloat("")     = 0.0f
189         *   NumberUtils.toFloat("1.5")  = 1.5f
190         * </pre>
191         *
192         * @param str the string to convert, may be <code>null</code>
193         * @return the float represented by the string, or <code>0.0f</code>
194         *  if conversion fails
195         * @since 2.1
196         */
197        public static float toFloat(String str) {
198            return toFloat(str, 0.0f);
199        }
200    
201        /**
202         * <p>Convert a <code>String</code> to a <code>float</code>, returning a
203         * default value if the conversion fails.</p>
204         *
205         * <p>If the string <code>str</code> is <code>null</code>, the default
206         * value is returned.</p>
207         *
208         * <pre>
209         *   NumberUtils.toFloat(null, 1.1f)   = 1.0f
210         *   NumberUtils.toFloat("", 1.1f)     = 1.1f
211         *   NumberUtils.toFloat("1.5", 0.0f)  = 1.5f
212         * </pre>
213         *
214         * @param str the string to convert, may be <code>null</code>
215         * @param defaultValue the default value
216         * @return the float represented by the string, or defaultValue
217         *  if conversion fails
218         * @since 2.1
219         */
220        public static float toFloat(String str, float defaultValue) {
221          if (str == null) {
222              return defaultValue;
223          }     
224          try {
225              return Float.parseFloat(str);
226          } catch (NumberFormatException nfe) {
227              return defaultValue;
228          }
229        }
230    
231        /**
232         * <p>Convert a <code>String</code> to a <code>double</code>, returning
233         * <code>0.0d</code> if the conversion fails.</p>
234         *
235         * <p>If the string <code>str</code> is <code>null</code>,
236         * <code>0.0d</code> is returned.</p>
237         *
238         * <pre>
239         *   NumberUtils.toDouble(null)   = 0.0d
240         *   NumberUtils.toDouble("")     = 0.0d
241         *   NumberUtils.toDouble("1.5")  = 1.5d
242         * </pre>
243         *
244         * @param str the string to convert, may be <code>null</code>
245         * @return the double represented by the string, or <code>0.0d</code>
246         *  if conversion fails
247         * @since 2.1
248         */
249        public static double toDouble(String str) {
250            return toDouble(str, 0.0d);
251        }
252    
253        /**
254         * <p>Convert a <code>String</code> to a <code>double</code>, returning a
255         * default value if the conversion fails.</p>
256         *
257         * <p>If the string <code>str</code> is <code>null</code>, the default
258         * value is returned.</p>
259         *
260         * <pre>
261         *   NumberUtils.toDouble(null, 1.1d)   = 1.1d
262         *   NumberUtils.toDouble("", 1.1d)     = 1.1d
263         *   NumberUtils.toDouble("1.5", 0.0d)  = 1.5d
264         * </pre>
265         *
266         * @param str the string to convert, may be <code>null</code>
267         * @param defaultValue the default value
268         * @return the double represented by the string, or defaultValue
269         *  if conversion fails
270         * @since 2.1
271         */
272        public static double toDouble(String str, double defaultValue) {
273          if (str == null) {
274              return defaultValue;
275          }
276          try {
277              return Double.parseDouble(str);
278          } catch (NumberFormatException nfe) {
279              return defaultValue;
280          }
281        }
282    
283         //-----------------------------------------------------------------------
284         /**
285         * <p>Convert a <code>String</code> to a <code>byte</code>, returning
286         * <code>zero</code> if the conversion fails.</p>
287         *
288         * <p>If the string is <code>null</code>, <code>zero</code> is returned.</p>
289         *
290         * <pre>
291         *   NumberUtils.toByte(null) = 0
292         *   NumberUtils.toByte("")   = 0
293         *   NumberUtils.toByte("1")  = 1
294         * </pre>
295         *
296         * @param str  the string to convert, may be null
297         * @return the byte represented by the string, or <code>zero</code> if
298         *  conversion fails
299         * @since 2.5
300         */
301        public static byte toByte(String str) {
302            return toByte(str, (byte) 0);
303        }
304    
305        /**
306         * <p>Convert a <code>String</code> to a <code>byte</code>, returning a
307         * default value if the conversion fails.</p>
308         *
309         * <p>If the string is <code>null</code>, the default value is returned.</p>
310         *
311         * <pre>
312         *   NumberUtils.toByte(null, 1) = 1
313         *   NumberUtils.toByte("", 1)   = 1
314         *   NumberUtils.toByte("1", 0)  = 1
315         * </pre>
316         *
317         * @param str  the string to convert, may be null
318         * @param defaultValue  the default value
319         * @return the byte represented by the string, or the default if conversion fails
320         * @since 2.5
321         */
322        public static byte toByte(String str, byte defaultValue) {
323            if(str == null) {
324                return defaultValue;
325            }
326            try {
327                return Byte.parseByte(str);
328            } catch (NumberFormatException nfe) {
329                return defaultValue;
330            }
331        }
332    
333        /**
334         * <p>Convert a <code>String</code> to a <code>short</code>, returning
335         * <code>zero</code> if the conversion fails.</p>
336         *
337         * <p>If the string is <code>null</code>, <code>zero</code> is returned.</p>
338         *
339         * <pre>
340         *   NumberUtils.toShort(null) = 0
341         *   NumberUtils.toShort("")   = 0
342         *   NumberUtils.toShort("1")  = 1
343         * </pre>
344         *
345         * @param str  the string to convert, may be null
346         * @return the short represented by the string, or <code>zero</code> if
347         *  conversion fails
348         * @since 2.5
349         */
350        public static short toShort(String str) {
351            return toShort(str, (short) 0);
352        }
353    
354        /**
355         * <p>Convert a <code>String</code> to an <code>short</code>, returning a
356         * default value if the conversion fails.</p>
357         *
358         * <p>If the string is <code>null</code>, the default value is returned.</p>
359         *
360         * <pre>
361         *   NumberUtils.toShort(null, 1) = 1
362         *   NumberUtils.toShort("", 1)   = 1
363         *   NumberUtils.toShort("1", 0)  = 1
364         * </pre>
365         *
366         * @param str  the string to convert, may be null
367         * @param defaultValue  the default value
368         * @return the short represented by the string, or the default if conversion fails
369         * @since 2.5
370         */
371        public static short toShort(String str, short defaultValue) {
372            if(str == null) {
373                return defaultValue;
374            }
375            try {
376                return Short.parseShort(str);
377            } catch (NumberFormatException nfe) {
378                return defaultValue;
379            }
380        }
381    
382        //-----------------------------------------------------------------------
383        // must handle Long, Float, Integer, Float, Short,
384        //                  BigDecimal, BigInteger and Byte
385        // useful methods:
386        // Byte.decode(String)
387        // Byte.valueOf(String,int radix)
388        // Byte.valueOf(String)
389        // Double.valueOf(String)
390        // Float.valueOf(String)
391        // new Float(String)
392        // Integer.valueOf(String,int radix)
393        // Integer.valueOf(String)
394        // Integer.decode(String)
395        // Integer.getInteger(String)
396        // Integer.getInteger(String,int val)
397        // Integer.getInteger(String,Integer val)
398        // new Integer(String)
399        // new Double(String)
400        // new Byte(String)
401        // new Long(String)
402        // Long.getLong(String)
403        // Long.getLong(String,int)
404        // Long.getLong(String,Integer)
405        // Long.valueOf(String,int)
406        // Long.valueOf(String)
407        // new Short(String)
408        // Short.decode(String)
409        // Short.valueOf(String,int)
410        // Short.valueOf(String)
411        // new BigDecimal(String)
412        // new BigInteger(String)
413        // new BigInteger(String,int radix)
414        // Possible inputs:
415        // 45 45.5 45E7 4.5E7 Hex Oct Binary xxxF xxxD xxxf xxxd
416        // plus minus everything. Prolly more. A lot are not separable.
417    
418        /**
419         * <p>Turns a string value into a java.lang.Number.</p>
420         *
421         * <p>First, the value is examined for a type qualifier on the end
422         * (<code>'f','F','d','D','l','L'</code>).  If it is found, it starts 
423         * trying to create successively larger types from the type specified
424         * until one is found that can represent the value.</p>
425         *
426         * <p>If a type specifier is not found, it will check for a decimal point
427         * and then try successively larger types from <code>Integer</code> to
428         * <code>BigInteger</code> and from <code>Float</code> to
429         * <code>BigDecimal</code>.</p>
430         *
431         * <p>If the string starts with <code>0x</code> or <code>-0x</code>, it
432         * will be interpreted as a hexadecimal integer.  Values with leading
433         * <code>0</code>'s will not be interpreted as octal.</p>
434         *
435         * <p>Returns <code>null</code> if the string is <code>null</code>.</p>
436         *
437         * <p>This method does not trim the input string, i.e., strings with leading
438         * or trailing spaces will generate NumberFormatExceptions.</p>
439         *
440         * @param str  String containing a number, may be null
441         * @return Number created from the string
442         * @throws NumberFormatException if the value cannot be converted
443         */
444        public static Number createNumber(String str) throws NumberFormatException {
445            if (str == null) {
446                return null;
447            }
448            if (StringUtils.isBlank(str)) {
449                throw new NumberFormatException("A blank string is not a valid number");
450            }  
451            if (str.startsWith("--")) {
452                // this is protection for poorness in java.lang.BigDecimal.
453                // it accepts this as a legal value, but it does not appear 
454                // to be in specification of class. OS X Java parses it to 
455                // a wrong value.
456                return null;
457            }
458            if (str.startsWith("0x") || str.startsWith("-0x")) {
459                return createInteger(str);
460            }   
461            char lastChar = str.charAt(str.length() - 1);
462            String mant;
463            String dec;
464            String exp;
465            int decPos = str.indexOf('.');
466            int expPos = str.indexOf('e') + str.indexOf('E') + 1;
467    
468            if (decPos > -1) {
469    
470                if (expPos > -1) {
471                    if (expPos < decPos || expPos > str.length()) {
472                        throw new NumberFormatException(str + " is not a valid number.");
473                    }
474                    dec = str.substring(decPos + 1, expPos);
475                } else {
476                    dec = str.substring(decPos + 1);
477                }
478                mant = str.substring(0, decPos);
479            } else {
480                if (expPos > -1) {
481                    if (expPos > str.length()) {
482                        throw new NumberFormatException(str + " is not a valid number.");
483                    }
484                    mant = str.substring(0, expPos);
485                } else {
486                    mant = str;
487                }
488                dec = null;
489            }
490            if (!Character.isDigit(lastChar) && lastChar != '.') {
491                if (expPos > -1 && expPos < str.length() - 1) {
492                    exp = str.substring(expPos + 1, str.length() - 1);
493                } else {
494                    exp = null;
495                }
496                //Requesting a specific type..
497                String numeric = str.substring(0, str.length() - 1);
498                boolean allZeros = isAllZeros(mant) && isAllZeros(exp);
499                switch (lastChar) {
500                    case 'l' :
501                    case 'L' :
502                        if (dec == null
503                            && exp == null
504                            && (numeric.charAt(0) == '-' && isDigits(numeric.substring(1)) || isDigits(numeric))) {
505                            try {
506                                return createLong(numeric);
507                            } catch (NumberFormatException nfe) { // NOPMD
508                                // Too big for a long
509                            }
510                            return createBigInteger(numeric);
511    
512                        }
513                        throw new NumberFormatException(str + " is not a valid number.");
514                    case 'f' :
515                    case 'F' :
516                        try {
517                            Float f = NumberUtils.createFloat(numeric);
518                            if (!(f.isInfinite() || (f.floatValue() == 0.0F && !allZeros))) {
519                                //If it's too big for a float or the float value = 0 and the string
520                                //has non-zeros in it, then float does not have the precision we want
521                                return f;
522                            }
523    
524                        } catch (NumberFormatException nfe) { // NOPMD
525                            // ignore the bad number
526                        }
527                        //$FALL-THROUGH$
528                    case 'd' :
529                    case 'D' :
530                        try {
531                            Double d = NumberUtils.createDouble(numeric);
532                            if (!(d.isInfinite() || (d.floatValue() == 0.0D && !allZeros))) {
533                                return d;
534                            }
535                        } catch (NumberFormatException nfe) { // NOPMD
536                            // ignore the bad number
537                        }
538                        try {
539                            return createBigDecimal(numeric);
540                        } catch (NumberFormatException e) { // NOPMD
541                            // ignore the bad number
542                        }
543                        //$FALL-THROUGH$
544                    default :
545                        throw new NumberFormatException(str + " is not a valid number.");
546    
547                }
548            } else {
549                //User doesn't have a preference on the return type, so let's start
550                //small and go from there...
551                if (expPos > -1 && expPos < str.length() - 1) {
552                    exp = str.substring(expPos + 1, str.length());
553                } else {
554                    exp = null;
555                }
556                if (dec == null && exp == null) {
557                    //Must be an int,long,bigint
558                    try {
559                        return createInteger(str);
560                    } catch (NumberFormatException nfe) { // NOPMD
561                        // ignore the bad number
562                    }
563                    try {
564                        return createLong(str);
565                    } catch (NumberFormatException nfe) { // NOPMD
566                        // ignore the bad number
567                    }
568                    return createBigInteger(str);
569    
570                } else {
571                    //Must be a float,double,BigDec
572                    boolean allZeros = isAllZeros(mant) && isAllZeros(exp);
573                    try {
574                        Float f = createFloat(str);
575                        if (!(f.isInfinite() || (f.floatValue() == 0.0F && !allZeros))) {
576                            return f;
577                        }
578                    } catch (NumberFormatException nfe) { // NOPMD
579                        // ignore the bad number
580                    }
581                    try {
582                        Double d = createDouble(str);
583                        if (!(d.isInfinite() || (d.doubleValue() == 0.0D && !allZeros))) {
584                            return d;
585                        }
586                    } catch (NumberFormatException nfe) { // NOPMD
587                        // ignore the bad number
588                    }
589    
590                    return createBigDecimal(str);
591    
592                }
593            }
594        }
595    
596        /**
597         * <p>Utility method for {@link #createNumber(java.lang.String)}.</p>
598         *
599         * <p>Returns <code>true</code> if s is <code>null</code>.</p>
600         * 
601         * @param str  the String to check
602         * @return if it is all zeros or <code>null</code>
603         */
604        private static boolean isAllZeros(String str) {
605            if (str == null) {
606                return true;
607            }
608            for (int i = str.length() - 1; i >= 0; i--) {
609                if (str.charAt(i) != '0') {
610                    return false;
611                }
612            }
613            return str.length() > 0;
614        }
615    
616        //-----------------------------------------------------------------------
617        /**
618         * <p>Convert a <code>String</code> to a <code>Float</code>.</p>
619         *
620         * <p>Returns <code>null</code> if the string is <code>null</code>.</p>
621         * 
622         * @param str  a <code>String</code> to convert, may be null
623         * @return converted <code>Float</code>
624         * @throws NumberFormatException if the value cannot be converted
625         */
626        public static Float createFloat(String str) {
627            if (str == null) {
628                return null;
629            }
630            return Float.valueOf(str);
631        }
632    
633        /**
634         * <p>Convert a <code>String</code> to a <code>Double</code>.</p>
635         * 
636         * <p>Returns <code>null</code> if the string is <code>null</code>.</p>
637         *
638         * @param str  a <code>String</code> to convert, may be null
639         * @return converted <code>Double</code>
640         * @throws NumberFormatException if the value cannot be converted
641         */
642        public static Double createDouble(String str) {
643            if (str == null) {
644                return null;
645            }
646            return Double.valueOf(str);
647        }
648    
649        /**
650         * <p>Convert a <code>String</code> to a <code>Integer</code>, handling
651         * hex and octal notations.</p>
652         *
653         * <p>Returns <code>null</code> if the string is <code>null</code>.</p>
654         * 
655         * @param str  a <code>String</code> to convert, may be null
656         * @return converted <code>Integer</code>
657         * @throws NumberFormatException if the value cannot be converted
658         */
659        public static Integer createInteger(String str) {
660            if (str == null) {
661                return null;
662            }
663            // decode() handles 0xAABD and 0777 (hex and octal) as well.
664            return Integer.decode(str);
665        }
666    
667        /**
668         * <p>Convert a <code>String</code> to a <code>Long</code>.</p>
669         * 
670         * <p>Returns <code>null</code> if the string is <code>null</code>.</p>
671         *
672         * @param str  a <code>String</code> to convert, may be null
673         * @return converted <code>Long</code>
674         * @throws NumberFormatException if the value cannot be converted
675         */
676        public static Long createLong(String str) {
677            if (str == null) {
678                return null;
679            }
680            return Long.valueOf(str);
681        }
682    
683        /**
684         * <p>Convert a <code>String</code> to a <code>BigInteger</code>.</p>
685         *
686         * <p>Returns <code>null</code> if the string is <code>null</code>.</p>
687         * 
688         * @param str  a <code>String</code> to convert, may be null
689         * @return converted <code>BigInteger</code>
690         * @throws NumberFormatException if the value cannot be converted
691         */
692        public static BigInteger createBigInteger(String str) {
693            if (str == null) {
694                return null;
695            }
696            return new BigInteger(str);
697        }
698    
699        /**
700         * <p>Convert a <code>String</code> to a <code>BigDecimal</code>.</p>
701         * 
702         * <p>Returns <code>null</code> if the string is <code>null</code>.</p>
703         *
704         * @param str  a <code>String</code> to convert, may be null
705         * @return converted <code>BigDecimal</code>
706         * @throws NumberFormatException if the value cannot be converted
707         */
708        public static BigDecimal createBigDecimal(String str) {
709            if (str == null) {
710                return null;
711            }
712            // handle JDK1.3.1 bug where "" throws IndexOutOfBoundsException
713            if (StringUtils.isBlank(str)) {
714                throw new NumberFormatException("A blank string is not a valid number");
715            }  
716            return new BigDecimal(str);
717        }
718    
719        // Min in array
720        //--------------------------------------------------------------------
721        /**
722         * <p>Returns the minimum value in an array.</p>
723         * 
724         * @param array  an array, must not be null or empty
725         * @return the minimum value in the array
726         * @throws IllegalArgumentException if <code>array</code> is <code>null</code>
727         * @throws IllegalArgumentException if <code>array</code> is empty
728         */
729        public static long min(long[] array) {
730            // Validates input
731            if (array == null) {
732                throw new IllegalArgumentException("The Array must not be null");
733            } else if (array.length == 0) {
734                throw new IllegalArgumentException("Array cannot be empty.");
735            }
736        
737            // Finds and returns min
738            long min = array[0];
739            for (int i = 1; i < array.length; i++) {
740                if (array[i] < min) {
741                    min = array[i];
742                }
743            }
744        
745            return min;
746        }
747    
748        /**
749         * <p>Returns the minimum value in an array.</p>
750         * 
751         * @param array  an array, must not be null or empty
752         * @return the minimum value in the array
753         * @throws IllegalArgumentException if <code>array</code> is <code>null</code>
754         * @throws IllegalArgumentException if <code>array</code> is empty
755         */
756        public static int min(int[] array) {
757            // Validates input
758            if (array == null) {
759                throw new IllegalArgumentException("The Array must not be null");
760            } else if (array.length == 0) {
761                throw new IllegalArgumentException("Array cannot be empty.");
762            }
763        
764            // Finds and returns min
765            int min = array[0];
766            for (int j = 1; j < array.length; j++) {
767                if (array[j] < min) {
768                    min = array[j];
769                }
770            }
771        
772            return min;
773        }
774    
775        /**
776         * <p>Returns the minimum value in an array.</p>
777         * 
778         * @param array  an array, must not be null or empty
779         * @return the minimum value in the array
780         * @throws IllegalArgumentException if <code>array</code> is <code>null</code>
781         * @throws IllegalArgumentException if <code>array</code> is empty
782         */
783        public static short min(short[] array) {
784            // Validates input
785            if (array == null) {
786                throw new IllegalArgumentException("The Array must not be null");
787            } else if (array.length == 0) {
788                throw new IllegalArgumentException("Array cannot be empty.");
789            }
790        
791            // Finds and returns min
792            short min = array[0];
793            for (int i = 1; i < array.length; i++) {
794                if (array[i] < min) {
795                    min = array[i];
796                }
797            }
798        
799            return min;
800        }
801    
802        /**
803         * <p>Returns the minimum value in an array.</p>
804         * 
805         * @param array  an array, must not be null or empty
806         * @return the minimum value in the array
807         * @throws IllegalArgumentException if <code>array</code> is <code>null</code>
808         * @throws IllegalArgumentException if <code>array</code> is empty
809         */
810        public static byte min(byte[] array) {
811            // Validates input
812            if (array == null) {
813                throw new IllegalArgumentException("The Array must not be null");
814            } else if (array.length == 0) {
815                throw new IllegalArgumentException("Array cannot be empty.");
816            }
817        
818            // Finds and returns min
819            byte min = array[0];
820            for (int i = 1; i < array.length; i++) {
821                if (array[i] < min) {
822                    min = array[i];
823                }
824            }
825        
826            return min;
827        }
828    
829         /**
830         * <p>Returns the minimum value in an array.</p>
831         * 
832         * @param array  an array, must not be null or empty
833         * @return the minimum value in the array
834         * @throws IllegalArgumentException if <code>array</code> is <code>null</code>
835         * @throws IllegalArgumentException if <code>array</code> is empty
836         * @see IEEE754rUtils#min(double[]) IEEE754rUtils for a version of this method that handles NaN differently
837         */
838        public static double min(double[] array) {
839            // Validates input
840            if (array == null) {
841                throw new IllegalArgumentException("The Array must not be null");
842            } else if (array.length == 0) {
843                throw new IllegalArgumentException("Array cannot be empty.");
844            }
845        
846            // Finds and returns min
847            double min = array[0];
848            for (int i = 1; i < array.length; i++) {
849                if (Double.isNaN(array[i])) {
850                    return Double.NaN;
851                }
852                if (array[i] < min) {
853                    min = array[i];
854                }
855            }
856        
857            return min;
858        }
859    
860        /**
861         * <p>Returns the minimum value in an array.</p>
862         * 
863         * @param array  an array, must not be null or empty
864         * @return the minimum value in the array
865         * @throws IllegalArgumentException if <code>array</code> is <code>null</code>
866         * @throws IllegalArgumentException if <code>array</code> is empty
867         * @see IEEE754rUtils#min(float[]) IEEE754rUtils for a version of this method that handles NaN differently
868         */
869        public static float min(float[] array) {
870            // Validates input
871            if (array == null) {
872                throw new IllegalArgumentException("The Array must not be null");
873            } else if (array.length == 0) {
874                throw new IllegalArgumentException("Array cannot be empty.");
875            }
876        
877            // Finds and returns min
878            float min = array[0];
879            for (int i = 1; i < array.length; i++) {
880                if (Float.isNaN(array[i])) {
881                    return Float.NaN;
882                }
883                if (array[i] < min) {
884                    min = array[i];
885                }
886            }
887        
888            return min;
889        }
890    
891        // Max in array
892        //--------------------------------------------------------------------
893        /**
894         * <p>Returns the maximum value in an array.</p>
895         * 
896         * @param array  an array, must not be null or empty
897         * @return the minimum value in the array
898         * @throws IllegalArgumentException if <code>array</code> is <code>null</code>
899         * @throws IllegalArgumentException if <code>array</code> is empty
900         */
901        public static long max(long[] array) {
902            // Validates input
903            if (array == null) {
904                throw new IllegalArgumentException("The Array must not be null");
905            } else if (array.length == 0) {
906                throw new IllegalArgumentException("Array cannot be empty.");
907            }
908    
909            // Finds and returns max
910            long max = array[0];
911            for (int j = 1; j < array.length; j++) {
912                if (array[j] > max) {
913                    max = array[j];
914                }
915            }
916    
917            return max;
918        }
919    
920        /**
921         * <p>Returns the maximum value in an array.</p>
922         * 
923         * @param array  an array, must not be null or empty
924         * @return the minimum value in the array
925         * @throws IllegalArgumentException if <code>array</code> is <code>null</code>
926         * @throws IllegalArgumentException if <code>array</code> is empty
927         */
928        public static int max(int[] array) {
929            // Validates input
930            if (array == null) {
931                throw new IllegalArgumentException("The Array must not be null");
932            } else if (array.length == 0) {
933                throw new IllegalArgumentException("Array cannot be empty.");
934            }
935        
936            // Finds and returns max
937            int max = array[0];
938            for (int j = 1; j < array.length; j++) {
939                if (array[j] > max) {
940                    max = array[j];
941                }
942            }
943        
944            return max;
945        }
946    
947        /**
948         * <p>Returns the maximum value in an array.</p>
949         * 
950         * @param array  an array, must not be null or empty
951         * @return the minimum value in the array
952         * @throws IllegalArgumentException if <code>array</code> is <code>null</code>
953         * @throws IllegalArgumentException if <code>array</code> is empty
954         */
955        public static short max(short[] array) {
956            // Validates input
957            if (array == null) {
958                throw new IllegalArgumentException("The Array must not be null");
959            } else if (array.length == 0) {
960                throw new IllegalArgumentException("Array cannot be empty.");
961            }
962        
963            // Finds and returns max
964            short max = array[0];
965            for (int i = 1; i < array.length; i++) {
966                if (array[i] > max) {
967                    max = array[i];
968                }
969            }
970        
971            return max;
972        }
973    
974        /**
975         * <p>Returns the maximum value in an array.</p>
976         * 
977         * @param array  an array, must not be null or empty
978         * @return the minimum value in the array
979         * @throws IllegalArgumentException if <code>array</code> is <code>null</code>
980         * @throws IllegalArgumentException if <code>array</code> is empty
981         */
982        public static byte max(byte[] array) {
983            // Validates input
984            if (array == null) {
985                throw new IllegalArgumentException("The Array must not be null");
986            } else if (array.length == 0) {
987                throw new IllegalArgumentException("Array cannot be empty.");
988            }
989        
990            // Finds and returns max
991            byte max = array[0];
992            for (int i = 1; i < array.length; i++) {
993                if (array[i] > max) {
994                    max = array[i];
995                }
996            }
997        
998            return max;
999        }
1000    
1001        /**
1002         * <p>Returns the maximum value in an array.</p>
1003         * 
1004         * @param array  an array, must not be null or empty
1005         * @return the minimum value in the array
1006         * @throws IllegalArgumentException if <code>array</code> is <code>null</code>
1007         * @throws IllegalArgumentException if <code>array</code> is empty
1008         * @see IEEE754rUtils#max(double[]) IEEE754rUtils for a version of this method that handles NaN differently
1009         */
1010        public static double max(double[] array) {
1011            // Validates input
1012            if (array== null) {
1013                throw new IllegalArgumentException("The Array must not be null");
1014            } else if (array.length == 0) {
1015                throw new IllegalArgumentException("Array cannot be empty.");
1016            }
1017        
1018            // Finds and returns max
1019            double max = array[0];
1020            for (int j = 1; j < array.length; j++) {
1021                if (Double.isNaN(array[j])) {
1022                    return Double.NaN;
1023                }
1024                if (array[j] > max) {
1025                    max = array[j];
1026                }
1027            }
1028        
1029            return max;
1030        }
1031    
1032        /**
1033         * <p>Returns the maximum value in an array.</p>
1034         * 
1035         * @param array  an array, must not be null or empty
1036         * @return the minimum value in the array
1037         * @throws IllegalArgumentException if <code>array</code> is <code>null</code>
1038         * @throws IllegalArgumentException if <code>array</code> is empty
1039         * @see IEEE754rUtils#max(float[]) IEEE754rUtils for a version of this method that handles NaN differently
1040         */
1041        public static float max(float[] array) {
1042            // Validates input
1043            if (array == null) {
1044                throw new IllegalArgumentException("The Array must not be null");
1045            } else if (array.length == 0) {
1046                throw new IllegalArgumentException("Array cannot be empty.");
1047            }
1048    
1049            // Finds and returns max
1050            float max = array[0];
1051            for (int j = 1; j < array.length; j++) {
1052                if (Float.isNaN(array[j])) {
1053                    return Float.NaN;
1054                }
1055                if (array[j] > max) {
1056                    max = array[j];
1057                }
1058            }
1059    
1060            return max;
1061        }
1062         
1063        // 3 param min
1064        //-----------------------------------------------------------------------
1065        /**
1066         * <p>Gets the minimum of three <code>long</code> values.</p>
1067         * 
1068         * @param a  value 1
1069         * @param b  value 2
1070         * @param c  value 3
1071         * @return  the smallest of the values
1072         */
1073        public static long min(long a, long b, long c) {
1074            if (b < a) {
1075                a = b;
1076            }
1077            if (c < a) {
1078                a = c;
1079            }
1080            return a;
1081        }
1082    
1083        /**
1084         * <p>Gets the minimum of three <code>int</code> values.</p>
1085         * 
1086         * @param a  value 1
1087         * @param b  value 2
1088         * @param c  value 3
1089         * @return  the smallest of the values
1090         */
1091        public static int min(int a, int b, int c) {
1092            if (b < a) {
1093                a = b;
1094            }
1095            if (c < a) {
1096                a = c;
1097            }
1098            return a;
1099        }
1100    
1101        /**
1102         * <p>Gets the minimum of three <code>short</code> values.</p>
1103         * 
1104         * @param a  value 1
1105         * @param b  value 2
1106         * @param c  value 3
1107         * @return  the smallest of the values
1108         */
1109        public static short min(short a, short b, short c) {
1110            if (b < a) {
1111                a = b;
1112            }
1113            if (c < a) {
1114                a = c;
1115            }
1116            return a;
1117        }
1118    
1119        /**
1120         * <p>Gets the minimum of three <code>byte</code> values.</p>
1121         * 
1122         * @param a  value 1
1123         * @param b  value 2
1124         * @param c  value 3
1125         * @return  the smallest of the values
1126         */
1127        public static byte min(byte a, byte b, byte c) {
1128            if (b < a) {
1129                a = b;
1130            }
1131            if (c < a) {
1132                a = c;
1133            }
1134            return a;
1135        }
1136    
1137        /**
1138         * <p>Gets the minimum of three <code>double</code> values.</p>
1139         * 
1140         * <p>If any value is <code>NaN</code>, <code>NaN</code> is
1141         * returned. Infinity is handled.</p>
1142         * 
1143         * @param a  value 1
1144         * @param b  value 2
1145         * @param c  value 3
1146         * @return  the smallest of the values
1147         * @see IEEE754rUtils#min(double, double, double) for a version of this method that handles NaN differently
1148         */
1149        public static double min(double a, double b, double c) {
1150            return Math.min(Math.min(a, b), c);
1151        }
1152    
1153        /**
1154         * <p>Gets the minimum of three <code>float</code> values.</p>
1155         * 
1156         * <p>If any value is <code>NaN</code>, <code>NaN</code> is
1157         * returned. Infinity is handled.</p>
1158         *
1159         * @param a  value 1
1160         * @param b  value 2
1161         * @param c  value 3
1162         * @return  the smallest of the values
1163         * @see IEEE754rUtils#min(float, float, float) for a version of this method that handles NaN differently
1164         */
1165        public static float min(float a, float b, float c) {
1166            return Math.min(Math.min(a, b), c);
1167        }
1168    
1169        // 3 param max
1170        //-----------------------------------------------------------------------
1171        /**
1172         * <p>Gets the maximum of three <code>long</code> values.</p>
1173         * 
1174         * @param a  value 1
1175         * @param b  value 2
1176         * @param c  value 3
1177         * @return  the largest of the values
1178         */
1179        public static long max(long a, long b, long c) {
1180            if (b > a) {
1181                a = b;
1182            }
1183            if (c > a) {
1184                a = c;
1185            }
1186            return a;
1187        }
1188    
1189        /**
1190         * <p>Gets the maximum of three <code>int</code> values.</p>
1191         * 
1192         * @param a  value 1
1193         * @param b  value 2
1194         * @param c  value 3
1195         * @return  the largest of the values
1196         */
1197        public static int max(int a, int b, int c) {
1198            if (b > a) {
1199                a = b;
1200            }
1201            if (c > a) {
1202                a = c;
1203            }
1204            return a;
1205        }
1206    
1207        /**
1208         * <p>Gets the maximum of three <code>short</code> values.</p>
1209         * 
1210         * @param a  value 1
1211         * @param b  value 2
1212         * @param c  value 3
1213         * @return  the largest of the values
1214         */
1215        public static short max(short a, short b, short c) {
1216            if (b > a) {
1217                a = b;
1218            }
1219            if (c > a) {
1220                a = c;
1221            }
1222            return a;
1223        }
1224    
1225        /**
1226         * <p>Gets the maximum of three <code>byte</code> values.</p>
1227         * 
1228         * @param a  value 1
1229         * @param b  value 2
1230         * @param c  value 3
1231         * @return  the largest of the values
1232         */
1233        public static byte max(byte a, byte b, byte c) {
1234            if (b > a) {
1235                a = b;
1236            }
1237            if (c > a) {
1238                a = c;
1239            }
1240            return a;
1241        }
1242    
1243        /**
1244         * <p>Gets the maximum of three <code>double</code> values.</p>
1245         * 
1246         * <p>If any value is <code>NaN</code>, <code>NaN</code> is
1247         * returned. Infinity is handled.</p>
1248         *
1249         * @param a  value 1
1250         * @param b  value 2
1251         * @param c  value 3
1252         * @return  the largest of the values
1253         * @see IEEE754rUtils#max(double, double, double) for a version of this method that handles NaN differently
1254         */
1255        public static double max(double a, double b, double c) {
1256            return Math.max(Math.max(a, b), c);
1257        }
1258    
1259        /**
1260         * <p>Gets the maximum of three <code>float</code> values.</p>
1261         * 
1262         * <p>If any value is <code>NaN</code>, <code>NaN</code> is
1263         * returned. Infinity is handled.</p>
1264         *
1265         * @param a  value 1
1266         * @param b  value 2
1267         * @param c  value 3
1268         * @return  the largest of the values
1269         * @see IEEE754rUtils#max(float, float, float) for a version of this method that handles NaN differently
1270         */
1271        public static float max(float a, float b, float c) {
1272            return Math.max(Math.max(a, b), c);
1273        }
1274    
1275        //-----------------------------------------------------------------------
1276        /**
1277         * <p>Checks whether the <code>String</code> contains only
1278         * digit characters.</p>
1279         *
1280         * <p><code>Null</code> and empty String will return
1281         * <code>false</code>.</p>
1282         *
1283         * @param str  the <code>String</code> to check
1284         * @return <code>true</code> if str contains only unicode numeric
1285         */
1286        public static boolean isDigits(String str) {
1287            if (StringUtils.isEmpty(str)) {
1288                return false;
1289            }
1290            for (int i = 0; i < str.length(); i++) {
1291                if (!Character.isDigit(str.charAt(i))) {
1292                    return false;
1293                }
1294            }
1295            return true;
1296        }
1297    
1298        /**
1299         * <p>Checks whether the String a valid Java number.</p>
1300         *
1301         * <p>Valid numbers include hexadecimal marked with the <code>0x</code>
1302         * qualifier, scientific notation and numbers marked with a type
1303         * qualifier (e.g. 123L).</p>
1304         *
1305         * <p><code>Null</code> and empty String will return
1306         * <code>false</code>.</p>
1307         *
1308         * @param str  the <code>String</code> to check
1309         * @return <code>true</code> if the string is a correctly formatted number
1310         */
1311        public static boolean isNumber(String str) {
1312            if (StringUtils.isEmpty(str)) {
1313                return false;
1314            }
1315            char[] chars = str.toCharArray();
1316            int sz = chars.length;
1317            boolean hasExp = false;
1318            boolean hasDecPoint = false;
1319            boolean allowSigns = false;
1320            boolean foundDigit = false;
1321            // deal with any possible sign up front
1322            int start = (chars[0] == '-') ? 1 : 0;
1323            if (sz > start + 1) {
1324                if (chars[start] == '0' && chars[start + 1] == 'x') {
1325                    int i = start + 2;
1326                    if (i == sz) {
1327                        return false; // str == "0x"
1328                    }
1329                    // checking hex (it can't be anything else)
1330                    for (; i < chars.length; i++) {
1331                        if ((chars[i] < '0' || chars[i] > '9')
1332                            && (chars[i] < 'a' || chars[i] > 'f')
1333                            && (chars[i] < 'A' || chars[i] > 'F')) {
1334                            return false;
1335                        }
1336                    }
1337                    return true;
1338                }
1339            }
1340            sz--; // don't want to loop to the last char, check it afterwords
1341                  // for type qualifiers
1342            int i = start;
1343            // loop to the next to last char or to the last char if we need another digit to
1344            // make a valid number (e.g. chars[0..5] = "1234E")
1345            while (i < sz || (i < sz + 1 && allowSigns && !foundDigit)) {
1346                if (chars[i] >= '0' && chars[i] <= '9') {
1347                    foundDigit = true;
1348                    allowSigns = false;
1349    
1350                } else if (chars[i] == '.') {
1351                    if (hasDecPoint || hasExp) {
1352                        // two decimal points or dec in exponent   
1353                        return false;
1354                    }
1355                    hasDecPoint = true;
1356                } else if (chars[i] == 'e' || chars[i] == 'E') {
1357                    // we've already taken care of hex.
1358                    if (hasExp) {
1359                        // two E's
1360                        return false;
1361                    }
1362                    if (!foundDigit) {
1363                        return false;
1364                    }
1365                    hasExp = true;
1366                    allowSigns = true;
1367                } else if (chars[i] == '+' || chars[i] == '-') {
1368                    if (!allowSigns) {
1369                        return false;
1370                    }
1371                    allowSigns = false;
1372                    foundDigit = false; // we need a digit after the E
1373                } else {
1374                    return false;
1375                }
1376                i++;
1377            }
1378            if (i < chars.length) {
1379                if (chars[i] >= '0' && chars[i] <= '9') {
1380                    // no type qualifier, OK
1381                    return true;
1382                }
1383                if (chars[i] == 'e' || chars[i] == 'E') {
1384                    // can't have an E at the last byte
1385                    return false;
1386                }
1387                if (chars[i] == '.') {
1388                    if (hasDecPoint || hasExp) {
1389                        // two decimal points or dec in exponent
1390                        return false;
1391                    }
1392                    // single trailing decimal point after non-exponent is ok
1393                    return foundDigit;
1394                }
1395                if (!allowSigns
1396                    && (chars[i] == 'd'
1397                        || chars[i] == 'D'
1398                        || chars[i] == 'f'
1399                        || chars[i] == 'F')) {
1400                    return foundDigit;
1401                }
1402                if (chars[i] == 'l'
1403                    || chars[i] == 'L') {
1404                    // not allowing L with an exponent or decimal point
1405                    return foundDigit && !hasExp && !hasDecPoint;
1406                }
1407                // last character is illegal
1408                return false;
1409            }
1410            // allowSigns is true iff the val ends in 'E'
1411            // found digit it to make sure weird stuff like '.' and '1E-' doesn't pass
1412            return !allowSigns && foundDigit;
1413        }
1414    
1415    }