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