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   */
31  public class BooleanUtils {
32  
33      /**
34       * <p>{@code BooleanUtils} instances should NOT be constructed in standard programming.
35       * Instead, the class should be used as {@code BooleanUtils.negate(true);}.</p>
36       *
37       * <p>This constructor is public to permit tools that require a JavaBean instance
38       * to operate.</p>
39       */
40      public BooleanUtils() {
41        super();
42      }
43  
44      // Boolean utilities
45      //--------------------------------------------------------------------------
46      /**
47       * <p>Negates the specified boolean.</p>
48       *
49       * <p>If {@code null} is passed in, {@code null} will be returned.</p>
50       *
51       * <p>NOTE: This returns null and will throw a NullPointerException if autoboxed to a boolean. </p>
52       *
53       * <pre>
54       *   BooleanUtils.negate(Boolean.TRUE)  = Boolean.FALSE;
55       *   BooleanUtils.negate(Boolean.FALSE) = Boolean.TRUE;
56       *   BooleanUtils.negate(null)          = null;
57       * </pre>
58       *
59       * @param bool  the Boolean to negate, may be null
60       * @return the negated Boolean, or {@code null} if {@code null} input
61       */
62      public static Boolean negate(final Boolean bool) {
63          if (bool == null) {
64              return null;
65          }
66          return bool.booleanValue() ? Boolean.FALSE : Boolean.TRUE;
67      }
68  
69      // boolean Boolean methods
70      //-----------------------------------------------------------------------
71      /**
72       * <p>Checks if a {@code Boolean} value is {@code true},
73       * handling {@code null} by returning {@code false}.</p>
74       *
75       * <pre>
76       *   BooleanUtils.isTrue(Boolean.TRUE)  = true
77       *   BooleanUtils.isTrue(Boolean.FALSE) = false
78       *   BooleanUtils.isTrue(null)          = false
79       * </pre>
80       *
81       * @param bool  the boolean to check, null returns {@code false}
82       * @return {@code true} only if the input is non-null and true
83       * @since 2.1
84       */
85      public static boolean isTrue(final Boolean bool) {
86          return Boolean.TRUE.equals(bool);
87      }
88  
89      /**
90       * <p>Checks if a {@code Boolean} value is <i>not</i> {@code true},
91       * handling {@code null} by returning {@code true}.</p>
92       *
93       * <pre>
94       *   BooleanUtils.isNotTrue(Boolean.TRUE)  = false
95       *   BooleanUtils.isNotTrue(Boolean.FALSE) = true
96       *   BooleanUtils.isNotTrue(null)          = true
97       * </pre>
98       *
99       * @param bool  the boolean to check, null returns {@code true}
100      * @return {@code true} if the input is null or false
101      * @since 2.3
102      */
103     public static boolean isNotTrue(final Boolean bool) {
104         return !isTrue(bool);
105     }
106 
107     /**
108      * <p>Checks if a {@code Boolean} value is {@code false},
109      * handling {@code null} by returning {@code false}.</p>
110      *
111      * <pre>
112      *   BooleanUtils.isFalse(Boolean.TRUE)  = false
113      *   BooleanUtils.isFalse(Boolean.FALSE) = true
114      *   BooleanUtils.isFalse(null)          = false
115      * </pre>
116      *
117      * @param bool  the boolean to check, null returns {@code false}
118      * @return {@code true} only if the input is non-null and false
119      * @since 2.1
120      */
121     public static boolean isFalse(final Boolean bool) {
122         return Boolean.FALSE.equals(bool);
123     }
124 
125     /**
126      * <p>Checks if a {@code Boolean} value is <i>not</i> {@code false},
127      * handling {@code null} by returning {@code true}.</p>
128      *
129      * <pre>
130      *   BooleanUtils.isNotFalse(Boolean.TRUE)  = true
131      *   BooleanUtils.isNotFalse(Boolean.FALSE) = false
132      *   BooleanUtils.isNotFalse(null)          = true
133      * </pre>
134      *
135      * @param bool  the boolean to check, null returns {@code true}
136      * @return {@code true} if the input is null or true
137      * @since 2.3
138      */
139     public static boolean isNotFalse(final Boolean bool) {
140         return !isFalse(bool);
141     }
142 
143     //-----------------------------------------------------------------------
144     /**
145      * <p>Converts a Boolean to a boolean handling {@code null}
146      * by returning {@code false}.</p>
147      *
148      * <pre>
149      *   BooleanUtils.toBoolean(Boolean.TRUE)  = true
150      *   BooleanUtils.toBoolean(Boolean.FALSE) = false
151      *   BooleanUtils.toBoolean(null)          = false
152      * </pre>
153      *
154      * @param bool  the boolean to convert
155      * @return {@code true} or {@code false}, {@code null} returns {@code false}
156      */
157     public static boolean toBoolean(final Boolean bool) {
158         return bool != null && bool.booleanValue();
159     }
160 
161     /**
162      * <p>Converts a Boolean to a boolean handling {@code null}.</p>
163      *
164      * <pre>
165      *   BooleanUtils.toBooleanDefaultIfNull(Boolean.TRUE, false) = true
166      *   BooleanUtils.toBooleanDefaultIfNull(Boolean.FALSE, true) = false
167      *   BooleanUtils.toBooleanDefaultIfNull(null, true)          = true
168      * </pre>
169      *
170      * @param bool  the boolean to convert
171      * @param valueIfNull  the boolean value to return if {@code null}
172      * @return {@code true} or {@code false}
173      */
174     public static boolean toBooleanDefaultIfNull(final Boolean bool, final boolean valueIfNull) {
175         if (bool == null) {
176             return valueIfNull;
177         }
178         return bool.booleanValue();
179     }
180 
181     // Integer to Boolean methods
182     //-----------------------------------------------------------------------
183     /**
184      * <p>Converts an int to a boolean using the convention that {@code zero}
185      * is {@code false}.</p>
186      *
187      * <pre>
188      *   BooleanUtils.toBoolean(0) = false
189      *   BooleanUtils.toBoolean(1) = true
190      *   BooleanUtils.toBoolean(2) = true
191      * </pre>
192      *
193      * @param value  the int to convert
194      * @return {@code true} if non-zero, {@code false}
195      *  if zero
196      */
197     public static boolean toBoolean(final int value) {
198         return value != 0;
199     }
200 
201     /**
202      * <p>Converts an int to a Boolean using the convention that {@code zero}
203      * is {@code false}.</p>
204      *
205      * <pre>
206      *   BooleanUtils.toBoolean(0) = Boolean.FALSE
207      *   BooleanUtils.toBoolean(1) = Boolean.TRUE
208      *   BooleanUtils.toBoolean(2) = Boolean.TRUE
209      * </pre>
210      *
211      * @param value  the int to convert
212      * @return Boolean.TRUE if non-zero, Boolean.FALSE if zero,
213      *  {@code null} if {@code null}
214      */
215     public static Boolean toBooleanObject(final int value) {
216         return value == 0 ? Boolean.FALSE : Boolean.TRUE;
217     }
218 
219     /**
220      * <p>Converts an Integer to a Boolean using the convention that {@code zero}
221      * is {@code false}.</p>
222      *
223      * <p>{@code null} will be converted to {@code null}.</p>
224      *
225      * <p>NOTE: This returns null and will throw a NullPointerException if autoboxed to a boolean. </p>
226      *
227      * <pre>
228      *   BooleanUtils.toBoolean(Integer.valueOf(0))    = Boolean.FALSE
229      *   BooleanUtils.toBoolean(Integer.valueOf(1))    = Boolean.TRUE
230      *   BooleanUtils.toBoolean(Integer.valueOf(null)) = null
231      * </pre>
232      *
233      * @param value  the Integer to convert
234      * @return Boolean.TRUE if non-zero, Boolean.FALSE if zero,
235      *  {@code null} if {@code null} input
236      */
237     public static Boolean toBooleanObject(final Integer value) {
238         if (value == null) {
239             return null;
240         }
241         return value.intValue() == 0 ? Boolean.FALSE : Boolean.TRUE;
242     }
243 
244     /**
245      * <p>Converts an int to a boolean specifying the conversion values.</p>
246      *
247      * <pre>
248      *   BooleanUtils.toBoolean(0, 1, 0) = false
249      *   BooleanUtils.toBoolean(1, 1, 0) = true
250      *   BooleanUtils.toBoolean(2, 1, 2) = false
251      *   BooleanUtils.toBoolean(2, 2, 0) = true
252      * </pre>
253      *
254      * @param value  the Integer to convert
255      * @param trueValue  the value to match for {@code true}
256      * @param falseValue  the value to match for {@code false}
257      * @return {@code true} or {@code false}
258      * @throws IllegalArgumentException if no match
259      */
260     public static boolean toBoolean(final int value, final int trueValue, final int falseValue) {
261         if (value == trueValue) {
262             return true;
263         }
264         if (value == falseValue) {
265             return false;
266         }
267         // no match
268         throw new IllegalArgumentException("The Integer did not match either specified value");
269     }
270 
271     /**
272      * <p>Converts an Integer to a boolean specifying the conversion values.</p>
273      *
274      * <pre>
275      *   BooleanUtils.toBoolean(Integer.valueOf(0), Integer.valueOf(1), Integer.valueOf(0)) = false
276      *   BooleanUtils.toBoolean(Integer.valueOf(1), Integer.valueOf(1), Integer.valueOf(0)) = true
277      *   BooleanUtils.toBoolean(Integer.valueOf(2), Integer.valueOf(1), Integer.valueOf(2)) = false
278      *   BooleanUtils.toBoolean(Integer.valueOf(2), Integer.valueOf(2), Integer.valueOf(0)) = true
279      *   BooleanUtils.toBoolean(null, null, Integer.valueOf(0))                     = true
280      * </pre>
281      *
282      * @param value  the Integer to convert
283      * @param trueValue  the value to match for {@code true}, may be {@code null}
284      * @param falseValue  the value to match for {@code false}, may be {@code null}
285      * @return {@code true} or {@code false}
286      * @throws IllegalArgumentException if no match
287      */
288     public static boolean toBoolean(final Integer value, final Integer trueValue, final Integer falseValue) {
289         if (value == null) {
290             if (trueValue == null) {
291                 return true;
292             }
293             if (falseValue == null) {
294                 return false;
295             }
296         } else if (value.equals(trueValue)) {
297             return true;
298         } else if (value.equals(falseValue)) {
299             return false;
300         }
301         // no match
302         throw new IllegalArgumentException("The Integer did not match either specified value");
303     }
304 
305     /**
306      * <p>Converts an int to a Boolean specifying the conversion values.</p>
307      *
308      * <p>NOTE: This returns null and will throw a NullPointerException if autoboxed to a boolean. </p>
309      *
310      * <pre>
311      *   BooleanUtils.toBooleanObject(0, 0, 2, 3) = Boolean.TRUE
312      *   BooleanUtils.toBooleanObject(2, 1, 2, 3) = Boolean.FALSE
313      *   BooleanUtils.toBooleanObject(3, 1, 2, 3) = null
314      * </pre>
315      *
316      * @param value  the Integer to convert
317      * @param trueValue  the value to match for {@code true}
318      * @param falseValue  the value to match for {@code false}
319      * @param nullValue  the value to to match for {@code null}
320      * @return Boolean.TRUE, Boolean.FALSE, or {@code null}
321      * @throws IllegalArgumentException if no match
322      */
323     public static Boolean toBooleanObject(final int value, final int trueValue, final int falseValue, final int nullValue) {
324         if (value == trueValue) {
325             return Boolean.TRUE;
326         }
327         if (value == falseValue) {
328             return Boolean.FALSE;
329         }
330         if (value == nullValue) {
331             return null;
332         }
333         // no match
334         throw new IllegalArgumentException("The Integer did not match any specified value");
335     }
336 
337     /**
338      * <p>Converts an Integer to a Boolean specifying the conversion values.</p>
339      *
340      * <p>NOTE: This returns null and will throw a NullPointerException if autoboxed to a boolean. </p>
341      *
342      * <pre>
343      *   BooleanUtils.toBooleanObject(Integer.valueOf(0), Integer.valueOf(0), Integer.valueOf(2), Integer.valueOf(3)) = Boolean.TRUE
344      *   BooleanUtils.toBooleanObject(Integer.valueOf(2), Integer.valueOf(1), Integer.valueOf(2), Integer.valueOf(3)) = Boolean.FALSE
345      *   BooleanUtils.toBooleanObject(Integer.valueOf(3), Integer.valueOf(1), Integer.valueOf(2), Integer.valueOf(3)) = null
346      * </pre>
347      *
348      * @param value  the Integer to convert
349      * @param trueValue  the value to match for {@code true}, may be {@code null}
350      * @param falseValue  the value to match for {@code false}, may be {@code null}
351      * @param nullValue  the value to to match for {@code null}, may be {@code null}
352      * @return Boolean.TRUE, Boolean.FALSE, or {@code null}
353      * @throws IllegalArgumentException if no match
354      */
355     public static Boolean toBooleanObject(final Integer value, final Integer trueValue, final Integer falseValue, final Integer nullValue) {
356         if (value == null) {
357             if (trueValue == null) {
358                 return Boolean.TRUE;
359             }
360             if (falseValue == null) {
361                 return Boolean.FALSE;
362             }
363             if (nullValue == null) {
364                 return null;
365             }
366         } else if (value.equals(trueValue)) {
367             return Boolean.TRUE;
368         } else if (value.equals(falseValue)) {
369             return Boolean.FALSE;
370         } else if (value.equals(nullValue)) {
371             return null;
372         }
373         // no match
374         throw new IllegalArgumentException("The Integer did not match any specified value");
375     }
376 
377     // Boolean to Integer methods
378     //-----------------------------------------------------------------------
379     /**
380      * <p>Converts a boolean to an int using the convention that
381      * {@code zero} is {@code false}.</p>
382      *
383      * <pre>
384      *   BooleanUtils.toInteger(true)  = 1
385      *   BooleanUtils.toInteger(false) = 0
386      * </pre>
387      *
388      * @param bool  the boolean to convert
389      * @return one if {@code true}, zero if {@code false}
390      */
391     public static int toInteger(final boolean bool) {
392         return bool ? 1 : 0;
393     }
394 
395     /**
396      * <p>Converts a boolean to an Integer using the convention that
397      * {@code zero} is {@code false}.</p>
398      *
399      * <pre>
400      *   BooleanUtils.toIntegerObject(true)  = Integer.valueOf(1)
401      *   BooleanUtils.toIntegerObject(false) = Integer.valueOf(0)
402      * </pre>
403      *
404      * @param bool  the boolean to convert
405      * @return one if {@code true}, zero if {@code false}
406      */
407     public static Integer toIntegerObject(final boolean bool) {
408         return bool ? NumberUtils.INTEGER_ONE : NumberUtils.INTEGER_ZERO;
409     }
410 
411     /**
412      * <p>Converts a Boolean to a Integer using the convention that
413      * {@code zero} is {@code false}.</p>
414      *
415      * <p>{@code null} will be converted to {@code null}.</p>
416      *
417      * <pre>
418      *   BooleanUtils.toIntegerObject(Boolean.TRUE)  = Integer.valueOf(1)
419      *   BooleanUtils.toIntegerObject(Boolean.FALSE) = Integer.valueOf(0)
420      * </pre>
421      *
422      * @param bool  the Boolean to convert
423      * @return one if Boolean.TRUE, zero if Boolean.FALSE, {@code null} if {@code null}
424      */
425     public static Integer toIntegerObject(final Boolean bool) {
426         if (bool == null) {
427             return null;
428         }
429         return bool.booleanValue() ? NumberUtils.INTEGER_ONE : NumberUtils.INTEGER_ZERO;
430     }
431 
432     /**
433      * <p>Converts a boolean to an int specifying the conversion values.</p>
434      *
435      * <pre>
436      *   BooleanUtils.toInteger(true, 1, 0)  = 1
437      *   BooleanUtils.toInteger(false, 1, 0) = 0
438      * </pre>
439      *
440      * @param bool  the to convert
441      * @param trueValue  the value to return if {@code true}
442      * @param falseValue  the value to return if {@code false}
443      * @return the appropriate value
444      */
445     public static int toInteger(final boolean bool, final int trueValue, final int falseValue) {
446         return bool ? trueValue : falseValue;
447     }
448 
449     /**
450      * <p>Converts a Boolean to an int specifying the conversion values.</p>
451      *
452      * <pre>
453      *   BooleanUtils.toInteger(Boolean.TRUE, 1, 0, 2)  = 1
454      *   BooleanUtils.toInteger(Boolean.FALSE, 1, 0, 2) = 0
455      *   BooleanUtils.toInteger(null, 1, 0, 2)          = 2
456      * </pre>
457      *
458      * @param bool  the Boolean to convert
459      * @param trueValue  the value to return if {@code true}
460      * @param falseValue  the value to return if {@code false}
461      * @param nullValue  the value to return if {@code null}
462      * @return the appropriate value
463      */
464     public static int toInteger(final Boolean bool, final int trueValue, final int falseValue, final int nullValue) {
465         if (bool == null) {
466             return nullValue;
467         }
468         return bool.booleanValue() ? trueValue : falseValue;
469     }
470 
471     /**
472      * <p>Converts a boolean to an Integer specifying the conversion values.</p>
473      *
474      * <pre>
475      *   BooleanUtils.toIntegerObject(true, Integer.valueOf(1), Integer.valueOf(0))  = Integer.valueOf(1)
476      *   BooleanUtils.toIntegerObject(false, Integer.valueOf(1), Integer.valueOf(0)) = Integer.valueOf(0)
477      * </pre>
478      *
479      * @param bool  the to convert
480      * @param trueValue  the value to return if {@code true}, may be {@code null}
481      * @param falseValue  the value to return if {@code false}, may be {@code null}
482      * @return the appropriate value
483      */
484     public static Integer toIntegerObject(final boolean bool, final Integer trueValue, final Integer falseValue) {
485         return bool ? trueValue : falseValue;
486     }
487 
488     /**
489      * <p>Converts a Boolean to an Integer specifying the conversion values.</p>
490      *
491      * <pre>
492      *   BooleanUtils.toIntegerObject(Boolean.TRUE, Integer.valueOf(1), Integer.valueOf(0), Integer.valueOf(2))  = Integer.valueOf(1)
493      *   BooleanUtils.toIntegerObject(Boolean.FALSE, Integer.valueOf(1), Integer.valueOf(0), Integer.valueOf(2)) = Integer.valueOf(0)
494      *   BooleanUtils.toIntegerObject(null, Integer.valueOf(1), Integer.valueOf(0), Integer.valueOf(2))          = Integer.valueOf(2)
495      * </pre>
496      *
497      * @param bool  the Boolean to convert
498      * @param trueValue  the value to return if {@code true}, may be {@code null}
499      * @param falseValue  the value to return if {@code false}, may be {@code null}
500      * @param nullValue  the value to return if {@code null}, may be {@code null}
501      * @return the appropriate value
502      */
503     public static Integer toIntegerObject(final Boolean bool, final Integer trueValue, final Integer falseValue, final Integer nullValue) {
504         if (bool == null) {
505             return nullValue;
506         }
507         return bool.booleanValue() ? trueValue : falseValue;
508     }
509 
510     // String to Boolean methods
511     //-----------------------------------------------------------------------
512     /**
513      * <p>Converts a String to a Boolean.</p>
514      *
515      * <p>{@code 'true'}, {@code 'on'}, {@code 'y'}, {@code 't'} or {@code 'yes'}
516      * (case insensitive) will return {@code true}.
517      * {@code 'false'}, {@code 'off'}, {@code 'n'}, {@code 'f'} or {@code 'no'}
518      * (case insensitive) will return {@code false}.
519      * Otherwise, {@code null} is returned.</p>
520      *
521      * <p>NOTE: This returns null and will throw a NullPointerException if autoboxed to a boolean. </p>
522      *
523      * <pre>
524      *   // N.B. case is not significant
525      *   BooleanUtils.toBooleanObject(null)    = null
526      *   BooleanUtils.toBooleanObject("true")  = Boolean.TRUE
527      *   BooleanUtils.toBooleanObject("T")     = Boolean.TRUE // i.e. T[RUE]
528      *   BooleanUtils.toBooleanObject("false") = Boolean.FALSE
529      *   BooleanUtils.toBooleanObject("f")     = Boolean.FALSE // i.e. f[alse]
530      *   BooleanUtils.toBooleanObject("No")    = Boolean.FALSE
531      *   BooleanUtils.toBooleanObject("n")     = Boolean.FALSE // i.e. n[o]
532      *   BooleanUtils.toBooleanObject("on")    = Boolean.TRUE
533      *   BooleanUtils.toBooleanObject("ON")    = Boolean.TRUE
534      *   BooleanUtils.toBooleanObject("off")   = Boolean.FALSE
535      *   BooleanUtils.toBooleanObject("oFf")   = Boolean.FALSE
536      *   BooleanUtils.toBooleanObject("yes")   = Boolean.TRUE
537      *   BooleanUtils.toBooleanObject("Y")     = Boolean.TRUE // i.e. Y[ES]
538      *   BooleanUtils.toBooleanObject("blue")  = null
539      *   BooleanUtils.toBooleanObject("true ") = null // trailing space (too long)
540      *   BooleanUtils.toBooleanObject("ono")   = null // does not match on or no
541      * </pre>
542      *
543      * @param str  the String to check; upper and lower case are treated as the same
544      * @return the Boolean value of the string, {@code null} if no match or {@code null} input
545      */
546     public static Boolean toBooleanObject(final String str) {
547         // Previously used equalsIgnoreCase, which was fast for interned 'true'.
548         // Non interned 'true' matched 15 times slower.
549         //
550         // Optimisation provides same performance as before for interned 'true'.
551         // Similar performance for null, 'false', and other strings not length 2/3/4.
552         // 'true'/'TRUE' match 4 times slower, 'tRUE'/'True' 7 times slower.
553         if (str == "true") {
554             return Boolean.TRUE;
555         }
556         if (str == null) {
557             return null;
558         }
559         switch (str.length()) {
560             case 1: {
561                 final char ch0 = str.charAt(0);
562                 if (ch0 == 'y' || ch0 == 'Y' ||
563                     ch0 == 't' || ch0 == 'T') {
564                     return Boolean.TRUE;
565                 }
566                 if (ch0 == 'n' || ch0 == 'N' ||
567                     ch0 == 'f' || ch0 == 'F') {
568                     return Boolean.FALSE;
569                 }
570                 break;
571             }
572             case 2: {
573                 final char ch0 = str.charAt(0);
574                 final char ch1 = str.charAt(1);
575                 if ((ch0 == 'o' || ch0 == 'O') &&
576                     (ch1 == 'n' || ch1 == 'N') ) {
577                     return Boolean.TRUE;
578                 }
579                 if ((ch0 == 'n' || ch0 == 'N') &&
580                     (ch1 == 'o' || ch1 == 'O') ) {
581                     return Boolean.FALSE;
582                 }
583                 break;
584             }
585             case 3: {
586                 final char ch0 = str.charAt(0);
587                 final char ch1 = str.charAt(1);
588                 final char ch2 = str.charAt(2);
589                 if ((ch0 == 'y' || ch0 == 'Y') &&
590                     (ch1 == 'e' || ch1 == 'E') &&
591                     (ch2 == 's' || ch2 == 'S') ) {
592                     return Boolean.TRUE;
593                 }
594                 if ((ch0 == 'o' || ch0 == 'O') &&
595                     (ch1 == 'f' || ch1 == 'F') &&
596                     (ch2 == 'f' || ch2 == 'F') ) {
597                     return Boolean.FALSE;
598                 }
599                 break;
600             }
601             case 4: {
602                 final char ch0 = str.charAt(0);
603                 final char ch1 = str.charAt(1);
604                 final char ch2 = str.charAt(2);
605                 final char ch3 = str.charAt(3);
606                 if ((ch0 == 't' || ch0 == 'T') &&
607                     (ch1 == 'r' || ch1 == 'R') &&
608                     (ch2 == 'u' || ch2 == 'U') &&
609                     (ch3 == 'e' || ch3 == 'E') ) {
610                     return Boolean.TRUE;
611                 }
612                 break;
613             }
614             case 5: {
615                 final char ch0 = str.charAt(0);
616                 final char ch1 = str.charAt(1);
617                 final char ch2 = str.charAt(2);
618                 final char ch3 = str.charAt(3);
619                 final char ch4 = str.charAt(4);
620                 if ((ch0 == 'f' || ch0 == 'F') &&
621                     (ch1 == 'a' || ch1 == 'A') &&
622                     (ch2 == 'l' || ch2 == 'L') &&
623                     (ch3 == 's' || ch3 == 'S') &&
624                     (ch4 == 'e' || ch4 == 'E') ) {
625                     return Boolean.FALSE;
626                 }
627                 break;
628             }
629         default:
630             break;
631         }
632 
633         return null;
634     }
635 
636     /**
637      * <p>Converts a String to a Boolean throwing an exception if no match.</p>
638      *
639      * <p>NOTE: This returns null and will throw a NullPointerException if autoboxed to a boolean. </p>
640      *
641      * <pre>
642      *   BooleanUtils.toBooleanObject("true", "true", "false", "null")  = Boolean.TRUE
643      *   BooleanUtils.toBooleanObject("false", "true", "false", "null") = Boolean.FALSE
644      *   BooleanUtils.toBooleanObject("null", "true", "false", "null")  = null
645      * </pre>
646      *
647      * @param str  the String to check
648      * @param trueString  the String to match for {@code true} (case sensitive), may be {@code null}
649      * @param falseString  the String to match for {@code false} (case sensitive), may be {@code null}
650      * @param nullString  the String to match for {@code null} (case sensitive), may be {@code null}
651      * @return the Boolean value of the string, {@code null} if either the String matches {@code nullString}
652      *  or if {@code null} input and {@code nullString} is {@code null}
653      * @throws IllegalArgumentException if the String doesn't match
654      */
655     public static Boolean toBooleanObject(final String str, final String trueString, final String falseString, final String nullString) {
656         if (str == null) {
657             if (trueString == null) {
658                 return Boolean.TRUE;
659             }
660             if (falseString == null) {
661                 return Boolean.FALSE;
662             }
663             if (nullString == null) {
664                 return null;
665             }
666         } else if (str.equals(trueString)) {
667             return Boolean.TRUE;
668         } else if (str.equals(falseString)) {
669             return Boolean.FALSE;
670         } else if (str.equals(nullString)) {
671             return null;
672         }
673         // no match
674         throw new IllegalArgumentException("The String did not match any specified value");
675     }
676 
677     // String to boolean methods
678     //-----------------------------------------------------------------------
679     /**
680      * <p>Converts a String to a boolean (optimised for performance).</p>
681      *
682      * <p>{@code 'true'}, {@code 'on'}, {@code 'y'}, {@code 't'} or {@code 'yes'}
683      * (case insensitive) will return {@code true}. Otherwise,
684      * {@code false} is returned.</p>
685      *
686      * <p>This method performs 4 times faster (JDK1.4) than
687      * {@code Boolean.valueOf(String)}. However, this method accepts
688      * 'on' and 'yes', 't', 'y' as true values.
689      *
690      * <pre>
691      *   BooleanUtils.toBoolean(null)    = false
692      *   BooleanUtils.toBoolean("true")  = true
693      *   BooleanUtils.toBoolean("TRUE")  = true
694      *   BooleanUtils.toBoolean("tRUe")  = true
695      *   BooleanUtils.toBoolean("on")    = true
696      *   BooleanUtils.toBoolean("yes")   = true
697      *   BooleanUtils.toBoolean("false") = false
698      *   BooleanUtils.toBoolean("x gti") = false
699      *   BooleanUtils.toBooleanObject("y") = true
700      *   BooleanUtils.toBooleanObject("n") = false
701      *   BooleanUtils.toBooleanObject("t") = true
702      *   BooleanUtils.toBooleanObject("f") = false 
703      * </pre>
704      *
705      * @param str  the String to check
706      * @return the boolean value of the string, {@code false} if no match or the String is null
707      */
708     public static boolean toBoolean(final String str) {
709         return toBooleanObject(str) == Boolean.TRUE;
710     }
711 
712     /**
713      * <p>Converts a String to a Boolean throwing an exception if no match found.</p>
714      *
715      * <pre>
716      *   BooleanUtils.toBoolean("true", "true", "false")  = true
717      *   BooleanUtils.toBoolean("false", "true", "false") = false
718      * </pre>
719      *
720      * @param str  the String to check
721      * @param trueString  the String to match for {@code true} (case sensitive), may be {@code null}
722      * @param falseString  the String to match for {@code false} (case sensitive), may be {@code null}
723      * @return the boolean value of the string
724      * @throws IllegalArgumentException if the String doesn't match
725      */
726     public static boolean toBoolean(final String str, final String trueString, final String falseString) {
727         if (str == trueString) {
728             return true;
729         } else if (str == falseString) {
730             return false;
731         } else if (str != null) {
732             if (str.equals(trueString)) {
733                 return true;
734             } else if (str.equals(falseString)) {
735                 return false;
736             }
737         }
738         // no match
739         throw new IllegalArgumentException("The String did not match either specified value");
740     }
741 
742     // Boolean to String methods
743     //-----------------------------------------------------------------------
744     /**
745      * <p>Converts a Boolean to a String returning {@code 'true'},
746      * {@code 'false'}, or {@code null}.</p>
747      *
748      * <pre>
749      *   BooleanUtils.toStringTrueFalse(Boolean.TRUE)  = "true"
750      *   BooleanUtils.toStringTrueFalse(Boolean.FALSE) = "false"
751      *   BooleanUtils.toStringTrueFalse(null)          = null;
752      * </pre>
753      *
754      * @param bool  the Boolean to check
755      * @return {@code 'true'}, {@code 'false'}, or {@code null}
756      */
757     public static String toStringTrueFalse(final Boolean bool) {
758         return toString(bool, "true", "false", null);
759     }
760 
761     /**
762      * <p>Converts a Boolean to a String returning {@code 'on'},
763      * {@code 'off'}, or {@code null}.</p>
764      *
765      * <pre>
766      *   BooleanUtils.toStringOnOff(Boolean.TRUE)  = "on"
767      *   BooleanUtils.toStringOnOff(Boolean.FALSE) = "off"
768      *   BooleanUtils.toStringOnOff(null)          = null;
769      * </pre>
770      *
771      * @param bool  the Boolean to check
772      * @return {@code 'on'}, {@code 'off'}, or {@code null}
773      */
774     public static String toStringOnOff(final Boolean bool) {
775         return toString(bool, "on", "off", null);
776     }
777 
778     /**
779      * <p>Converts a Boolean to a String returning {@code 'yes'},
780      * {@code 'no'}, or {@code null}.</p>
781      *
782      * <pre>
783      *   BooleanUtils.toStringYesNo(Boolean.TRUE)  = "yes"
784      *   BooleanUtils.toStringYesNo(Boolean.FALSE) = "no"
785      *   BooleanUtils.toStringYesNo(null)          = null;
786      * </pre>
787      *
788      * @param bool  the Boolean to check
789      * @return {@code 'yes'}, {@code 'no'}, or {@code null}
790      */
791     public static String toStringYesNo(final Boolean bool) {
792         return toString(bool, "yes", "no", null);
793     }
794 
795     /**
796      * <p>Converts a Boolean to a String returning one of the input Strings.</p>
797      *
798      * <pre>
799      *   BooleanUtils.toString(Boolean.TRUE, "true", "false", null)   = "true"
800      *   BooleanUtils.toString(Boolean.FALSE, "true", "false", null)  = "false"
801      *   BooleanUtils.toString(null, "true", "false", null)           = null;
802      * </pre>
803      *
804      * @param bool  the Boolean to check
805      * @param trueString  the String to return if {@code true}, may be {@code null}
806      * @param falseString  the String to return if {@code false}, may be {@code null}
807      * @param nullString  the String to return if {@code null}, may be {@code null}
808      * @return one of the three input Strings
809      */
810     public static String toString(final Boolean bool, final String trueString, final String falseString, final String nullString) {
811         if (bool == null) {
812             return nullString;
813         }
814         return bool.booleanValue() ? trueString : falseString;
815     }
816 
817     // boolean to String methods
818     //-----------------------------------------------------------------------
819     /**
820      * <p>Converts a boolean to a String returning {@code 'true'}
821      * or {@code 'false'}.</p>
822      *
823      * <pre>
824      *   BooleanUtils.toStringTrueFalse(true)   = "true"
825      *   BooleanUtils.toStringTrueFalse(false)  = "false"
826      * </pre>
827      *
828      * @param bool  the Boolean to check
829      * @return {@code 'true'}, {@code 'false'}, or {@code null}
830      */
831     public static String toStringTrueFalse(final boolean bool) {
832         return toString(bool, "true", "false");
833     }
834 
835     /**
836      * <p>Converts a boolean to a String returning {@code 'on'}
837      * or {@code 'off'}.</p>
838      *
839      * <pre>
840      *   BooleanUtils.toStringOnOff(true)   = "on"
841      *   BooleanUtils.toStringOnOff(false)  = "off"
842      * </pre>
843      *
844      * @param bool  the Boolean to check
845      * @return {@code 'on'}, {@code 'off'}, or {@code null}
846      */
847     public static String toStringOnOff(final boolean bool) {
848         return toString(bool, "on", "off");
849     }
850 
851     /**
852      * <p>Converts a boolean to a String returning {@code 'yes'}
853      * or {@code 'no'}.</p>
854      *
855      * <pre>
856      *   BooleanUtils.toStringYesNo(true)   = "yes"
857      *   BooleanUtils.toStringYesNo(false)  = "no"
858      * </pre>
859      *
860      * @param bool  the Boolean to check
861      * @return {@code 'yes'}, {@code 'no'}, or {@code null}
862      */
863     public static String toStringYesNo(final boolean bool) {
864         return toString(bool, "yes", "no");
865     }
866 
867     /**
868      * <p>Converts a boolean to a String returning one of the input Strings.</p>
869      *
870      * <pre>
871      *   BooleanUtils.toString(true, "true", "false")   = "true"
872      *   BooleanUtils.toString(false, "true", "false")  = "false"
873      * </pre>
874      *
875      * @param bool  the Boolean to check
876      * @param trueString  the String to return if {@code true}, may be {@code null}
877      * @param falseString  the String to return if {@code false}, may be {@code null}
878      * @return one of the two input Strings
879      */
880     public static String toString(final boolean bool, final String trueString, final String falseString) {
881         return bool ? trueString : falseString;
882     }
883 
884     // logical operations
885     // ----------------------------------------------------------------------
886     /**
887      * <p>Performs an and on a set of booleans.</p>
888      *
889      * <pre>
890      *   BooleanUtils.and(true, true)         = true
891      *   BooleanUtils.and(false, false)       = false
892      *   BooleanUtils.and(true, false)        = false
893      *   BooleanUtils.and(true, true, false)  = false
894      *   BooleanUtils.and(true, true, true)   = true
895      * </pre>
896      *
897      * @param array  an array of {@code boolean}s
898      * @return {@code true} if the and is successful.
899      * @throws IllegalArgumentException if {@code array} is {@code null}
900      * @throws IllegalArgumentException if {@code array} is empty.
901      * @since 3.0.1
902      */
903     public static boolean and(final boolean... array) {
904         // Validates input
905         if (array == null) {
906             throw new IllegalArgumentException("The Array must not be null");
907         }
908         if (array.length == 0) {
909             throw new IllegalArgumentException("Array is empty");
910         }
911         for (final boolean element : array) {
912             if (!element) {
913                 return false;
914             }
915         }
916         return true;
917     }
918 
919     /**
920      * <p>Performs an and on an array of Booleans.</p>
921      *
922      * <pre>
923      *   BooleanUtils.and(Boolean.TRUE, Boolean.TRUE)                 = Boolean.TRUE
924      *   BooleanUtils.and(Boolean.FALSE, Boolean.FALSE)               = Boolean.FALSE
925      *   BooleanUtils.and(Boolean.TRUE, Boolean.FALSE)                = Boolean.FALSE
926      *   BooleanUtils.and(Boolean.TRUE, Boolean.TRUE, Boolean.TRUE)   = Boolean.TRUE
927      *   BooleanUtils.and(Boolean.FALSE, Boolean.FALSE, Boolean.TRUE) = Boolean.FALSE
928      *   BooleanUtils.and(Boolean.TRUE, Boolean.FALSE, Boolean.TRUE)  = Boolean.FALSE
929      * </pre>
930      *
931      * @param array  an array of {@code Boolean}s
932      * @return {@code true} if the and is successful.
933      * @throws IllegalArgumentException if {@code array} is {@code null}
934      * @throws IllegalArgumentException if {@code array} is empty.
935      * @throws IllegalArgumentException if {@code array} contains a {@code null}
936      * @since 3.0.1
937      */
938     public static Boolean and(final Boolean... array) {
939         if (array == null) {
940             throw new IllegalArgumentException("The Array must not be null");
941         }
942         if (array.length == 0) {
943             throw new IllegalArgumentException("Array is empty");
944         }
945         try {
946             final boolean[] primitive = ArrayUtils.toPrimitive(array);
947             return and(primitive) ? Boolean.TRUE : Boolean.FALSE;
948         } catch (final NullPointerException ex) {
949             throw new IllegalArgumentException("The array must not contain any null elements");
950         }
951     }
952 
953     /**
954      * <p>Performs an or on a set of booleans.</p>
955      *
956      * <pre>
957      *   BooleanUtils.or(true, true)          = true
958      *   BooleanUtils.or(false, false)        = false
959      *   BooleanUtils.or(true, false)         = true
960      *   BooleanUtils.or(true, true, false)   = true
961      *   BooleanUtils.or(true, true, true)    = true
962      *   BooleanUtils.or(false, false, false) = false
963      * </pre>
964      *
965      * @param array  an array of {@code boolean}s
966      * @return {@code true} if the or is successful.
967      * @throws IllegalArgumentException if {@code array} is {@code null}
968      * @throws IllegalArgumentException if {@code array} is empty.
969      * @since 3.0.1
970      */
971     public static boolean or(final boolean... array) {
972         // Validates input
973         if (array == null) {
974             throw new IllegalArgumentException("The Array must not be null");
975         }
976         if (array.length == 0) {
977             throw new IllegalArgumentException("Array is empty");
978         }
979         for (final boolean element : array) {
980             if (element) {
981                 return true;
982             }
983         }
984         return false;
985     }
986 
987     /**
988      * <p>Performs an or on an array of Booleans.</p>
989      *
990      * <pre>
991      *   BooleanUtils.or(Boolean.TRUE, Boolean.TRUE)                  = Boolean.TRUE
992      *   BooleanUtils.or(Boolean.FALSE, Boolean.FALSE)                = Boolean.FALSE
993      *   BooleanUtils.or(Boolean.TRUE, Boolean.FALSE)                 = Boolean.TRUE
994      *   BooleanUtils.or(Boolean.TRUE, Boolean.TRUE, Boolean.TRUE)    = Boolean.TRUE
995      *   BooleanUtils.or(Boolean.FALSE, Boolean.FALSE, Boolean.TRUE)  = Boolean.TRUE
996      *   BooleanUtils.or(Boolean.TRUE, Boolean.FALSE, Boolean.TRUE)   = Boolean.TRUE
997      *   BooleanUtils.or(Boolean.FALSE, Boolean.FALSE, Boolean.FALSE) = Boolean.FALSE
998      * </pre>
999      *
1000      * @param array  an array of {@code Boolean}s
1001      * @return {@code true} if the or is successful.
1002      * @throws IllegalArgumentException if {@code array} is {@code null}
1003      * @throws IllegalArgumentException if {@code array} is empty.
1004      * @throws IllegalArgumentException if {@code array} contains a {@code null}
1005      * @since 3.0.1
1006      */
1007     public static Boolean or(final Boolean... array) {
1008         if (array == null) {
1009             throw new IllegalArgumentException("The Array must not be null");
1010         }
1011         if (array.length == 0) {
1012             throw new IllegalArgumentException("Array is empty");
1013         }
1014         try {
1015             final boolean[] primitive = ArrayUtils.toPrimitive(array);
1016             return or(primitive) ? Boolean.TRUE : Boolean.FALSE;
1017         } catch (final NullPointerException ex) {
1018             throw new IllegalArgumentException("The array must not contain any null elements");
1019         }
1020     }
1021 
1022     /**
1023      * <p>Performs an xor on a set of booleans.</p>
1024      *
1025      * <pre>
1026      *   BooleanUtils.xor(true, true)   = false
1027      *   BooleanUtils.xor(false, false) = false
1028      *   BooleanUtils.xor(true, false)  = true
1029      *   BooleanUtils.xor(true, true)   = false
1030      *   BooleanUtils.xor(false, false) = false
1031      *   BooleanUtils.xor(true, false)  = true
1032      * </pre>
1033      *
1034      * @param array  an array of {@code boolean}s
1035      * @return {@code true} if the xor is successful.
1036      * @throws IllegalArgumentException if {@code array} is {@code null}
1037      * @throws IllegalArgumentException if {@code array} is empty.
1038      */
1039     public static boolean xor(final boolean... array) {
1040         // Validates input
1041         if (array == null) {
1042             throw new IllegalArgumentException("The Array must not be null");
1043         }
1044         if (array.length == 0) {
1045             throw new IllegalArgumentException("Array is empty");
1046         }
1047 
1048         // false if the neutral element of the xor operator
1049         boolean result = false;
1050         for (final boolean element : array) {
1051             result ^= element;
1052         }
1053 
1054         return result;
1055     }
1056 
1057     /**
1058      * <p>Performs an xor on an array of Booleans.</p>
1059      *
1060      * <pre>
1061      *   BooleanUtils.xor(new Boolean[] { Boolean.TRUE, Boolean.TRUE })   = Boolean.FALSE
1062      *   BooleanUtils.xor(new Boolean[] { Boolean.FALSE, Boolean.FALSE }) = Boolean.FALSE
1063      *   BooleanUtils.xor(new Boolean[] { Boolean.TRUE, Boolean.FALSE })  = Boolean.TRUE
1064      * </pre>
1065      *
1066      * @param array  an array of {@code Boolean}s
1067      * @return {@code true} if the xor is successful.
1068      * @throws IllegalArgumentException if {@code array} is {@code null}
1069      * @throws IllegalArgumentException if {@code array} is empty.
1070      * @throws IllegalArgumentException if {@code array} contains a {@code null}
1071      */
1072     public static Boolean xor(final Boolean... array) {
1073         if (array == null) {
1074             throw new IllegalArgumentException("The Array must not be null");
1075         }
1076         if (array.length == 0) {
1077             throw new IllegalArgumentException("Array is empty");
1078         }
1079         try {
1080             final boolean[] primitive = ArrayUtils.toPrimitive(array);
1081             return xor(primitive) ? Boolean.TRUE : Boolean.FALSE;
1082         } catch (final NullPointerException ex) {
1083             throw new IllegalArgumentException("The array must not contain any null elements");
1084         }
1085     }
1086 
1087     /**
1088      * <p>Compares two {@code boolean} values. This is the same functionality as provided in Java 7.</p>
1089      *
1090      * @param x the first {@code boolean} to compare
1091      * @param y the second {@code boolean} to compare
1092      * @return the value {@code 0} if {@code x == y};
1093      *         a value less than {@code 0} if {@code !x && y}; and
1094      *         a value greater than {@code 0} if {@code x && !y}
1095      * @since 3.4
1096      */
1097     public static int compare(boolean x, boolean y) {
1098         if (x == y) {
1099             return 0;
1100         }
1101         if (x) {
1102             return 1;
1103         } else {
1104             return -1;
1105         }
1106     }
1107 
1108 }