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