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.lang;
018
019 import org.apache.commons.lang.math.NumberUtils;
020
021 /**
022 * <p>Operations on boolean primitives and Boolean objects.</p>
023 *
024 * <p>This class tries to handle <code>null</code> input gracefully.
025 * An exception will not be thrown for a <code>null</code> input.
026 * Each method documents its behaviour in more detail.</p>
027 *
028 * <p>#ThreadSafe#</p>
029 * @author Apache Software Foundation
030 * @author Matthew Hawthorne
031 * @author Gary Gregory
032 * @since 2.0
033 * @version $Id: BooleanUtils.java 1057037 2011-01-09 21:35:32Z niallp $
034 */
035 public class BooleanUtils {
036
037 /**
038 * <p><code>BooleanUtils</code> instances should NOT be constructed in standard programming.
039 * Instead, the class should be used as <code>BooleanUtils.toBooleanObject(true);</code>.</p>
040 *
041 * <p>This constructor is public to permit tools that require a JavaBean instance
042 * to operate.</p>
043 */
044 public BooleanUtils() {
045 super();
046 }
047
048 // Boolean utilities
049 //--------------------------------------------------------------------------
050 /**
051 * <p>Negates the specified boolean.</p>
052 *
053 * <p>If <code>null</code> is passed in, <code>null</code> will be returned.</p>
054 *
055 * <pre>
056 * BooleanUtils.negate(Boolean.TRUE) = Boolean.FALSE;
057 * BooleanUtils.negate(Boolean.FALSE) = Boolean.TRUE;
058 * BooleanUtils.negate(null) = null;
059 * </pre>
060 *
061 * @param bool the Boolean to negate, may be null
062 * @return the negated Boolean, or <code>null</code> if <code>null</code> input
063 */
064 public static Boolean negate(Boolean bool) {
065 if (bool == null) {
066 return null;
067 }
068 return (bool.booleanValue() ? Boolean.FALSE : Boolean.TRUE);
069 }
070
071 // boolean Boolean methods
072 //-----------------------------------------------------------------------
073 /**
074 * <p>Checks if a <code>Boolean</code> value is <code>true</code>,
075 * handling <code>null</code> by returning <code>false</code>.</p>
076 *
077 * <pre>
078 * BooleanUtils.isTrue(Boolean.TRUE) = true
079 * BooleanUtils.isTrue(Boolean.FALSE) = false
080 * BooleanUtils.isTrue(null) = false
081 * </pre>
082 *
083 * @param bool the boolean to check, null returns <code>false</code>
084 * @return <code>true</code> only if the input is non-null and true
085 * @since 2.1
086 */
087 public static boolean isTrue(Boolean bool) {
088 if (bool == null) {
089 return false;
090 }
091 return bool.booleanValue() ? true : false;
092 }
093
094 /**
095 * <p>Checks if a <code>Boolean</code> value is <i>not</i> <code>true</code>,
096 * handling <code>null</code> by returning <code>true</code>.</p>
097 *
098 * <pre>
099 * BooleanUtils.isNotTrue(Boolean.TRUE) = false
100 * BooleanUtils.isNotTrue(Boolean.FALSE) = true
101 * BooleanUtils.isNotTrue(null) = true
102 * </pre>
103 *
104 * @param bool the boolean to check, null returns <code>true</code>
105 * @return <code>true</code> if the input is null or false
106 * @since 2.3
107 */
108 public static boolean isNotTrue(Boolean bool) {
109 return !isTrue(bool);
110 }
111
112 /**
113 * <p>Checks if a <code>Boolean</code> value is <code>false</code>,
114 * handling <code>null</code> by returning <code>false</code>.</p>
115 *
116 * <pre>
117 * BooleanUtils.isFalse(Boolean.TRUE) = false
118 * BooleanUtils.isFalse(Boolean.FALSE) = true
119 * BooleanUtils.isFalse(null) = false
120 * </pre>
121 *
122 * @param bool the boolean to check, null returns <code>false</code>
123 * @return <code>true</code> only if the input is non-null and false
124 * @since 2.1
125 */
126 public static boolean isFalse(Boolean bool) {
127 if (bool == null) {
128 return false;
129 }
130 return bool.booleanValue() ? false : true;
131 }
132
133 /**
134 * <p>Checks if a <code>Boolean</code> value is <i>not</i> <code>false</code>,
135 * handling <code>null</code> by returning <code>true</code>.</p>
136 *
137 * <pre>
138 * BooleanUtils.isNotFalse(Boolean.TRUE) = true
139 * BooleanUtils.isNotFalse(Boolean.FALSE) = false
140 * BooleanUtils.isNotFalse(null) = true
141 * </pre>
142 *
143 * @param bool the boolean to check, null returns <code>true</code>
144 * @return <code>true</code> if the input is null or true
145 * @since 2.3
146 */
147 public static boolean isNotFalse(Boolean bool) {
148 return !isFalse(bool);
149 }
150
151 //-----------------------------------------------------------------------
152 /**
153 * <p>Boolean factory that avoids creating new Boolean objecs all the time.</p>
154 *
155 * <p>This method was added to JDK1.4 but is available here for earlier JDKs.</p>
156 *
157 * <pre>
158 * BooleanUtils.toBooleanObject(false) = Boolean.FALSE
159 * BooleanUtils.toBooleanObject(true) = Boolean.TRUE
160 * </pre>
161 *
162 * @param bool the boolean to convert
163 * @return Boolean.TRUE or Boolean.FALSE as appropriate
164 */
165 public static Boolean toBooleanObject(boolean bool) {
166 return bool ? Boolean.TRUE : Boolean.FALSE;
167 }
168
169 /**
170 * <p>Converts a Boolean to a boolean handling <code>null</code>
171 * by returning <code>false</code>.</p>
172 *
173 * <pre>
174 * BooleanUtils.toBoolean(Boolean.TRUE) = true
175 * BooleanUtils.toBoolean(Boolean.FALSE) = false
176 * BooleanUtils.toBoolean(null) = false
177 * </pre>
178 *
179 * @param bool the boolean to convert
180 * @return <code>true</code> or <code>false</code>,
181 * <code>null</code> returns <code>false</code>
182 */
183 public static boolean toBoolean(Boolean bool) {
184 if (bool == null) {
185 return false;
186 }
187 return bool.booleanValue() ? true : false;
188 }
189
190 /**
191 * <p>Converts a Boolean to a boolean handling <code>null</code>.</p>
192 *
193 * <pre>
194 * BooleanUtils.toBooleanDefaultIfNull(Boolean.TRUE, false) = true
195 * BooleanUtils.toBooleanDefaultIfNull(Boolean.FALSE, true) = false
196 * BooleanUtils.toBooleanDefaultIfNull(null, true) = true
197 * </pre>
198 *
199 * @param bool the boolean to convert
200 * @param valueIfNull the boolean value to return if <code>null</code>
201 * @return <code>true</code> or <code>false</code>
202 */
203 public static boolean toBooleanDefaultIfNull(Boolean bool, boolean valueIfNull) {
204 if (bool == null) {
205 return valueIfNull;
206 }
207 return bool.booleanValue() ? true : false;
208 }
209
210 // Integer to Boolean methods
211 //-----------------------------------------------------------------------
212 /**
213 * <p>Converts an int to a boolean using the convention that <code>zero</code>
214 * is <code>false</code>.</p>
215 *
216 * <pre>
217 * BooleanUtils.toBoolean(0) = false
218 * BooleanUtils.toBoolean(1) = true
219 * BooleanUtils.toBoolean(2) = true
220 * </pre>
221 *
222 * @param value the int to convert
223 * @return <code>true</code> if non-zero, <code>false</code>
224 * if zero
225 */
226 public static boolean toBoolean(int value) {
227 return value == 0 ? false : true;
228 }
229
230 /**
231 * <p>Converts an int to a Boolean using the convention that <code>zero</code>
232 * is <code>false</code>.</p>
233 *
234 * <pre>
235 * BooleanUtils.toBoolean(0) = Boolean.FALSE
236 * BooleanUtils.toBoolean(1) = Boolean.TRUE
237 * BooleanUtils.toBoolean(2) = Boolean.TRUE
238 * </pre>
239 *
240 * @param value the int to convert
241 * @return Boolean.TRUE if non-zero, Boolean.FALSE if zero,
242 * <code>null</code> if <code>null</code>
243 */
244 public static Boolean toBooleanObject(int value) {
245 return value == 0 ? Boolean.FALSE : Boolean.TRUE;
246 }
247
248 /**
249 * <p>Converts an Integer to a Boolean using the convention that <code>zero</code>
250 * is <code>false</code>.</p>
251 *
252 * <p><code>null</code> will be converted to <code>null</code>.</p>
253 *
254 * <pre>
255 * BooleanUtils.toBoolean(new Integer(0)) = Boolean.FALSE
256 * BooleanUtils.toBoolean(new Integer(1)) = Boolean.TRUE
257 * BooleanUtils.toBoolean(new Integer(null)) = null
258 * </pre>
259 *
260 * @param value the Integer to convert
261 * @return Boolean.TRUE if non-zero, Boolean.FALSE if zero,
262 * <code>null</code> if <code>null</code> input
263 */
264 public static Boolean toBooleanObject(Integer value) {
265 if (value == null) {
266 return null;
267 }
268 return value.intValue() == 0 ? Boolean.FALSE : Boolean.TRUE;
269 }
270
271 /**
272 * <p>Converts an int to a boolean specifying the conversion values.</p>
273 *
274 * <pre>
275 * BooleanUtils.toBoolean(0, 1, 0) = false
276 * BooleanUtils.toBoolean(1, 1, 0) = true
277 * BooleanUtils.toBoolean(2, 1, 2) = false
278 * BooleanUtils.toBoolean(2, 2, 0) = true
279 * </pre>
280 *
281 * @param value the Integer to convert
282 * @param trueValue the value to match for <code>true</code>
283 * @param falseValue the value to match for <code>false</code>
284 * @return <code>true</code> or <code>false</code>
285 * @throws IllegalArgumentException if no match
286 */
287 public static boolean toBoolean(int value, int trueValue, int falseValue) {
288 if (value == trueValue) {
289 return true;
290 } else if (value == falseValue) {
291 return false;
292 }
293 // no match
294 throw new IllegalArgumentException("The Integer did not match either specified value");
295 }
296
297 /**
298 * <p>Converts an Integer to a boolean specifying the conversion values.</p>
299 *
300 * <pre>
301 * BooleanUtils.toBoolean(new Integer(0), new Integer(1), new Integer(0)) = false
302 * BooleanUtils.toBoolean(new Integer(1), new Integer(1), new Integer(0)) = true
303 * BooleanUtils.toBoolean(new Integer(2), new Integer(1), new Integer(2)) = false
304 * BooleanUtils.toBoolean(new Integer(2), new Integer(2), new Integer(0)) = true
305 * BooleanUtils.toBoolean(null, null, new Integer(0)) = true
306 * </pre>
307 *
308 * @param value the Integer to convert
309 * @param trueValue the value to match for <code>true</code>,
310 * may be <code>null</code>
311 * @param falseValue the value to match for <code>false</code>,
312 * may be <code>null</code>
313 * @return <code>true</code> or <code>false</code>
314 * @throws IllegalArgumentException if no match
315 */
316 public static boolean toBoolean(Integer value, Integer trueValue, Integer falseValue) {
317 if (value == null) {
318 if (trueValue == null) {
319 return true;
320 } else if (falseValue == null) {
321 return false;
322 }
323 } else if (value.equals(trueValue)) {
324 return true;
325 } else if (value.equals(falseValue)) {
326 return false;
327 }
328 // no match
329 throw new IllegalArgumentException("The Integer did not match either specified value");
330 }
331
332 /**
333 * <p>Converts an int to a Boolean specifying the conversion values.</p>
334 *
335 * <pre>
336 * BooleanUtils.toBooleanObject(0, 0, 2, 3) = Boolean.TRUE
337 * BooleanUtils.toBooleanObject(2, 1, 2, 3) = Boolean.FALSE
338 * BooleanUtils.toBooleanObject(3, 1, 2, 3) = null
339 * </pre>
340 *
341 * @param value the Integer to convert
342 * @param trueValue the value to match for <code>true</code>
343 * @param falseValue the value to match for <code>false</code>
344 * @param nullValue the value to to match for <code>null</code>
345 * @return Boolean.TRUE, Boolean.FALSE, or <code>null</code>
346 * @throws IllegalArgumentException if no match
347 */
348 public static Boolean toBooleanObject(int value, int trueValue, int falseValue, int nullValue) {
349 if (value == trueValue) {
350 return Boolean.TRUE;
351 } else if (value == falseValue) {
352 return Boolean.FALSE;
353 } else if (value == nullValue) {
354 return null;
355 }
356 // no match
357 throw new IllegalArgumentException("The Integer did not match any specified value");
358 }
359
360 /**
361 * <p>Converts an Integer to a Boolean specifying the conversion values.</p>
362 *
363 * <pre>
364 * BooleanUtils.toBooleanObject(new Integer(0), new Integer(0), new Integer(2), new Integer(3)) = Boolean.TRUE
365 * BooleanUtils.toBooleanObject(new Integer(2), new Integer(1), new Integer(2), new Integer(3)) = Boolean.FALSE
366 * BooleanUtils.toBooleanObject(new Integer(3), new Integer(1), new Integer(2), new Integer(3)) = null
367 * </pre>
368 *
369 * @param value the Integer to convert
370 * @param trueValue the value to match for <code>true</code>,
371 * may be <code>null</code>
372 * @param falseValue the value to match for <code>false</code>,
373 * may be <code>null</code>
374 * @param nullValue the value to to match for <code>null</code>,
375 * may be <code>null</code>
376 * @return Boolean.TRUE, Boolean.FALSE, or <code>null</code>
377 * @throws IllegalArgumentException if no match
378 */
379 public static Boolean toBooleanObject(Integer value, Integer trueValue, Integer falseValue, Integer nullValue) {
380 if (value == null) {
381 if (trueValue == null) {
382 return Boolean.TRUE;
383 } else if (falseValue == null) {
384 return Boolean.FALSE;
385 } else if (nullValue == null) {
386 return null;
387 }
388 } else if (value.equals(trueValue)) {
389 return Boolean.TRUE;
390 } else if (value.equals(falseValue)) {
391 return Boolean.FALSE;
392 } else if (value.equals(nullValue)) {
393 return null;
394 }
395 // no match
396 throw new IllegalArgumentException("The Integer did not match any specified value");
397 }
398
399 // Boolean to Integer methods
400 //-----------------------------------------------------------------------
401 /**
402 * <p>Converts a boolean to an int using the convention that
403 * <code>zero</code> is <code>false</code>.</p>
404 *
405 * <pre>
406 * BooleanUtils.toInteger(true) = 1
407 * BooleanUtils.toInteger(false) = 0
408 * </pre>
409 *
410 * @param bool the boolean to convert
411 * @return one if <code>true</code>, zero if <code>false</code>
412 */
413 public static int toInteger(boolean bool) {
414 return bool ? 1 : 0;
415 }
416
417 /**
418 * <p>Converts a boolean to an Integer using the convention that
419 * <code>zero</code> is <code>false</code>.</p>
420 *
421 * <pre>
422 * BooleanUtils.toIntegerObject(true) = new Integer(1)
423 * BooleanUtils.toIntegerObject(false) = new Integer(0)
424 * </pre>
425 *
426 * @param bool the boolean to convert
427 * @return one if <code>true</code>, zero if <code>false</code>
428 */
429 public static Integer toIntegerObject(boolean bool) {
430 return bool ? NumberUtils.INTEGER_ONE : NumberUtils.INTEGER_ZERO;
431 }
432
433 /**
434 * <p>Converts a Boolean to a Integer using the convention that
435 * <code>zero</code> is <code>false</code>.</p>
436 *
437 * <p><code>null</code> will be converted to <code>null</code>.</p>
438 *
439 * <pre>
440 * BooleanUtils.toIntegerObject(Boolean.TRUE) = new Integer(1)
441 * BooleanUtils.toIntegerObject(Boolean.FALSE) = new Integer(0)
442 * </pre>
443 *
444 * @param bool the Boolean to convert
445 * @return one if Boolean.TRUE, zero if Boolean.FALSE, <code>null</code> if <code>null</code>
446 */
447 public static Integer toIntegerObject(Boolean bool) {
448 if (bool == null) {
449 return null;
450 }
451 return bool.booleanValue() ? NumberUtils.INTEGER_ONE : NumberUtils.INTEGER_ZERO;
452 }
453
454 /**
455 * <p>Converts a boolean to an int specifying the conversion values.</p>
456 *
457 * <pre>
458 * BooleanUtils.toInteger(true, 1, 0) = 1
459 * BooleanUtils.toInteger(false, 1, 0) = 0
460 * </pre>
461 *
462 * @param bool the to convert
463 * @param trueValue the value to return if <code>true</code>
464 * @param falseValue the value to return if <code>false</code>
465 * @return the appropriate value
466 */
467 public static int toInteger(boolean bool, int trueValue, int falseValue) {
468 return bool ? trueValue : falseValue;
469 }
470
471 /**
472 * <p>Converts a Boolean to an int specifying the conversion values.</p>
473 *
474 * <pre>
475 * BooleanUtils.toInteger(Boolean.TRUE, 1, 0, 2) = 1
476 * BooleanUtils.toInteger(Boolean.FALSE, 1, 0, 2) = 0
477 * BooleanUtils.toInteger(null, 1, 0, 2) = 2
478 * </pre>
479 *
480 * @param bool the Boolean to convert
481 * @param trueValue the value to return if <code>true</code>
482 * @param falseValue the value to return if <code>false</code>
483 * @param nullValue the value to return if <code>null</code>
484 * @return the appropriate value
485 */
486 public static int toInteger(Boolean bool, int trueValue, int falseValue, int nullValue) {
487 if (bool == null) {
488 return nullValue;
489 }
490 return bool.booleanValue() ? trueValue : falseValue;
491 }
492
493 /**
494 * <p>Converts a boolean to an Integer specifying the conversion values.</p>
495 *
496 * <pre>
497 * BooleanUtils.toIntegerObject(true, new Integer(1), new Integer(0)) = new Integer(1)
498 * BooleanUtils.toIntegerObject(false, new Integer(1), new Integer(0)) = new Integer(0)
499 * </pre>
500 *
501 * @param bool the to convert
502 * @param trueValue the value to return if <code>true</code>,
503 * may be <code>null</code>
504 * @param falseValue the value to return if <code>false</code>,
505 * may be <code>null</code>
506 * @return the appropriate value
507 */
508 public static Integer toIntegerObject(boolean bool, Integer trueValue, Integer falseValue) {
509 return bool ? trueValue : falseValue;
510 }
511
512 /**
513 * <p>Converts a Boolean to an Integer specifying the conversion values.</p>
514 *
515 * <pre>
516 * BooleanUtils.toIntegerObject(Boolean.TRUE, new Integer(1), new Integer(0), new Integer(2)) = new Integer(1)
517 * BooleanUtils.toIntegerObject(Boolean.FALSE, new Integer(1), new Integer(0), new Integer(2)) = new Integer(0)
518 * BooleanUtils.toIntegerObject(null, new Integer(1), new Integer(0), new Integer(2)) = new Integer(2)
519 * </pre>
520 *
521 * @param bool the Boolean to convert
522 * @param trueValue the value to return if <code>true</code>,
523 * may be <code>null</code>
524 * @param falseValue the value to return if <code>false</code>,
525 * may be <code>null</code>
526 * @param nullValue the value to return if <code>null</code>,
527 * may be <code>null</code>
528 * @return the appropriate value
529 */
530 public static Integer toIntegerObject(Boolean bool, Integer trueValue, Integer falseValue, Integer nullValue) {
531 if (bool == null) {
532 return nullValue;
533 }
534 return bool.booleanValue() ? trueValue : falseValue;
535 }
536
537 // String to Boolean methods
538 //-----------------------------------------------------------------------
539 /**
540 * <p>Converts a String to a Boolean.</p>
541 *
542 * <p><code>'true'</code>, <code>'on'</code> or <code>'yes'</code>
543 * (case insensitive) will return <code>true</code>.
544 * <code>'false'</code>, <code>'off'</code> or <code>'no'</code>
545 * (case insensitive) will return <code>false</code>.
546 * Otherwise, <code>null</code> is returned.</p>
547 *
548 * <pre>
549 * BooleanUtils.toBooleanObject(null) = null
550 * BooleanUtils.toBooleanObject("true") = Boolean.TRUE
551 * BooleanUtils.toBooleanObject("false") = Boolean.FALSE
552 * BooleanUtils.toBooleanObject("on") = Boolean.TRUE
553 * BooleanUtils.toBooleanObject("ON") = Boolean.TRUE
554 * BooleanUtils.toBooleanObject("off") = Boolean.FALSE
555 * BooleanUtils.toBooleanObject("oFf") = Boolean.FALSE
556 * BooleanUtils.toBooleanObject("blue") = null
557 * </pre>
558 *
559 * @param str the String to check
560 * @return the Boolean value of the string,
561 * <code>null</code> if no match or <code>null</code> input
562 */
563 public static Boolean toBooleanObject(String str) {
564 // Previously used equalsIgnoreCase, which was fast for interned 'true'.
565 // Non interned 'true' matched 15 times slower.
566 //
567 // Optimisation provides same performance as before for interned 'true'.
568 // Similar performance for null, 'false', and other strings not length 2/3/4.
569 // 'true'/'TRUE' match 4 times slower, 'tRUE'/'True' 7 times slower.
570 if (str == "true") {
571 return Boolean.TRUE;
572 }
573 if (str == null) {
574 return null;
575 }
576 switch (str.length()) {
577 case 1: {
578 char ch0 = str.charAt(0);
579 if ((ch0 == 'y' || ch0 == 'Y') ||
580 (ch0 == 't' || ch0 == 'T'))
581 {
582 return Boolean.TRUE;
583 }
584 if ((ch0 == 'n' || ch0 == 'N') ||
585 (ch0 == 'f' || ch0 == 'F'))
586 {
587 return Boolean.FALSE;
588 }
589 break;
590 }
591 case 2: {
592 char ch0 = str.charAt(0);
593 char ch1 = str.charAt(1);
594 if ((ch0 == 'o' || ch0 == 'O') &&
595 (ch1 == 'n' || ch1 == 'N') )
596 {
597 return Boolean.TRUE;
598 }
599 if ((ch0 == 'n' || ch0 == 'N') &&
600 (ch1 == 'o' || ch1 == 'O') )
601 {
602 return Boolean.FALSE;
603 }
604 break;
605 }
606 case 3: {
607 char ch0 = str.charAt(0);
608 char ch1 = str.charAt(1);
609 char ch2 = str.charAt(2);
610 if ((ch0 == 'y' || ch0 == 'Y') &&
611 (ch1 == 'e' || ch1 == 'E') &&
612 (ch2 == 's' || ch2 == 'S') )
613 {
614 return Boolean.TRUE;
615 }
616 if ((ch0 == 'o' || ch0 == 'O') &&
617 (ch1 == 'f' || ch1 == 'F') &&
618 (ch2 == 'f' || ch2 == 'F') )
619 {
620 return Boolean.FALSE;
621 }
622 break;
623 }
624 case 4: {
625 char ch0 = str.charAt(0);
626 char ch1 = str.charAt(1);
627 char ch2 = str.charAt(2);
628 char ch3 = str.charAt(3);
629 if ((ch0 == 't' || ch0 == 'T') &&
630 (ch1 == 'r' || ch1 == 'R') &&
631 (ch2 == 'u' || ch2 == 'U') &&
632 (ch3 == 'e' || ch3 == 'E') )
633 {
634 return Boolean.TRUE;
635 }
636 break;
637 }
638 case 5: {
639 char ch0 = str.charAt(0);
640 char ch1 = str.charAt(1);
641 char ch2 = str.charAt(2);
642 char ch3 = str.charAt(3);
643 char ch4 = str.charAt(4);
644 if ((ch0 == 'f' || ch0 == 'F') &&
645 (ch1 == 'a' || ch1 == 'A') &&
646 (ch2 == 'l' || ch2 == 'L') &&
647 (ch3 == 's' || ch3 == 'S') &&
648 (ch4 == 'e' || ch4 == 'E') )
649 {
650 return Boolean.FALSE;
651 }
652 break;
653 }
654 }
655
656 return null;
657 }
658
659 /**
660 * <p>Converts a String to a Boolean throwing an exception if no match.</p>
661 *
662 * <pre>
663 * BooleanUtils.toBooleanObject("true", "true", "false", "null") = Boolean.TRUE
664 * BooleanUtils.toBooleanObject("false", "true", "false", "null") = Boolean.FALSE
665 * BooleanUtils.toBooleanObject("null", "true", "false", "null") = null
666 * </pre>
667 *
668 * @param str the String to check
669 * @param trueString the String to match for <code>true</code>
670 * (case sensitive), may be <code>null</code>
671 * @param falseString the String to match for <code>false</code>
672 * (case sensitive), may be <code>null</code>
673 * @param nullString the String to match for <code>null</code>
674 * (case sensitive), may be <code>null</code>
675 * @return the Boolean value of the string,
676 * <code>null</code> if either the String matches <code>nullString</code>
677 * or if <code>null</code> input and <code>nullString</code> is
678 * <code>null</code>
679 * @throws IllegalArgumentException if the String doesn't match
680 */
681 public static Boolean toBooleanObject(String str, String trueString, String falseString, String nullString) {
682 if (str == null) {
683 if (trueString == null) {
684 return Boolean.TRUE;
685 } else if (falseString == null) {
686 return Boolean.FALSE;
687 } else if (nullString == null) {
688 return null;
689 }
690 } else if (str.equals(trueString)) {
691 return Boolean.TRUE;
692 } else if (str.equals(falseString)) {
693 return Boolean.FALSE;
694 } else if (str.equals(nullString)) {
695 return null;
696 }
697 // no match
698 throw new IllegalArgumentException("The String did not match any specified value");
699 }
700
701 // String to boolean methods
702 //-----------------------------------------------------------------------
703 /**
704 * <p>Converts a String to a boolean (optimised for performance).</p>
705 *
706 * <p><code>'true'</code>, <code>'on'</code> or <code>'yes'</code>
707 * (case insensitive) will return <code>true</code>. Otherwise,
708 * <code>false</code> is returned.</p>
709 *
710 * <p>This method performs 4 times faster (JDK1.4) than
711 * <code>Boolean.valueOf(String)</code>. However, this method accepts
712 * 'on' and 'yes' as true values.
713 *
714 * <pre>
715 * BooleanUtils.toBoolean(null) = false
716 * BooleanUtils.toBoolean("true") = true
717 * BooleanUtils.toBoolean("TRUE") = true
718 * BooleanUtils.toBoolean("tRUe") = true
719 * BooleanUtils.toBoolean("on") = true
720 * BooleanUtils.toBoolean("yes") = true
721 * BooleanUtils.toBoolean("false") = false
722 * BooleanUtils.toBoolean("x gti") = false
723 * </pre>
724 *
725 * @param str the String to check
726 * @return the boolean value of the string, <code>false</code> if no match or the String is null
727 */
728 public static boolean toBoolean(String str) {
729 return toBoolean(toBooleanObject(str));
730 }
731
732 /**
733 * <p>Converts a String to a Boolean throwing an exception if no match found.</p>
734 *
735 * <p>null is returned if there is no match.</p>
736 *
737 * <pre>
738 * BooleanUtils.toBoolean("true", "true", "false") = true
739 * BooleanUtils.toBoolean("false", "true", "false") = false
740 * </pre>
741 *
742 * @param str the String to check
743 * @param trueString the String to match for <code>true</code>
744 * (case sensitive), may be <code>null</code>
745 * @param falseString the String to match for <code>false</code>
746 * (case sensitive), may be <code>null</code>
747 * @return the boolean value of the string
748 * @throws IllegalArgumentException if the String doesn't match
749 */
750 public static boolean toBoolean(String str, String trueString, String falseString) {
751 if (str == null) {
752 if (trueString == null) {
753 return true;
754 } else if (falseString == null) {
755 return false;
756 }
757 } else if (str.equals(trueString)) {
758 return true;
759 } else if (str.equals(falseString)) {
760 return false;
761 }
762 // no match
763 throw new IllegalArgumentException("The String did not match either specified value");
764 }
765
766 // Boolean to String methods
767 //-----------------------------------------------------------------------
768 /**
769 * <p>Converts a Boolean to a String returning <code>'true'</code>,
770 * <code>'false'</code>, or <code>null</code>.</p>
771 *
772 * <pre>
773 * BooleanUtils.toStringTrueFalse(Boolean.TRUE) = "true"
774 * BooleanUtils.toStringTrueFalse(Boolean.FALSE) = "false"
775 * BooleanUtils.toStringTrueFalse(null) = null;
776 * </pre>
777 *
778 * @param bool the Boolean to check
779 * @return <code>'true'</code>, <code>'false'</code>,
780 * or <code>null</code>
781 */
782 public static String toStringTrueFalse(Boolean bool) {
783 return toString(bool, "true", "false", null);
784 }
785
786 /**
787 * <p>Converts a Boolean to a String returning <code>'on'</code>,
788 * <code>'off'</code>, or <code>null</code>.</p>
789 *
790 * <pre>
791 * BooleanUtils.toStringOnOff(Boolean.TRUE) = "on"
792 * BooleanUtils.toStringOnOff(Boolean.FALSE) = "off"
793 * BooleanUtils.toStringOnOff(null) = null;
794 * </pre>
795 *
796 * @param bool the Boolean to check
797 * @return <code>'on'</code>, <code>'off'</code>,
798 * or <code>null</code>
799 */
800 public static String toStringOnOff(Boolean bool) {
801 return toString(bool, "on", "off", null);
802 }
803
804 /**
805 * <p>Converts a Boolean to a String returning <code>'yes'</code>,
806 * <code>'no'</code>, or <code>null</code>.</p>
807 *
808 * <pre>
809 * BooleanUtils.toStringYesNo(Boolean.TRUE) = "yes"
810 * BooleanUtils.toStringYesNo(Boolean.FALSE) = "no"
811 * BooleanUtils.toStringYesNo(null) = null;
812 * </pre>
813 *
814 * @param bool the Boolean to check
815 * @return <code>'yes'</code>, <code>'no'</code>,
816 * or <code>null</code>
817 */
818 public static String toStringYesNo(Boolean bool) {
819 return toString(bool, "yes", "no", null);
820 }
821
822 /**
823 * <p>Converts a Boolean to a String returning one of the input Strings.</p>
824 *
825 * <pre>
826 * BooleanUtils.toString(Boolean.TRUE, "true", "false", null) = "true"
827 * BooleanUtils.toString(Boolean.FALSE, "true", "false", null) = "false"
828 * BooleanUtils.toString(null, "true", "false", null) = null;
829 * </pre>
830 *
831 * @param bool the Boolean to check
832 * @param trueString the String to return if <code>true</code>,
833 * may be <code>null</code>
834 * @param falseString the String to return if <code>false</code>,
835 * may be <code>null</code>
836 * @param nullString the String to return if <code>null</code>,
837 * may be <code>null</code>
838 * @return one of the three input Strings
839 */
840 public static String toString(Boolean bool, String trueString, String falseString, String nullString) {
841 if (bool == null) {
842 return nullString;
843 }
844 return bool.booleanValue() ? trueString : falseString;
845 }
846
847 // boolean to String methods
848 //-----------------------------------------------------------------------
849 /**
850 * <p>Converts a boolean to a String returning <code>'true'</code>
851 * or <code>'false'</code>.</p>
852 *
853 * <pre>
854 * BooleanUtils.toStringTrueFalse(true) = "true"
855 * BooleanUtils.toStringTrueFalse(false) = "false"
856 * </pre>
857 *
858 * @param bool the Boolean to check
859 * @return <code>'true'</code>, <code>'false'</code>,
860 * or <code>null</code>
861 */
862 public static String toStringTrueFalse(boolean bool) {
863 return toString(bool, "true", "false");
864 }
865
866 /**
867 * <p>Converts a boolean to a String returning <code>'on'</code>
868 * or <code>'off'</code>.</p>
869 *
870 * <pre>
871 * BooleanUtils.toStringOnOff(true) = "on"
872 * BooleanUtils.toStringOnOff(false) = "off"
873 * </pre>
874 *
875 * @param bool the Boolean to check
876 * @return <code>'on'</code>, <code>'off'</code>,
877 * or <code>null</code>
878 */
879 public static String toStringOnOff(boolean bool) {
880 return toString(bool, "on", "off");
881 }
882
883 /**
884 * <p>Converts a boolean to a String returning <code>'yes'</code>
885 * or <code>'no'</code>.</p>
886 *
887 * <pre>
888 * BooleanUtils.toStringYesNo(true) = "yes"
889 * BooleanUtils.toStringYesNo(false) = "no"
890 * </pre>
891 *
892 * @param bool the Boolean to check
893 * @return <code>'yes'</code>, <code>'no'</code>,
894 * or <code>null</code>
895 */
896 public static String toStringYesNo(boolean bool) {
897 return toString(bool, "yes", "no");
898 }
899
900 /**
901 * <p>Converts a boolean to a String returning one of the input Strings.</p>
902 *
903 * <pre>
904 * BooleanUtils.toString(true, "true", "false") = "true"
905 * BooleanUtils.toString(false, "true", "false") = "false"
906 * </pre>
907 *
908 * @param bool the Boolean to check
909 * @param trueString the String to return if <code>true</code>,
910 * may be <code>null</code>
911 * @param falseString the String to return if <code>false</code>,
912 * may be <code>null</code>
913 * @return one of the two input Strings
914 */
915 public static String toString(boolean bool, String trueString, String falseString) {
916 return bool ? trueString : falseString;
917 }
918
919 // xor methods
920 // ----------------------------------------------------------------------
921 /**
922 * <p>Performs an xor on a set of booleans.</p>
923 *
924 * <pre>
925 * BooleanUtils.xor(new boolean[] { true, true }) = false
926 * BooleanUtils.xor(new boolean[] { false, false }) = false
927 * BooleanUtils.xor(new boolean[] { true, false }) = true
928 * </pre>
929 *
930 * @param array an array of <code>boolean<code>s
931 * @return <code>true</code> if the xor is successful.
932 * @throws IllegalArgumentException if <code>array</code> is <code>null</code>
933 * @throws IllegalArgumentException if <code>array</code> is empty.
934 */
935 public static boolean xor(boolean[] array) {
936 // Validates input
937 if (array == null) {
938 throw new IllegalArgumentException("The Array must not be null");
939 } else if (array.length == 0) {
940 throw new IllegalArgumentException("Array is empty");
941 }
942
943 // Loops through array, comparing each item
944 int trueCount = 0;
945 for (int i = 0; i < array.length; i++) {
946 // If item is true, and trueCount is < 1, increments count
947 // Else, xor fails
948 if (array[i]) {
949 if (trueCount < 1) {
950 trueCount++;
951 } else {
952 return false;
953 }
954 }
955 }
956
957 // Returns true if there was exactly 1 true item
958 return trueCount == 1;
959 }
960
961 /**
962 * <p>Performs an xor on an array of Booleans.</p>
963 *
964 * <pre>
965 * BooleanUtils.xor(new Boolean[] { Boolean.TRUE, Boolean.TRUE }) = Boolean.FALSE
966 * BooleanUtils.xor(new Boolean[] { Boolean.FALSE, Boolean.FALSE }) = Boolean.FALSE
967 * BooleanUtils.xor(new Boolean[] { Boolean.TRUE, Boolean.FALSE }) = Boolean.TRUE
968 * </pre>
969 *
970 * @param array an array of <code>Boolean<code>s
971 * @return <code>true</code> if the xor is successful.
972 * @throws IllegalArgumentException if <code>array</code> is <code>null</code>
973 * @throws IllegalArgumentException if <code>array</code> is empty.
974 * @throws IllegalArgumentException if <code>array</code> contains a <code>null</code>
975 */
976 public static Boolean xor(Boolean[] array) {
977 if (array == null) {
978 throw new IllegalArgumentException("The Array must not be null");
979 } else if (array.length == 0) {
980 throw new IllegalArgumentException("Array is empty");
981 }
982 boolean[] primitive = null;
983 try {
984 primitive = ArrayUtils.toPrimitive(array);
985 } catch (NullPointerException ex) {
986 throw new IllegalArgumentException("The array must not contain any null elements");
987 }
988 return xor(primitive) ? Boolean.TRUE : Boolean.FALSE;
989 }
990
991 }