View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.lang3;
18  
19  import org.apache.commons.lang3.math.NumberUtils;
20  
21  /**
22   * <p>Operations on boolean primitives and Boolean objects.</p>
23   *
24   * <p>This class tries to handle {@code null} input gracefully.
25   * An exception will not be thrown for a {@code null} input.
26   * Each method documents its behaviour in more detail.</p>
27   *
28   * <p>#ThreadSafe#</p>
29   * @since 2.0
30   * @version $Id: BooleanUtils.java 1565252 2014-02-06 13:48:08Z sebb $
31   */
32  public class BooleanUtils {
33  
34      /**
35       * <p>{@code BooleanUtils} instances should NOT be constructed in standard programming.
36       * Instead, the class should be used as {@code BooleanUtils.negate(true);}.</p>
37       *
38       * <p>This constructor is public to permit tools that require a JavaBean instance
39       * to operate.</p>
40       */
41      public BooleanUtils() {
42        super();
43      }
44  
45      // Boolean utilities
46      //--------------------------------------------------------------------------
47      /**
48       * <p>Negates the specified boolean.</p>
49       *
50       * <p>If {@code null} is passed in, {@code null} will be returned.</p>
51       *
52       * <p>NOTE: This returns null and will throw a NullPointerException if autoboxed to a boolean. </p>
53       *
54       * <pre>
55       *   BooleanUtils.negate(Boolean.TRUE)  = Boolean.FALSE;
56       *   BooleanUtils.negate(Boolean.FALSE) = Boolean.TRUE;
57       *   BooleanUtils.negate(null)          = null;
58       * </pre>
59       *
60       * @param bool  the Boolean to negate, may be null
61       * @return the negated Boolean, or {@code null} if {@code null} input
62       */
63      public static Boolean negate(final Boolean bool) {
64          if (bool == null) {
65              return null;
66          }
67          return bool.booleanValue() ? Boolean.FALSE : Boolean.TRUE;
68      }
69  
70      // boolean Boolean methods
71      //-----------------------------------------------------------------------
72      /**
73       * <p>Checks if a {@code Boolean} value is {@code true},
74       * handling {@code null} by returning {@code false}.</p>
75       *
76       * <pre>
77       *   BooleanUtils.isTrue(Boolean.TRUE)  = true
78       *   BooleanUtils.isTrue(Boolean.FALSE) = false
79       *   BooleanUtils.isTrue(null)          = false
80       * </pre>
81       *
82       * @param bool  the boolean to check, null returns {@code false}
83       * @return {@code true} only if the input is non-null and true
84       * @since 2.1
85       */
86      public static boolean isTrue(final Boolean bool) {
87          return Boolean.TRUE.equals(bool);
88      }
89  
90      /**
91       * <p>Checks if a {@code Boolean} value is <i>not</i> {@code true},
92       * handling {@code null} by returning {@code true}.</p>
93       *
94       * <pre>
95       *   BooleanUtils.isNotTrue(Boolean.TRUE)  = false
96       *   BooleanUtils.isNotTrue(Boolean.FALSE) = true
97       *   BooleanUtils.isNotTrue(null)          = true
98       * </pre>
99       *
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(final 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(final 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(final 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(final 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(final Boolean bool, final 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(final 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(final 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(Integer.valueOf(0))    = Boolean.FALSE
230      *   BooleanUtils.toBoolean(Integer.valueOf(1))    = Boolean.TRUE
231      *   BooleanUtils.toBoolean(Integer.valueOf(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(final 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(final int value, final int trueValue, final 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(Integer.valueOf(0), Integer.valueOf(1), Integer.valueOf(0)) = false
277      *   BooleanUtils.toBoolean(Integer.valueOf(1), Integer.valueOf(1), Integer.valueOf(0)) = true
278      *   BooleanUtils.toBoolean(Integer.valueOf(2), Integer.valueOf(1), Integer.valueOf(2)) = false
279      *   BooleanUtils.toBoolean(Integer.valueOf(2), Integer.valueOf(2), Integer.valueOf(0)) = true
280      *   BooleanUtils.toBoolean(null, null, Integer.valueOf(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(final Integer value, final Integer trueValue, final 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(final int value, final int trueValue, final int falseValue, final 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(Integer.valueOf(0), Integer.valueOf(0), Integer.valueOf(2), Integer.valueOf(3)) = Boolean.TRUE
345      *   BooleanUtils.toBooleanObject(Integer.valueOf(2), Integer.valueOf(1), Integer.valueOf(2), Integer.valueOf(3)) = Boolean.FALSE
346      *   BooleanUtils.toBooleanObject(Integer.valueOf(3), Integer.valueOf(1), Integer.valueOf(2), Integer.valueOf(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(final Integer value, final Integer trueValue, final Integer falseValue, final 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(final 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)  = Integer.valueOf(1)
402      *   BooleanUtils.toIntegerObject(false) = Integer.valueOf(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(final 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)  = Integer.valueOf(1)
420      *   BooleanUtils.toIntegerObject(Boolean.FALSE) = Integer.valueOf(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(final 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(final boolean bool, final int trueValue, final 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(final Boolean bool, final int trueValue, final int falseValue, final 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, Integer.valueOf(1), Integer.valueOf(0))  = Integer.valueOf(1)
477      *   BooleanUtils.toIntegerObject(false, Integer.valueOf(1), Integer.valueOf(0)) = Integer.valueOf(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(final boolean bool, final Integer trueValue, final 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, Integer.valueOf(1), Integer.valueOf(0), Integer.valueOf(2))  = Integer.valueOf(1)
494      *   BooleanUtils.toIntegerObject(Boolean.FALSE, Integer.valueOf(1), Integer.valueOf(0), Integer.valueOf(2)) = Integer.valueOf(0)
495      *   BooleanUtils.toIntegerObject(null, Integer.valueOf(1), Integer.valueOf(0), Integer.valueOf(2))          = Integer.valueOf(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(final Boolean bool, final Integer trueValue, final Integer falseValue, final 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'}, {@code 'y'}, {@code 't'} or {@code 'yes'}
517      * (case insensitive) will return {@code true}.
518      * {@code 'false'}, {@code 'off'}, {@code 'n'}, {@code 'f'} 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      *   // N.B. case is not significant
526      *   BooleanUtils.toBooleanObject(null)    = null
527      *   BooleanUtils.toBooleanObject("true")  = Boolean.TRUE
528      *   BooleanUtils.toBooleanObject("T")     = Boolean.TRUE // i.e. T[RUE]
529      *   BooleanUtils.toBooleanObject("false") = Boolean.FALSE
530      *   BooleanUtils.toBooleanObject("f")     = Boolean.FALSE // i.e. f[alse]
531      *   BooleanUtils.toBooleanObject("No")    = Boolean.FALSE
532      *   BooleanUtils.toBooleanObject("n")     = Boolean.FALSE // i.e. n[o]
533      *   BooleanUtils.toBooleanObject("on")    = Boolean.TRUE
534      *   BooleanUtils.toBooleanObject("ON")    = Boolean.TRUE
535      *   BooleanUtils.toBooleanObject("off")   = Boolean.FALSE
536      *   BooleanUtils.toBooleanObject("oFf")   = Boolean.FALSE
537      *   BooleanUtils.toBooleanObject("yes")   = Boolean.TRUE
538      *   BooleanUtils.toBooleanObject("Y")     = Boolean.TRUE // i.e. Y[ES]
539      *   BooleanUtils.toBooleanObject("blue")  = null
540      *   BooleanUtils.toBooleanObject("true ") = null // trailing space (too long)
541      *   BooleanUtils.toBooleanObject("ono")   = null // does not match on or no
542      * </pre>
543      *
544      * @param str  the String to check; upper and lower case are treated as the same
545      * @return the Boolean value of the string, {@code null} if no match or {@code null} input
546      */
547     public static Boolean toBooleanObject(final String str) {
548         // Previously used equalsIgnoreCase, which was fast for interned 'true'.
549         // Non interned 'true' matched 15 times slower.
550         //
551         // Optimisation provides same performance as before for interned 'true'.
552         // Similar performance for null, 'false', and other strings not length 2/3/4.
553         // 'true'/'TRUE' match 4 times slower, 'tRUE'/'True' 7 times slower.
554         if (str == "true") {
555             return Boolean.TRUE;
556         }
557         if (str == null) {
558             return null;
559         }
560         switch (str.length()) {
561             case 1: {
562                 final char ch0 = str.charAt(0);
563                 if (ch0 == 'y' || ch0 == 'Y' ||
564                     ch0 == 't' || ch0 == 'T') {
565                     return Boolean.TRUE;
566                 }
567                 if (ch0 == 'n' || ch0 == 'N' ||
568                     ch0 == 'f' || ch0 == 'F') {
569                     return Boolean.FALSE;
570                 }
571                 break;
572             }
573             case 2: {
574                 final char ch0 = str.charAt(0);
575                 final char ch1 = str.charAt(1);
576                 if ((ch0 == 'o' || ch0 == 'O') &&
577                     (ch1 == 'n' || ch1 == 'N') ) {
578                     return Boolean.TRUE;
579                 }
580                 if ((ch0 == 'n' || ch0 == 'N') &&
581                     (ch1 == 'o' || ch1 == 'O') ) {
582                     return Boolean.FALSE;
583                 }
584                 break;
585             }
586             case 3: {
587                 final char ch0 = str.charAt(0);
588                 final char ch1 = str.charAt(1);
589                 final char ch2 = str.charAt(2);
590                 if ((ch0 == 'y' || ch0 == 'Y') &&
591                     (ch1 == 'e' || ch1 == 'E') &&
592                     (ch2 == 's' || ch2 == 'S') ) {
593                     return Boolean.TRUE;
594                 }
595                 if ((ch0 == 'o' || ch0 == 'O') &&
596                     (ch1 == 'f' || ch1 == 'F') &&
597                     (ch2 == 'f' || ch2 == 'F') ) {
598                     return Boolean.FALSE;
599                 }
600                 break;
601             }
602             case 4: {
603                 final char ch0 = str.charAt(0);
604                 final char ch1 = str.charAt(1);
605                 final char ch2 = str.charAt(2);
606                 final char ch3 = str.charAt(3);
607                 if ((ch0 == 't' || ch0 == 'T') &&
608                     (ch1 == 'r' || ch1 == 'R') &&
609                     (ch2 == 'u' || ch2 == 'U') &&
610                     (ch3 == 'e' || ch3 == 'E') ) {
611                     return Boolean.TRUE;
612                 }
613                 break;
614             }
615             case 5: {
616                 final char ch0 = str.charAt(0);
617                 final char ch1 = str.charAt(1);
618                 final char ch2 = str.charAt(2);
619                 final char ch3 = str.charAt(3);
620                 final char ch4 = str.charAt(4);
621                 if ((ch0 == 'f' || ch0 == 'F') &&
622                     (ch1 == 'a' || ch1 == 'A') &&
623                     (ch2 == 'l' || ch2 == 'L') &&
624                     (ch3 == 's' || ch3 == 'S') &&
625                     (ch4 == 'e' || ch4 == 'E') ) {
626                     return Boolean.FALSE;
627                 }
628                 break;
629             }
630         default:
631             break;
632         }
633 
634         return null;
635     }
636 
637     /**
638      * <p>Converts a String to a Boolean throwing an exception if no match.</p>
639      *
640      * <p>NOTE: This returns null and will throw a NullPointerException if autoboxed to a boolean. </p>
641      *
642      * <pre>
643      *   BooleanUtils.toBooleanObject("true", "true", "false", "null")  = Boolean.TRUE
644      *   BooleanUtils.toBooleanObject("false", "true", "false", "null") = Boolean.FALSE
645      *   BooleanUtils.toBooleanObject("null", "true", "false", "null")  = null
646      * </pre>
647      *
648      * @param str  the String to check
649      * @param trueString  the String to match for {@code true} (case sensitive), may be {@code null}
650      * @param falseString  the String to match for {@code false} (case sensitive), may be {@code null}
651      * @param nullString  the String to match for {@code null} (case sensitive), may be {@code null}
652      * @return the Boolean value of the string, {@code null} if either the String matches {@code nullString}
653      *  or if {@code null} input and {@code nullString} is {@code null}
654      * @throws IllegalArgumentException if the String doesn't match
655      */
656     public static Boolean toBooleanObject(final String str, final String trueString, final String falseString, final String nullString) {
657         if (str == null) {
658             if (trueString == null) {
659                 return Boolean.TRUE;
660             }
661             if (falseString == null) {
662                 return Boolean.FALSE;
663             }
664             if (nullString == null) {
665                 return null;
666             }
667         } else if (str.equals(trueString)) {
668             return Boolean.TRUE;
669         } else if (str.equals(falseString)) {
670             return Boolean.FALSE;
671         } else if (str.equals(nullString)) {
672             return null;
673         }
674         // no match
675         throw new IllegalArgumentException("The String did not match any specified value");
676     }
677 
678     // String to boolean methods
679     //-----------------------------------------------------------------------
680     /**
681      * <p>Converts a String to a boolean (optimised for performance).</p>
682      *
683      * <p>{@code 'true'}, {@code 'on'}, {@code 'y'}, {@code 't'} or {@code 'yes'}
684      * (case insensitive) will return {@code true}. Otherwise,
685      * {@code false} is returned.</p>
686      *
687      * <p>This method performs 4 times faster (JDK1.4) than
688      * {@code Boolean.valueOf(String)}. However, this method accepts
689      * 'on' and 'yes', 't', 'y' as true values.
690      *
691      * <pre>
692      *   BooleanUtils.toBoolean(null)    = false
693      *   BooleanUtils.toBoolean("true")  = true
694      *   BooleanUtils.toBoolean("TRUE")  = true
695      *   BooleanUtils.toBoolean("tRUe")  = true
696      *   BooleanUtils.toBoolean("on")    = true
697      *   BooleanUtils.toBoolean("yes")   = true
698      *   BooleanUtils.toBoolean("false") = false
699      *   BooleanUtils.toBoolean("x gti") = false
700      *   BooleanUtils.toBooleanObject("y") = true
701      *   BooleanUtils.toBooleanObject("n") = false
702      *   BooleanUtils.toBooleanObject("t") = true
703      *   BooleanUtils.toBooleanObject("f") = false 
704      * </pre>
705      *
706      * @param str  the String to check
707      * @return the boolean value of the string, {@code false} if no match or the String is null
708      */
709     public static boolean toBoolean(final String str) {
710         return toBooleanObject(str) == Boolean.TRUE;
711     }
712 
713     /**
714      * <p>Converts a String to a Boolean throwing an exception if no match found.</p>
715      *
716      * <pre>
717      *   BooleanUtils.toBoolean("true", "true", "false")  = true
718      *   BooleanUtils.toBoolean("false", "true", "false") = false
719      * </pre>
720      *
721      * @param str  the String to check
722      * @param trueString  the String to match for {@code true} (case sensitive), may be {@code null}
723      * @param falseString  the String to match for {@code false} (case sensitive), may be {@code null}
724      * @return the boolean value of the string
725      * @throws IllegalArgumentException if the String doesn't match
726      */
727     public static boolean toBoolean(final String str, final String trueString, final String falseString) {
728         if (str == trueString) {
729             return true;
730         } else if (str == falseString) {
731             return false;
732         } else if (str != null) {
733             if (str.equals(trueString)) {
734                 return true;
735             } else if (str.equals(falseString)) {
736                 return false;
737             }
738         }
739         // no match
740         throw new IllegalArgumentException("The String did not match either specified value");
741     }
742 
743     // Boolean to String methods
744     //-----------------------------------------------------------------------
745     /**
746      * <p>Converts a Boolean to a String returning {@code 'true'},
747      * {@code 'false'}, or {@code null}.</p>
748      *
749      * <pre>
750      *   BooleanUtils.toStringTrueFalse(Boolean.TRUE)  = "true"
751      *   BooleanUtils.toStringTrueFalse(Boolean.FALSE) = "false"
752      *   BooleanUtils.toStringTrueFalse(null)          = null;
753      * </pre>
754      *
755      * @param bool  the Boolean to check
756      * @return {@code 'true'}, {@code 'false'}, or {@code null}
757      */
758     public static String toStringTrueFalse(final Boolean bool) {
759         return toString(bool, "true", "false", null);
760     }
761 
762     /**
763      * <p>Converts a Boolean to a String returning {@code 'on'},
764      * {@code 'off'}, or {@code null}.</p>
765      *
766      * <pre>
767      *   BooleanUtils.toStringOnOff(Boolean.TRUE)  = "on"
768      *   BooleanUtils.toStringOnOff(Boolean.FALSE) = "off"
769      *   BooleanUtils.toStringOnOff(null)          = null;
770      * </pre>
771      *
772      * @param bool  the Boolean to check
773      * @return {@code 'on'}, {@code 'off'}, or {@code null}
774      */
775     public static String toStringOnOff(final Boolean bool) {
776         return toString(bool, "on", "off", null);
777     }
778 
779     /**
780      * <p>Converts a Boolean to a String returning {@code 'yes'},
781      * {@code 'no'}, or {@code null}.</p>
782      *
783      * <pre>
784      *   BooleanUtils.toStringYesNo(Boolean.TRUE)  = "yes"
785      *   BooleanUtils.toStringYesNo(Boolean.FALSE) = "no"
786      *   BooleanUtils.toStringYesNo(null)          = null;
787      * </pre>
788      *
789      * @param bool  the Boolean to check
790      * @return {@code 'yes'}, {@code 'no'}, or {@code null}
791      */
792     public static String toStringYesNo(final Boolean bool) {
793         return toString(bool, "yes", "no", null);
794     }
795 
796     /**
797      * <p>Converts a Boolean to a String returning one of the input Strings.</p>
798      *
799      * <pre>
800      *   BooleanUtils.toString(Boolean.TRUE, "true", "false", null)   = "true"
801      *   BooleanUtils.toString(Boolean.FALSE, "true", "false", null)  = "false"
802      *   BooleanUtils.toString(null, "true", "false", null)           = null;
803      * </pre>
804      *
805      * @param bool  the Boolean to check
806      * @param trueString  the String to return if {@code true}, may be {@code null}
807      * @param falseString  the String to return if {@code false}, may be {@code null}
808      * @param nullString  the String to return if {@code null}, may be {@code null}
809      * @return one of the three input Strings
810      */
811     public static String toString(final Boolean bool, final String trueString, final String falseString, final String nullString) {
812         if (bool == null) {
813             return nullString;
814         }
815         return bool.booleanValue() ? trueString : falseString;
816     }
817 
818     // boolean to String methods
819     //-----------------------------------------------------------------------
820     /**
821      * <p>Converts a boolean to a String returning {@code 'true'}
822      * or {@code 'false'}.</p>
823      *
824      * <pre>
825      *   BooleanUtils.toStringTrueFalse(true)   = "true"
826      *   BooleanUtils.toStringTrueFalse(false)  = "false"
827      * </pre>
828      *
829      * @param bool  the Boolean to check
830      * @return {@code 'true'}, {@code 'false'}, or {@code null}
831      */
832     public static String toStringTrueFalse(final boolean bool) {
833         return toString(bool, "true", "false");
834     }
835 
836     /**
837      * <p>Converts a boolean to a String returning {@code 'on'}
838      * or {@code 'off'}.</p>
839      *
840      * <pre>
841      *   BooleanUtils.toStringOnOff(true)   = "on"
842      *   BooleanUtils.toStringOnOff(false)  = "off"
843      * </pre>
844      *
845      * @param bool  the Boolean to check
846      * @return {@code 'on'}, {@code 'off'}, or {@code null}
847      */
848     public static String toStringOnOff(final boolean bool) {
849         return toString(bool, "on", "off");
850     }
851 
852     /**
853      * <p>Converts a boolean to a String returning {@code 'yes'}
854      * or {@code 'no'}.</p>
855      *
856      * <pre>
857      *   BooleanUtils.toStringYesNo(true)   = "yes"
858      *   BooleanUtils.toStringYesNo(false)  = "no"
859      * </pre>
860      *
861      * @param bool  the Boolean to check
862      * @return {@code 'yes'}, {@code 'no'}, or {@code null}
863      */
864     public static String toStringYesNo(final boolean bool) {
865         return toString(bool, "yes", "no");
866     }
867 
868     /**
869      * <p>Converts a boolean to a String returning one of the input Strings.</p>
870      *
871      * <pre>
872      *   BooleanUtils.toString(true, "true", "false")   = "true"
873      *   BooleanUtils.toString(false, "true", "false")  = "false"
874      * </pre>
875      *
876      * @param bool  the Boolean to check
877      * @param trueString  the String to return if {@code true}, may be {@code null}
878      * @param falseString  the String to return if {@code false}, may be {@code null}
879      * @return one of the two input Strings
880      */
881     public static String toString(final boolean bool, final String trueString, final String falseString) {
882         return bool ? trueString : falseString;
883     }
884 
885     // logical operations
886     // ----------------------------------------------------------------------
887     /**
888      * <p>Performs an and on a set of booleans.</p>
889      *
890      * <pre>
891      *   BooleanUtils.and(true, true)         = true
892      *   BooleanUtils.and(false, false)       = false
893      *   BooleanUtils.and(true, false)        = false
894      *   BooleanUtils.and(true, true, false)  = false
895      *   BooleanUtils.and(true, true, true)   = true
896      * </pre>
897      *
898      * @param array  an array of {@code boolean}s
899      * @return {@code true} if the and is successful.
900      * @throws IllegalArgumentException if {@code array} is {@code null}
901      * @throws IllegalArgumentException if {@code array} is empty.
902      * @since 3.0.1
903      */
904     public static boolean and(final boolean... array) {
905         // Validates input
906         if (array == null) {
907             throw new IllegalArgumentException("The Array must not be null");
908         }
909         if (array.length == 0) {
910             throw new IllegalArgumentException("Array is empty");
911         }
912         for (final boolean element : array) {
913             if (!element) {
914                 return false;
915             }
916         }
917         return true;
918     }
919 
920     /**
921      * <p>Performs an and on an array of Booleans.</p>
922      *
923      * <pre>
924      *   BooleanUtils.and(Boolean.TRUE, Boolean.TRUE)                 = Boolean.TRUE
925      *   BooleanUtils.and(Boolean.FALSE, Boolean.FALSE)               = Boolean.FALSE
926      *   BooleanUtils.and(Boolean.TRUE, Boolean.FALSE)                = Boolean.FALSE
927      *   BooleanUtils.and(Boolean.TRUE, Boolean.TRUE, Boolean.TRUE)   = Boolean.TRUE
928      *   BooleanUtils.and(Boolean.FALSE, Boolean.FALSE, Boolean.TRUE) = Boolean.FALSE
929      *   BooleanUtils.and(Boolean.TRUE, Boolean.FALSE, Boolean.TRUE)  = Boolean.FALSE
930      * </pre>
931      *
932      * @param array  an array of {@code Boolean}s
933      * @return {@code true} if the and is successful.
934      * @throws IllegalArgumentException if {@code array} is {@code null}
935      * @throws IllegalArgumentException if {@code array} is empty.
936      * @throws IllegalArgumentException if {@code array} contains a {@code null}
937      * @since 3.0.1
938      */
939     public static Boolean and(final Boolean... array) {
940         if (array == null) {
941             throw new IllegalArgumentException("The Array must not be null");
942         }
943         if (array.length == 0) {
944             throw new IllegalArgumentException("Array is empty");
945         }
946         try {
947             final boolean[] primitive = ArrayUtils.toPrimitive(array);
948             return and(primitive) ? Boolean.TRUE : Boolean.FALSE;
949         } catch (final NullPointerException ex) {
950             throw new IllegalArgumentException("The array must not contain any null elements");
951         }
952     }
953 
954     /**
955      * <p>Performs an or on a set of booleans.</p>
956      *
957      * <pre>
958      *   BooleanUtils.or(true, true)          = true
959      *   BooleanUtils.or(false, false)        = false
960      *   BooleanUtils.or(true, false)         = true
961      *   BooleanUtils.or(true, true, false)   = true
962      *   BooleanUtils.or(true, true, true)    = true
963      *   BooleanUtils.or(false, false, false) = false
964      * </pre>
965      *
966      * @param array  an array of {@code boolean}s
967      * @return {@code true} if the or is successful.
968      * @throws IllegalArgumentException if {@code array} is {@code null}
969      * @throws IllegalArgumentException if {@code array} is empty.
970      * @since 3.0.1
971      */
972     public static boolean or(final boolean... array) {
973         // Validates input
974         if (array == null) {
975             throw new IllegalArgumentException("The Array must not be null");
976         }
977         if (array.length == 0) {
978             throw new IllegalArgumentException("Array is empty");
979         }
980         for (final boolean element : array) {
981             if (element) {
982                 return true;
983             }
984         }
985         return false;
986     }
987 
988     /**
989      * <p>Performs an or on an array of Booleans.</p>
990      *
991      * <pre>
992      *   BooleanUtils.or(Boolean.TRUE, Boolean.TRUE)                  = Boolean.TRUE
993      *   BooleanUtils.or(Boolean.FALSE, Boolean.FALSE)                = Boolean.FALSE
994      *   BooleanUtils.or(Boolean.TRUE, Boolean.FALSE)                 = Boolean.TRUE
995      *   BooleanUtils.or(Boolean.TRUE, Boolean.TRUE, Boolean.TRUE)    = Boolean.TRUE
996      *   BooleanUtils.or(Boolean.FALSE, Boolean.FALSE, Boolean.TRUE)  = Boolean.TRUE
997      *   BooleanUtils.or(Boolean.TRUE, Boolean.FALSE, Boolean.TRUE)   = Boolean.TRUE
998      *   BooleanUtils.or(Boolean.FALSE, Boolean.FALSE, Boolean.FALSE) = Boolean.FALSE
999      * </pre>
1000      *
1001      * @param array  an array of {@code Boolean}s
1002      * @return {@code true} if the or is successful.
1003      * @throws IllegalArgumentException if {@code array} is {@code null}
1004      * @throws IllegalArgumentException if {@code array} is empty.
1005      * @throws IllegalArgumentException if {@code array} contains a {@code null}
1006      * @since 3.0.1
1007      */
1008     public static Boolean or(final Boolean... array) {
1009         if (array == null) {
1010             throw new IllegalArgumentException("The Array must not be null");
1011         }
1012         if (array.length == 0) {
1013             throw new IllegalArgumentException("Array is empty");
1014         }
1015         try {
1016             final boolean[] primitive = ArrayUtils.toPrimitive(array);
1017             return or(primitive) ? Boolean.TRUE : Boolean.FALSE;
1018         } catch (final NullPointerException ex) {
1019             throw new IllegalArgumentException("The array must not contain any null elements");
1020         }
1021     }
1022 
1023     /**
1024      * <p>Performs an xor on a set of booleans.</p>
1025      *
1026      * <pre>
1027      *   BooleanUtils.xor(true, true)   = false
1028      *   BooleanUtils.xor(false, false) = false
1029      *   BooleanUtils.xor(true, false)  = true
1030      *   BooleanUtils.xor(true, true)   = false
1031      *   BooleanUtils.xor(false, false) = false
1032      *   BooleanUtils.xor(true, false)  = true
1033      * </pre>
1034      *
1035      * @param array  an array of {@code boolean}s
1036      * @return {@code true} if the xor is successful.
1037      * @throws IllegalArgumentException if {@code array} is {@code null}
1038      * @throws IllegalArgumentException if {@code array} is empty.
1039      */
1040     public static boolean xor(final boolean... array) {
1041         // Validates input
1042         if (array == null) {
1043             throw new IllegalArgumentException("The Array must not be null");
1044         }
1045         if (array.length == 0) {
1046             throw new IllegalArgumentException("Array is empty");
1047         }
1048 
1049         // false if the neutral element of the xor operator
1050         boolean result = false;
1051         for (final boolean element : array) {
1052             result ^= element;
1053         }
1054 
1055         return result;
1056     }
1057 
1058     /**
1059      * <p>Performs an xor on an array of Booleans.</p>
1060      *
1061      * <pre>
1062      *   BooleanUtils.xor(new Boolean[] { Boolean.TRUE, Boolean.TRUE })   = Boolean.FALSE
1063      *   BooleanUtils.xor(new Boolean[] { Boolean.FALSE, Boolean.FALSE }) = Boolean.FALSE
1064      *   BooleanUtils.xor(new Boolean[] { Boolean.TRUE, Boolean.FALSE })  = Boolean.TRUE
1065      * </pre>
1066      *
1067      * @param array  an array of {@code Boolean}s
1068      * @return {@code true} if the xor is successful.
1069      * @throws IllegalArgumentException if {@code array} is {@code null}
1070      * @throws IllegalArgumentException if {@code array} is empty.
1071      * @throws IllegalArgumentException if {@code array} contains a {@code null}
1072      */
1073     public static Boolean xor(final Boolean... array) {
1074         if (array == null) {
1075             throw new IllegalArgumentException("The Array must not be null");
1076         }
1077         if (array.length == 0) {
1078             throw new IllegalArgumentException("Array is empty");
1079         }
1080         try {
1081             final boolean[] primitive = ArrayUtils.toPrimitive(array);
1082             return xor(primitive) ? Boolean.TRUE : Boolean.FALSE;
1083         } catch (final NullPointerException ex) {
1084             throw new IllegalArgumentException("The array must not contain any null elements");
1085         }
1086     }
1087 
1088 }