Source code

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