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 1199816 2011-11-09 16:11:34Z bayard $
029 */
030 public class NumberUtils {
031
032 /** Reusable Long constant for zero. */
033 public static final Long LONG_ZERO = Long.valueOf(0L);
034 /** Reusable Long constant for one. */
035 public static final Long LONG_ONE = Long.valueOf(1L);
036 /** Reusable Long constant for minus one. */
037 public static final Long LONG_MINUS_ONE = Long.valueOf(-1L);
038 /** Reusable Integer constant for zero. */
039 public static final Integer INTEGER_ZERO = Integer.valueOf(0);
040 /** Reusable Integer constant for one. */
041 public static final Integer INTEGER_ONE = Integer.valueOf(1);
042 /** Reusable Integer constant for minus one. */
043 public static final Integer INTEGER_MINUS_ONE = Integer.valueOf(-1);
044 /** Reusable Short constant for zero. */
045 public static final Short SHORT_ZERO = Short.valueOf((short) 0);
046 /** Reusable Short constant for one. */
047 public static final Short SHORT_ONE = Short.valueOf((short) 1);
048 /** Reusable Short constant for minus one. */
049 public static final Short SHORT_MINUS_ONE = Short.valueOf((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 = Double.valueOf(0.0d);
058 /** Reusable Double constant for one. */
059 public static final Double DOUBLE_ONE = Double.valueOf(1.0d);
060 /** Reusable Double constant for minus one. */
061 public static final Double DOUBLE_MINUS_ONE = Double.valueOf(-1.0d);
062 /** Reusable Float constant for zero. */
063 public static final Float FLOAT_ZERO = Float.valueOf(0.0f);
064 /** Reusable Float constant for one. */
065 public static final Float FLOAT_ONE = Float.valueOf(1.0f);
066 /** Reusable Float constant for minus one. */
067 public static final Float FLOAT_MINUS_ONE = Float.valueOf(-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 // Float.valueOf(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 // Integer.valueOf(String)
399 // Double.valueOf(String)
400 // new Byte(String)
401 // Long.valueOf(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 // Short.valueOf(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> (lower or upper case), 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 (or null if the input is null)
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") || 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>;
669 * since 3.1 it handles hex and octal notations.</p>
670 *
671 * <p>Returns <code>null</code> if the string is <code>null</code>.</p>
672 *
673 * @param str a <code>String</code> to convert, may be null
674 * @return converted <code>Long</code>
675 * @throws NumberFormatException if the value cannot be converted
676 */
677 public static Long createLong(String str) {
678 if (str == null) {
679 return null;
680 }
681 return Long.decode(str);
682 }
683
684 /**
685 * <p>Convert a <code>String</code> to a <code>BigInteger</code>.</p>
686 *
687 * <p>Returns <code>null</code> if the string is <code>null</code>.</p>
688 *
689 * @param str a <code>String</code> to convert, may be null
690 * @return converted <code>BigInteger</code>
691 * @throws NumberFormatException if the value cannot be converted
692 */
693 public static BigInteger createBigInteger(String str) {
694 if (str == null) {
695 return null;
696 }
697 return new BigInteger(str);
698 }
699
700 /**
701 * <p>Convert a <code>String</code> to a <code>BigDecimal</code>.</p>
702 *
703 * <p>Returns <code>null</code> if the string is <code>null</code>.</p>
704 *
705 * @param str a <code>String</code> to convert, may be null
706 * @return converted <code>BigDecimal</code>
707 * @throws NumberFormatException if the value cannot be converted
708 */
709 public static BigDecimal createBigDecimal(String str) {
710 if (str == null) {
711 return null;
712 }
713 // handle JDK1.3.1 bug where "" throws IndexOutOfBoundsException
714 if (StringUtils.isBlank(str)) {
715 throw new NumberFormatException("A blank string is not a valid number");
716 }
717 return new BigDecimal(str);
718 }
719
720 // Min in array
721 //--------------------------------------------------------------------
722 /**
723 * <p>Returns the minimum value in an array.</p>
724 *
725 * @param array an array, must not be null or empty
726 * @return the minimum value in the array
727 * @throws IllegalArgumentException if <code>array</code> is <code>null</code>
728 * @throws IllegalArgumentException if <code>array</code> is empty
729 */
730 public static long min(long[] array) {
731 // Validates input
732 if (array == null) {
733 throw new IllegalArgumentException("The Array must not be null");
734 } else if (array.length == 0) {
735 throw new IllegalArgumentException("Array cannot be empty.");
736 }
737
738 // Finds and returns min
739 long min = array[0];
740 for (int i = 1; i < array.length; i++) {
741 if (array[i] < min) {
742 min = array[i];
743 }
744 }
745
746 return min;
747 }
748
749 /**
750 * <p>Returns the minimum value in an array.</p>
751 *
752 * @param array an array, must not be null or empty
753 * @return the minimum value in the array
754 * @throws IllegalArgumentException if <code>array</code> is <code>null</code>
755 * @throws IllegalArgumentException if <code>array</code> is empty
756 */
757 public static int min(int[] array) {
758 // Validates input
759 if (array == null) {
760 throw new IllegalArgumentException("The Array must not be null");
761 } else if (array.length == 0) {
762 throw new IllegalArgumentException("Array cannot be empty.");
763 }
764
765 // Finds and returns min
766 int min = array[0];
767 for (int j = 1; j < array.length; j++) {
768 if (array[j] < min) {
769 min = array[j];
770 }
771 }
772
773 return min;
774 }
775
776 /**
777 * <p>Returns the minimum value in an array.</p>
778 *
779 * @param array an array, must not be null or empty
780 * @return the minimum value in the array
781 * @throws IllegalArgumentException if <code>array</code> is <code>null</code>
782 * @throws IllegalArgumentException if <code>array</code> is empty
783 */
784 public static short min(short[] array) {
785 // Validates input
786 if (array == null) {
787 throw new IllegalArgumentException("The Array must not be null");
788 } else if (array.length == 0) {
789 throw new IllegalArgumentException("Array cannot be empty.");
790 }
791
792 // Finds and returns min
793 short min = array[0];
794 for (int i = 1; i < array.length; i++) {
795 if (array[i] < min) {
796 min = array[i];
797 }
798 }
799
800 return min;
801 }
802
803 /**
804 * <p>Returns the minimum value in an array.</p>
805 *
806 * @param array an array, must not be null or empty
807 * @return the minimum value in the array
808 * @throws IllegalArgumentException if <code>array</code> is <code>null</code>
809 * @throws IllegalArgumentException if <code>array</code> is empty
810 */
811 public static byte min(byte[] array) {
812 // Validates input
813 if (array == null) {
814 throw new IllegalArgumentException("The Array must not be null");
815 } else if (array.length == 0) {
816 throw new IllegalArgumentException("Array cannot be empty.");
817 }
818
819 // Finds and returns min
820 byte min = array[0];
821 for (int i = 1; i < array.length; i++) {
822 if (array[i] < min) {
823 min = array[i];
824 }
825 }
826
827 return min;
828 }
829
830 /**
831 * <p>Returns the minimum value in an array.</p>
832 *
833 * @param array an array, must not be null or empty
834 * @return the minimum value in the array
835 * @throws IllegalArgumentException if <code>array</code> is <code>null</code>
836 * @throws IllegalArgumentException if <code>array</code> is empty
837 * @see IEEE754rUtils#min(double[]) IEEE754rUtils for a version of this method that handles NaN differently
838 */
839 public static double min(double[] array) {
840 // Validates input
841 if (array == null) {
842 throw new IllegalArgumentException("The Array must not be null");
843 } else if (array.length == 0) {
844 throw new IllegalArgumentException("Array cannot be empty.");
845 }
846
847 // Finds and returns min
848 double min = array[0];
849 for (int i = 1; i < array.length; i++) {
850 if (Double.isNaN(array[i])) {
851 return Double.NaN;
852 }
853 if (array[i] < min) {
854 min = array[i];
855 }
856 }
857
858 return min;
859 }
860
861 /**
862 * <p>Returns the minimum value in an array.</p>
863 *
864 * @param array an array, must not be null or empty
865 * @return the minimum value in the array
866 * @throws IllegalArgumentException if <code>array</code> is <code>null</code>
867 * @throws IllegalArgumentException if <code>array</code> is empty
868 * @see IEEE754rUtils#min(float[]) IEEE754rUtils for a version of this method that handles NaN differently
869 */
870 public static float min(float[] array) {
871 // Validates input
872 if (array == null) {
873 throw new IllegalArgumentException("The Array must not be null");
874 } else if (array.length == 0) {
875 throw new IllegalArgumentException("Array cannot be empty.");
876 }
877
878 // Finds and returns min
879 float min = array[0];
880 for (int i = 1; i < array.length; i++) {
881 if (Float.isNaN(array[i])) {
882 return Float.NaN;
883 }
884 if (array[i] < min) {
885 min = array[i];
886 }
887 }
888
889 return min;
890 }
891
892 // Max in array
893 //--------------------------------------------------------------------
894 /**
895 * <p>Returns the maximum value in an array.</p>
896 *
897 * @param array an array, must not be null or empty
898 * @return the minimum value in the array
899 * @throws IllegalArgumentException if <code>array</code> is <code>null</code>
900 * @throws IllegalArgumentException if <code>array</code> is empty
901 */
902 public static long max(long[] array) {
903 // Validates input
904 if (array == null) {
905 throw new IllegalArgumentException("The Array must not be null");
906 } else if (array.length == 0) {
907 throw new IllegalArgumentException("Array cannot be empty.");
908 }
909
910 // Finds and returns max
911 long max = array[0];
912 for (int j = 1; j < array.length; j++) {
913 if (array[j] > max) {
914 max = array[j];
915 }
916 }
917
918 return max;
919 }
920
921 /**
922 * <p>Returns the maximum value in an array.</p>
923 *
924 * @param array an array, must not be null or empty
925 * @return the minimum value in the array
926 * @throws IllegalArgumentException if <code>array</code> is <code>null</code>
927 * @throws IllegalArgumentException if <code>array</code> is empty
928 */
929 public static int max(int[] array) {
930 // Validates input
931 if (array == null) {
932 throw new IllegalArgumentException("The Array must not be null");
933 } else if (array.length == 0) {
934 throw new IllegalArgumentException("Array cannot be empty.");
935 }
936
937 // Finds and returns max
938 int max = array[0];
939 for (int j = 1; j < array.length; j++) {
940 if (array[j] > max) {
941 max = array[j];
942 }
943 }
944
945 return max;
946 }
947
948 /**
949 * <p>Returns the maximum value in an array.</p>
950 *
951 * @param array an array, must not be null or empty
952 * @return the minimum value in the array
953 * @throws IllegalArgumentException if <code>array</code> is <code>null</code>
954 * @throws IllegalArgumentException if <code>array</code> is empty
955 */
956 public static short max(short[] array) {
957 // Validates input
958 if (array == null) {
959 throw new IllegalArgumentException("The Array must not be null");
960 } else if (array.length == 0) {
961 throw new IllegalArgumentException("Array cannot be empty.");
962 }
963
964 // Finds and returns max
965 short max = array[0];
966 for (int i = 1; i < array.length; i++) {
967 if (array[i] > max) {
968 max = array[i];
969 }
970 }
971
972 return max;
973 }
974
975 /**
976 * <p>Returns the maximum value in an array.</p>
977 *
978 * @param array an array, must not be null or empty
979 * @return the minimum value in the array
980 * @throws IllegalArgumentException if <code>array</code> is <code>null</code>
981 * @throws IllegalArgumentException if <code>array</code> is empty
982 */
983 public static byte max(byte[] array) {
984 // Validates input
985 if (array == null) {
986 throw new IllegalArgumentException("The Array must not be null");
987 } else if (array.length == 0) {
988 throw new IllegalArgumentException("Array cannot be empty.");
989 }
990
991 // Finds and returns max
992 byte max = array[0];
993 for (int i = 1; i < array.length; i++) {
994 if (array[i] > max) {
995 max = array[i];
996 }
997 }
998
999 return max;
1000 }
1001
1002 /**
1003 * <p>Returns the maximum value in an array.</p>
1004 *
1005 * @param array an array, must not be null or empty
1006 * @return the minimum value in the array
1007 * @throws IllegalArgumentException if <code>array</code> is <code>null</code>
1008 * @throws IllegalArgumentException if <code>array</code> is empty
1009 * @see IEEE754rUtils#max(double[]) IEEE754rUtils for a version of this method that handles NaN differently
1010 */
1011 public static double max(double[] array) {
1012 // Validates input
1013 if (array== null) {
1014 throw new IllegalArgumentException("The Array must not be null");
1015 } else if (array.length == 0) {
1016 throw new IllegalArgumentException("Array cannot be empty.");
1017 }
1018
1019 // Finds and returns max
1020 double max = array[0];
1021 for (int j = 1; j < array.length; j++) {
1022 if (Double.isNaN(array[j])) {
1023 return Double.NaN;
1024 }
1025 if (array[j] > max) {
1026 max = array[j];
1027 }
1028 }
1029
1030 return max;
1031 }
1032
1033 /**
1034 * <p>Returns the maximum 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</code> is <code>null</code>
1039 * @throws IllegalArgumentException if <code>array</code> is empty
1040 * @see IEEE754rUtils#max(float[]) IEEE754rUtils for a version of this method that handles NaN differently
1041 */
1042 public static float max(float[] array) {
1043 // Validates input
1044 if (array == null) {
1045 throw new IllegalArgumentException("The Array must not be null");
1046 } else if (array.length == 0) {
1047 throw new IllegalArgumentException("Array cannot be empty.");
1048 }
1049
1050 // Finds and returns max
1051 float max = array[0];
1052 for (int j = 1; j < array.length; j++) {
1053 if (Float.isNaN(array[j])) {
1054 return Float.NaN;
1055 }
1056 if (array[j] > max) {
1057 max = array[j];
1058 }
1059 }
1060
1061 return max;
1062 }
1063
1064 // 3 param min
1065 //-----------------------------------------------------------------------
1066 /**
1067 * <p>Gets the minimum of three <code>long</code> values.</p>
1068 *
1069 * @param a value 1
1070 * @param b value 2
1071 * @param c value 3
1072 * @return the smallest of the values
1073 */
1074 public static long min(long a, long b, long c) {
1075 if (b < a) {
1076 a = b;
1077 }
1078 if (c < a) {
1079 a = c;
1080 }
1081 return a;
1082 }
1083
1084 /**
1085 * <p>Gets the minimum of three <code>int</code> values.</p>
1086 *
1087 * @param a value 1
1088 * @param b value 2
1089 * @param c value 3
1090 * @return the smallest of the values
1091 */
1092 public static int min(int a, int b, int c) {
1093 if (b < a) {
1094 a = b;
1095 }
1096 if (c < a) {
1097 a = c;
1098 }
1099 return a;
1100 }
1101
1102 /**
1103 * <p>Gets the minimum of three <code>short</code> values.</p>
1104 *
1105 * @param a value 1
1106 * @param b value 2
1107 * @param c value 3
1108 * @return the smallest of the values
1109 */
1110 public static short min(short a, short b, short c) {
1111 if (b < a) {
1112 a = b;
1113 }
1114 if (c < a) {
1115 a = c;
1116 }
1117 return a;
1118 }
1119
1120 /**
1121 * <p>Gets the minimum of three <code>byte</code> values.</p>
1122 *
1123 * @param a value 1
1124 * @param b value 2
1125 * @param c value 3
1126 * @return the smallest of the values
1127 */
1128 public static byte min(byte a, byte b, byte c) {
1129 if (b < a) {
1130 a = b;
1131 }
1132 if (c < a) {
1133 a = c;
1134 }
1135 return a;
1136 }
1137
1138 /**
1139 * <p>Gets the minimum of three <code>double</code> values.</p>
1140 *
1141 * <p>If any value is <code>NaN</code>, <code>NaN</code> is
1142 * returned. Infinity is handled.</p>
1143 *
1144 * @param a value 1
1145 * @param b value 2
1146 * @param c value 3
1147 * @return the smallest of the values
1148 * @see IEEE754rUtils#min(double, double, double) for a version of this method that handles NaN differently
1149 */
1150 public static double min(double a, double b, double c) {
1151 return Math.min(Math.min(a, b), c);
1152 }
1153
1154 /**
1155 * <p>Gets the minimum of three <code>float</code> values.</p>
1156 *
1157 * <p>If any value is <code>NaN</code>, <code>NaN</code> is
1158 * returned. Infinity is handled.</p>
1159 *
1160 * @param a value 1
1161 * @param b value 2
1162 * @param c value 3
1163 * @return the smallest of the values
1164 * @see IEEE754rUtils#min(float, float, float) for a version of this method that handles NaN differently
1165 */
1166 public static float min(float a, float b, float c) {
1167 return Math.min(Math.min(a, b), c);
1168 }
1169
1170 // 3 param max
1171 //-----------------------------------------------------------------------
1172 /**
1173 * <p>Gets the maximum of three <code>long</code> values.</p>
1174 *
1175 * @param a value 1
1176 * @param b value 2
1177 * @param c value 3
1178 * @return the largest of the values
1179 */
1180 public static long max(long a, long b, long c) {
1181 if (b > a) {
1182 a = b;
1183 }
1184 if (c > a) {
1185 a = c;
1186 }
1187 return a;
1188 }
1189
1190 /**
1191 * <p>Gets the maximum of three <code>int</code> values.</p>
1192 *
1193 * @param a value 1
1194 * @param b value 2
1195 * @param c value 3
1196 * @return the largest of the values
1197 */
1198 public static int max(int a, int b, int c) {
1199 if (b > a) {
1200 a = b;
1201 }
1202 if (c > a) {
1203 a = c;
1204 }
1205 return a;
1206 }
1207
1208 /**
1209 * <p>Gets the maximum of three <code>short</code> values.</p>
1210 *
1211 * @param a value 1
1212 * @param b value 2
1213 * @param c value 3
1214 * @return the largest of the values
1215 */
1216 public static short max(short a, short b, short c) {
1217 if (b > a) {
1218 a = b;
1219 }
1220 if (c > a) {
1221 a = c;
1222 }
1223 return a;
1224 }
1225
1226 /**
1227 * <p>Gets the maximum of three <code>byte</code> values.</p>
1228 *
1229 * @param a value 1
1230 * @param b value 2
1231 * @param c value 3
1232 * @return the largest of the values
1233 */
1234 public static byte max(byte a, byte b, byte c) {
1235 if (b > a) {
1236 a = b;
1237 }
1238 if (c > a) {
1239 a = c;
1240 }
1241 return a;
1242 }
1243
1244 /**
1245 * <p>Gets the maximum of three <code>double</code> values.</p>
1246 *
1247 * <p>If any value is <code>NaN</code>, <code>NaN</code> is
1248 * returned. Infinity is handled.</p>
1249 *
1250 * @param a value 1
1251 * @param b value 2
1252 * @param c value 3
1253 * @return the largest of the values
1254 * @see IEEE754rUtils#max(double, double, double) for a version of this method that handles NaN differently
1255 */
1256 public static double max(double a, double b, double c) {
1257 return Math.max(Math.max(a, b), c);
1258 }
1259
1260 /**
1261 * <p>Gets the maximum of three <code>float</code> values.</p>
1262 *
1263 * <p>If any value is <code>NaN</code>, <code>NaN</code> is
1264 * returned. Infinity is handled.</p>
1265 *
1266 * @param a value 1
1267 * @param b value 2
1268 * @param c value 3
1269 * @return the largest of the values
1270 * @see IEEE754rUtils#max(float, float, float) for a version of this method that handles NaN differently
1271 */
1272 public static float max(float a, float b, float c) {
1273 return Math.max(Math.max(a, b), c);
1274 }
1275
1276 //-----------------------------------------------------------------------
1277 /**
1278 * <p>Checks whether the <code>String</code> contains only
1279 * digit characters.</p>
1280 *
1281 * <p><code>Null</code> and empty String will return
1282 * <code>false</code>.</p>
1283 *
1284 * @param str the <code>String</code> to check
1285 * @return <code>true</code> if str contains only Unicode numeric
1286 */
1287 public static boolean isDigits(String str) {
1288 if (StringUtils.isEmpty(str)) {
1289 return false;
1290 }
1291 for (int i = 0; i < str.length(); i++) {
1292 if (!Character.isDigit(str.charAt(i))) {
1293 return false;
1294 }
1295 }
1296 return true;
1297 }
1298
1299 /**
1300 * <p>Checks whether the String a valid Java number.</p>
1301 *
1302 * <p>Valid numbers include hexadecimal marked with the <code>0x</code>
1303 * qualifier, scientific notation and numbers marked with a type
1304 * qualifier (e.g. 123L).</p>
1305 *
1306 * <p><code>Null</code> and empty String will return
1307 * <code>false</code>.</p>
1308 *
1309 * @param str the <code>String</code> to check
1310 * @return <code>true</code> if the string is a correctly formatted number
1311 */
1312 public static boolean isNumber(String str) {
1313 if (StringUtils.isEmpty(str)) {
1314 return false;
1315 }
1316 char[] chars = str.toCharArray();
1317 int sz = chars.length;
1318 boolean hasExp = false;
1319 boolean hasDecPoint = false;
1320 boolean allowSigns = false;
1321 boolean foundDigit = false;
1322 // deal with any possible sign up front
1323 int start = (chars[0] == '-') ? 1 : 0;
1324 if (sz > start + 1 && 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 sz--; // don't want to loop to the last char, check it afterwords
1340 // for type qualifiers
1341 int i = start;
1342 // loop to the next to last char or to the last char if we need another digit to
1343 // make a valid number (e.g. chars[0..5] = "1234E")
1344 while (i < sz || (i < sz + 1 && allowSigns && !foundDigit)) {
1345 if (chars[i] >= '0' && chars[i] <= '9') {
1346 foundDigit = true;
1347 allowSigns = false;
1348
1349 } else if (chars[i] == '.') {
1350 if (hasDecPoint || hasExp) {
1351 // two decimal points or dec in exponent
1352 return false;
1353 }
1354 hasDecPoint = true;
1355 } else if (chars[i] == 'e' || chars[i] == 'E') {
1356 // we've already taken care of hex.
1357 if (hasExp) {
1358 // two E's
1359 return false;
1360 }
1361 if (!foundDigit) {
1362 return false;
1363 }
1364 hasExp = true;
1365 allowSigns = true;
1366 } else if (chars[i] == '+' || chars[i] == '-') {
1367 if (!allowSigns) {
1368 return false;
1369 }
1370 allowSigns = false;
1371 foundDigit = false; // we need a digit after the E
1372 } else {
1373 return false;
1374 }
1375 i++;
1376 }
1377 if (i < chars.length) {
1378 if (chars[i] >= '0' && chars[i] <= '9') {
1379 // no type qualifier, OK
1380 return true;
1381 }
1382 if (chars[i] == 'e' || chars[i] == 'E') {
1383 // can't have an E at the last byte
1384 return false;
1385 }
1386 if (chars[i] == '.') {
1387 if (hasDecPoint || hasExp) {
1388 // two decimal points or dec in exponent
1389 return false;
1390 }
1391 // single trailing decimal point after non-exponent is ok
1392 return foundDigit;
1393 }
1394 if (!allowSigns
1395 && (chars[i] == 'd'
1396 || chars[i] == 'D'
1397 || chars[i] == 'f'
1398 || chars[i] == 'F')) {
1399 return foundDigit;
1400 }
1401 if (chars[i] == 'l'
1402 || chars[i] == 'L') {
1403 // not allowing L with an exponent or decimal point
1404 return foundDigit && !hasExp && !hasDecPoint;
1405 }
1406 // last character is illegal
1407 return false;
1408 }
1409 // allowSigns is true iff the val ends in 'E'
1410 // found digit it to make sure weird stuff like '.' and '1E-' doesn't pass
1411 return !allowSigns && foundDigit;
1412 }
1413
1414 }