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 1632874 2014-10-19 05:52:37Z djones $
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     *   BooleanUtils.toBooleanObject("true ") = null // trailing space (too long)
541     *   BooleanUtils.toBooleanObject("ono")   = null // does not match on or no
542     * </pre>
543     *
544     * @param str  the String to check; upper and lower case are treated as the same
545     * @return the Boolean value of the string, {@code null} if no match or {@code null} input
546     */
547    public static Boolean toBooleanObject(final String str) {
548        // Previously used equalsIgnoreCase, which was fast for interned 'true'.
549        // Non interned 'true' matched 15 times slower.
550        //
551        // Optimisation provides same performance as before for interned 'true'.
552        // Similar performance for null, 'false', and other strings not length 2/3/4.
553        // 'true'/'TRUE' match 4 times slower, 'tRUE'/'True' 7 times slower.
554        if (str == "true") {
555            return Boolean.TRUE;
556        }
557        if (str == null) {
558            return null;
559        }
560        switch (str.length()) {
561            case 1: {
562                final char ch0 = str.charAt(0);
563                if (ch0 == 'y' || ch0 == 'Y' ||
564                    ch0 == 't' || ch0 == 'T') {
565                    return Boolean.TRUE;
566                }
567                if (ch0 == 'n' || ch0 == 'N' ||
568                    ch0 == 'f' || ch0 == 'F') {
569                    return Boolean.FALSE;
570                }
571                break;
572            }
573            case 2: {
574                final char ch0 = str.charAt(0);
575                final char ch1 = str.charAt(1);
576                if ((ch0 == 'o' || ch0 == 'O') &&
577                    (ch1 == 'n' || ch1 == 'N') ) {
578                    return Boolean.TRUE;
579                }
580                if ((ch0 == 'n' || ch0 == 'N') &&
581                    (ch1 == 'o' || ch1 == 'O') ) {
582                    return Boolean.FALSE;
583                }
584                break;
585            }
586            case 3: {
587                final char ch0 = str.charAt(0);
588                final char ch1 = str.charAt(1);
589                final char ch2 = str.charAt(2);
590                if ((ch0 == 'y' || ch0 == 'Y') &&
591                    (ch1 == 'e' || ch1 == 'E') &&
592                    (ch2 == 's' || ch2 == 'S') ) {
593                    return Boolean.TRUE;
594                }
595                if ((ch0 == 'o' || ch0 == 'O') &&
596                    (ch1 == 'f' || ch1 == 'F') &&
597                    (ch2 == 'f' || ch2 == 'F') ) {
598                    return Boolean.FALSE;
599                }
600                break;
601            }
602            case 4: {
603                final char ch0 = str.charAt(0);
604                final char ch1 = str.charAt(1);
605                final char ch2 = str.charAt(2);
606                final char ch3 = str.charAt(3);
607                if ((ch0 == 't' || ch0 == 'T') &&
608                    (ch1 == 'r' || ch1 == 'R') &&
609                    (ch2 == 'u' || ch2 == 'U') &&
610                    (ch3 == 'e' || ch3 == 'E') ) {
611                    return Boolean.TRUE;
612                }
613                break;
614            }
615            case 5: {
616                final char ch0 = str.charAt(0);
617                final char ch1 = str.charAt(1);
618                final char ch2 = str.charAt(2);
619                final char ch3 = str.charAt(3);
620                final char ch4 = str.charAt(4);
621                if ((ch0 == 'f' || ch0 == 'F') &&
622                    (ch1 == 'a' || ch1 == 'A') &&
623                    (ch2 == 'l' || ch2 == 'L') &&
624                    (ch3 == 's' || ch3 == 'S') &&
625                    (ch4 == 'e' || ch4 == 'E') ) {
626                    return Boolean.FALSE;
627                }
628                break;
629            }
630        default:
631            break;
632        }
633
634        return null;
635    }
636
637    /**
638     * <p>Converts a String to a Boolean throwing an exception if no match.</p>
639     *
640     * <p>NOTE: This returns null and will throw a NullPointerException if autoboxed to a boolean. </p>
641     *
642     * <pre>
643     *   BooleanUtils.toBooleanObject("true", "true", "false", "null")  = Boolean.TRUE
644     *   BooleanUtils.toBooleanObject("false", "true", "false", "null") = Boolean.FALSE
645     *   BooleanUtils.toBooleanObject("null", "true", "false", "null")  = null
646     * </pre>
647     *
648     * @param str  the String to check
649     * @param trueString  the String to match for {@code true} (case sensitive), may be {@code null}
650     * @param falseString  the String to match for {@code false} (case sensitive), may be {@code null}
651     * @param nullString  the String to match for {@code null} (case sensitive), may be {@code null}
652     * @return the Boolean value of the string, {@code null} if either the String matches {@code nullString}
653     *  or if {@code null} input and {@code nullString} is {@code null}
654     * @throws IllegalArgumentException if the String doesn't match
655     */
656    public static Boolean toBooleanObject(final String str, final String trueString, final String falseString, final String nullString) {
657        if (str == null) {
658            if (trueString == null) {
659                return Boolean.TRUE;
660            }
661            if (falseString == null) {
662                return Boolean.FALSE;
663            }
664            if (nullString == null) {
665                return null;
666            }
667        } else if (str.equals(trueString)) {
668            return Boolean.TRUE;
669        } else if (str.equals(falseString)) {
670            return Boolean.FALSE;
671        } else if (str.equals(nullString)) {
672            return null;
673        }
674        // no match
675        throw new IllegalArgumentException("The String did not match any specified value");
676    }
677
678    // String to boolean methods
679    //-----------------------------------------------------------------------
680    /**
681     * <p>Converts a String to a boolean (optimised for performance).</p>
682     *
683     * <p>{@code 'true'}, {@code 'on'}, {@code 'y'}, {@code 't'} or {@code 'yes'}
684     * (case insensitive) will return {@code true}. Otherwise,
685     * {@code false} is returned.</p>
686     *
687     * <p>This method performs 4 times faster (JDK1.4) than
688     * {@code Boolean.valueOf(String)}. However, this method accepts
689     * 'on' and 'yes', 't', 'y' as true values.
690     *
691     * <pre>
692     *   BooleanUtils.toBoolean(null)    = false
693     *   BooleanUtils.toBoolean("true")  = true
694     *   BooleanUtils.toBoolean("TRUE")  = true
695     *   BooleanUtils.toBoolean("tRUe")  = true
696     *   BooleanUtils.toBoolean("on")    = true
697     *   BooleanUtils.toBoolean("yes")   = true
698     *   BooleanUtils.toBoolean("false") = false
699     *   BooleanUtils.toBoolean("x gti") = false
700     *   BooleanUtils.toBooleanObject("y") = true
701     *   BooleanUtils.toBooleanObject("n") = false
702     *   BooleanUtils.toBooleanObject("t") = true
703     *   BooleanUtils.toBooleanObject("f") = false 
704     * </pre>
705     *
706     * @param str  the String to check
707     * @return the boolean value of the string, {@code false} if no match or the String is null
708     */
709    public static boolean toBoolean(final String str) {
710        return toBooleanObject(str) == Boolean.TRUE;
711    }
712
713    /**
714     * <p>Converts a String to a Boolean throwing an exception if no match found.</p>
715     *
716     * <pre>
717     *   BooleanUtils.toBoolean("true", "true", "false")  = true
718     *   BooleanUtils.toBoolean("false", "true", "false") = false
719     * </pre>
720     *
721     * @param str  the String to check
722     * @param trueString  the String to match for {@code true} (case sensitive), may be {@code null}
723     * @param falseString  the String to match for {@code false} (case sensitive), may be {@code null}
724     * @return the boolean value of the string
725     * @throws IllegalArgumentException if the String doesn't match
726     */
727    public static boolean toBoolean(final String str, final String trueString, final String falseString) {
728        if (str == trueString) {
729            return true;
730        } else if (str == falseString) {
731            return false;
732        } else if (str != null) {
733            if (str.equals(trueString)) {
734                return true;
735            } else if (str.equals(falseString)) {
736                return false;
737            }
738        }
739        // no match
740        throw new IllegalArgumentException("The String did not match either specified value");
741    }
742
743    // Boolean to String methods
744    //-----------------------------------------------------------------------
745    /**
746     * <p>Converts a Boolean to a String returning {@code 'true'},
747     * {@code 'false'}, or {@code null}.</p>
748     *
749     * <pre>
750     *   BooleanUtils.toStringTrueFalse(Boolean.TRUE)  = "true"
751     *   BooleanUtils.toStringTrueFalse(Boolean.FALSE) = "false"
752     *   BooleanUtils.toStringTrueFalse(null)          = null;
753     * </pre>
754     *
755     * @param bool  the Boolean to check
756     * @return {@code 'true'}, {@code 'false'}, or {@code null}
757     */
758    public static String toStringTrueFalse(final Boolean bool) {
759        return toString(bool, "true", "false", null);
760    }
761
762    /**
763     * <p>Converts a Boolean to a String returning {@code 'on'},
764     * {@code 'off'}, or {@code null}.</p>
765     *
766     * <pre>
767     *   BooleanUtils.toStringOnOff(Boolean.TRUE)  = "on"
768     *   BooleanUtils.toStringOnOff(Boolean.FALSE) = "off"
769     *   BooleanUtils.toStringOnOff(null)          = null;
770     * </pre>
771     *
772     * @param bool  the Boolean to check
773     * @return {@code 'on'}, {@code 'off'}, or {@code null}
774     */
775    public static String toStringOnOff(final Boolean bool) {
776        return toString(bool, "on", "off", null);
777    }
778
779    /**
780     * <p>Converts a Boolean to a String returning {@code 'yes'},
781     * {@code 'no'}, or {@code null}.</p>
782     *
783     * <pre>
784     *   BooleanUtils.toStringYesNo(Boolean.TRUE)  = "yes"
785     *   BooleanUtils.toStringYesNo(Boolean.FALSE) = "no"
786     *   BooleanUtils.toStringYesNo(null)          = null;
787     * </pre>
788     *
789     * @param bool  the Boolean to check
790     * @return {@code 'yes'}, {@code 'no'}, or {@code null}
791     */
792    public static String toStringYesNo(final Boolean bool) {
793        return toString(bool, "yes", "no", null);
794    }
795
796    /**
797     * <p>Converts a Boolean to a String returning one of the input Strings.</p>
798     *
799     * <pre>
800     *   BooleanUtils.toString(Boolean.TRUE, "true", "false", null)   = "true"
801     *   BooleanUtils.toString(Boolean.FALSE, "true", "false", null)  = "false"
802     *   BooleanUtils.toString(null, "true", "false", null)           = null;
803     * </pre>
804     *
805     * @param bool  the Boolean to check
806     * @param trueString  the String to return if {@code true}, may be {@code null}
807     * @param falseString  the String to return if {@code false}, may be {@code null}
808     * @param nullString  the String to return if {@code null}, may be {@code null}
809     * @return one of the three input Strings
810     */
811    public static String toString(final Boolean bool, final String trueString, final String falseString, final String nullString) {
812        if (bool == null) {
813            return nullString;
814        }
815        return bool.booleanValue() ? trueString : falseString;
816    }
817
818    // boolean to String methods
819    //-----------------------------------------------------------------------
820    /**
821     * <p>Converts a boolean to a String returning {@code 'true'}
822     * or {@code 'false'}.</p>
823     *
824     * <pre>
825     *   BooleanUtils.toStringTrueFalse(true)   = "true"
826     *   BooleanUtils.toStringTrueFalse(false)  = "false"
827     * </pre>
828     *
829     * @param bool  the Boolean to check
830     * @return {@code 'true'}, {@code 'false'}, or {@code null}
831     */
832    public static String toStringTrueFalse(final boolean bool) {
833        return toString(bool, "true", "false");
834    }
835
836    /**
837     * <p>Converts a boolean to a String returning {@code 'on'}
838     * or {@code 'off'}.</p>
839     *
840     * <pre>
841     *   BooleanUtils.toStringOnOff(true)   = "on"
842     *   BooleanUtils.toStringOnOff(false)  = "off"
843     * </pre>
844     *
845     * @param bool  the Boolean to check
846     * @return {@code 'on'}, {@code 'off'}, or {@code null}
847     */
848    public static String toStringOnOff(final boolean bool) {
849        return toString(bool, "on", "off");
850    }
851
852    /**
853     * <p>Converts a boolean to a String returning {@code 'yes'}
854     * or {@code 'no'}.</p>
855     *
856     * <pre>
857     *   BooleanUtils.toStringYesNo(true)   = "yes"
858     *   BooleanUtils.toStringYesNo(false)  = "no"
859     * </pre>
860     *
861     * @param bool  the Boolean to check
862     * @return {@code 'yes'}, {@code 'no'}, or {@code null}
863     */
864    public static String toStringYesNo(final boolean bool) {
865        return toString(bool, "yes", "no");
866    }
867
868    /**
869     * <p>Converts a boolean to a String returning one of the input Strings.</p>
870     *
871     * <pre>
872     *   BooleanUtils.toString(true, "true", "false")   = "true"
873     *   BooleanUtils.toString(false, "true", "false")  = "false"
874     * </pre>
875     *
876     * @param bool  the Boolean to check
877     * @param trueString  the String to return if {@code true}, may be {@code null}
878     * @param falseString  the String to return if {@code false}, may be {@code null}
879     * @return one of the two input Strings
880     */
881    public static String toString(final boolean bool, final String trueString, final String falseString) {
882        return bool ? trueString : falseString;
883    }
884
885    // logical operations
886    // ----------------------------------------------------------------------
887    /**
888     * <p>Performs an and on a set of booleans.</p>
889     *
890     * <pre>
891     *   BooleanUtils.and(true, true)         = true
892     *   BooleanUtils.and(false, false)       = false
893     *   BooleanUtils.and(true, false)        = false
894     *   BooleanUtils.and(true, true, false)  = false
895     *   BooleanUtils.and(true, true, true)   = true
896     * </pre>
897     *
898     * @param array  an array of {@code boolean}s
899     * @return {@code true} if the and is successful.
900     * @throws IllegalArgumentException if {@code array} is {@code null}
901     * @throws IllegalArgumentException if {@code array} is empty.
902     * @since 3.0.1
903     */
904    public static boolean and(final boolean... array) {
905        // Validates input
906        if (array == null) {
907            throw new IllegalArgumentException("The Array must not be null");
908        }
909        if (array.length == 0) {
910            throw new IllegalArgumentException("Array is empty");
911        }
912        for (final boolean element : array) {
913            if (!element) {
914                return false;
915            }
916        }
917        return true;
918    }
919
920    /**
921     * <p>Performs an and on an array of Booleans.</p>
922     *
923     * <pre>
924     *   BooleanUtils.and(Boolean.TRUE, Boolean.TRUE)                 = Boolean.TRUE
925     *   BooleanUtils.and(Boolean.FALSE, Boolean.FALSE)               = Boolean.FALSE
926     *   BooleanUtils.and(Boolean.TRUE, Boolean.FALSE)                = Boolean.FALSE
927     *   BooleanUtils.and(Boolean.TRUE, Boolean.TRUE, Boolean.TRUE)   = Boolean.TRUE
928     *   BooleanUtils.and(Boolean.FALSE, Boolean.FALSE, Boolean.TRUE) = Boolean.FALSE
929     *   BooleanUtils.and(Boolean.TRUE, Boolean.FALSE, Boolean.TRUE)  = Boolean.FALSE
930     * </pre>
931     *
932     * @param array  an array of {@code Boolean}s
933     * @return {@code true} if the and is successful.
934     * @throws IllegalArgumentException if {@code array} is {@code null}
935     * @throws IllegalArgumentException if {@code array} is empty.
936     * @throws IllegalArgumentException if {@code array} contains a {@code null}
937     * @since 3.0.1
938     */
939    public static Boolean and(final Boolean... array) {
940        if (array == null) {
941            throw new IllegalArgumentException("The Array must not be null");
942        }
943        if (array.length == 0) {
944            throw new IllegalArgumentException("Array is empty");
945        }
946        try {
947            final boolean[] primitive = ArrayUtils.toPrimitive(array);
948            return and(primitive) ? Boolean.TRUE : Boolean.FALSE;
949        } catch (final NullPointerException ex) {
950            throw new IllegalArgumentException("The array must not contain any null elements");
951        }
952    }
953
954    /**
955     * <p>Performs an or on a set of booleans.</p>
956     *
957     * <pre>
958     *   BooleanUtils.or(true, true)          = true
959     *   BooleanUtils.or(false, false)        = false
960     *   BooleanUtils.or(true, false)         = true
961     *   BooleanUtils.or(true, true, false)   = true
962     *   BooleanUtils.or(true, true, true)    = true
963     *   BooleanUtils.or(false, false, false) = false
964     * </pre>
965     *
966     * @param array  an array of {@code boolean}s
967     * @return {@code true} if the or is successful.
968     * @throws IllegalArgumentException if {@code array} is {@code null}
969     * @throws IllegalArgumentException if {@code array} is empty.
970     * @since 3.0.1
971     */
972    public static boolean or(final boolean... array) {
973        // Validates input
974        if (array == null) {
975            throw new IllegalArgumentException("The Array must not be null");
976        }
977        if (array.length == 0) {
978            throw new IllegalArgumentException("Array is empty");
979        }
980        for (final boolean element : array) {
981            if (element) {
982                return true;
983            }
984        }
985        return false;
986    }
987
988    /**
989     * <p>Performs an or on an array of Booleans.</p>
990     *
991     * <pre>
992     *   BooleanUtils.or(Boolean.TRUE, Boolean.TRUE)                  = Boolean.TRUE
993     *   BooleanUtils.or(Boolean.FALSE, Boolean.FALSE)                = Boolean.FALSE
994     *   BooleanUtils.or(Boolean.TRUE, Boolean.FALSE)                 = Boolean.TRUE
995     *   BooleanUtils.or(Boolean.TRUE, Boolean.TRUE, Boolean.TRUE)    = Boolean.TRUE
996     *   BooleanUtils.or(Boolean.FALSE, Boolean.FALSE, Boolean.TRUE)  = Boolean.TRUE
997     *   BooleanUtils.or(Boolean.TRUE, Boolean.FALSE, Boolean.TRUE)   = Boolean.TRUE
998     *   BooleanUtils.or(Boolean.FALSE, Boolean.FALSE, Boolean.FALSE) = Boolean.FALSE
999     * </pre>
1000     *
1001     * @param array  an array of {@code Boolean}s
1002     * @return {@code true} if the or is successful.
1003     * @throws IllegalArgumentException if {@code array} is {@code null}
1004     * @throws IllegalArgumentException if {@code array} is empty.
1005     * @throws IllegalArgumentException if {@code array} contains a {@code null}
1006     * @since 3.0.1
1007     */
1008    public static Boolean or(final Boolean... array) {
1009        if (array == null) {
1010            throw new IllegalArgumentException("The Array must not be null");
1011        }
1012        if (array.length == 0) {
1013            throw new IllegalArgumentException("Array is empty");
1014        }
1015        try {
1016            final boolean[] primitive = ArrayUtils.toPrimitive(array);
1017            return or(primitive) ? Boolean.TRUE : Boolean.FALSE;
1018        } catch (final NullPointerException ex) {
1019            throw new IllegalArgumentException("The array must not contain any null elements");
1020        }
1021    }
1022
1023    /**
1024     * <p>Performs an xor on a set of booleans.</p>
1025     *
1026     * <pre>
1027     *   BooleanUtils.xor(true, true)   = false
1028     *   BooleanUtils.xor(false, false) = false
1029     *   BooleanUtils.xor(true, false)  = true
1030     *   BooleanUtils.xor(true, true)   = false
1031     *   BooleanUtils.xor(false, false) = false
1032     *   BooleanUtils.xor(true, false)  = true
1033     * </pre>
1034     *
1035     * @param array  an array of {@code boolean}s
1036     * @return {@code true} if the xor is successful.
1037     * @throws IllegalArgumentException if {@code array} is {@code null}
1038     * @throws IllegalArgumentException if {@code array} is empty.
1039     */
1040    public static boolean xor(final boolean... array) {
1041        // Validates input
1042        if (array == null) {
1043            throw new IllegalArgumentException("The Array must not be null");
1044        }
1045        if (array.length == 0) {
1046            throw new IllegalArgumentException("Array is empty");
1047        }
1048
1049        // false if the neutral element of the xor operator
1050        boolean result = false;
1051        for (final boolean element : array) {
1052            result ^= element;
1053        }
1054
1055        return result;
1056    }
1057
1058    /**
1059     * <p>Performs an xor on an array of Booleans.</p>
1060     *
1061     * <pre>
1062     *   BooleanUtils.xor(new Boolean[] { Boolean.TRUE, Boolean.TRUE })   = Boolean.FALSE
1063     *   BooleanUtils.xor(new Boolean[] { Boolean.FALSE, Boolean.FALSE }) = Boolean.FALSE
1064     *   BooleanUtils.xor(new Boolean[] { Boolean.TRUE, Boolean.FALSE })  = Boolean.TRUE
1065     * </pre>
1066     *
1067     * @param array  an array of {@code Boolean}s
1068     * @return {@code true} if the xor is successful.
1069     * @throws IllegalArgumentException if {@code array} is {@code null}
1070     * @throws IllegalArgumentException if {@code array} is empty.
1071     * @throws IllegalArgumentException if {@code array} contains a {@code null}
1072     */
1073    public static Boolean xor(final Boolean... array) {
1074        if (array == null) {
1075            throw new IllegalArgumentException("The Array must not be null");
1076        }
1077        if (array.length == 0) {
1078            throw new IllegalArgumentException("Array is empty");
1079        }
1080        try {
1081            final boolean[] primitive = ArrayUtils.toPrimitive(array);
1082            return xor(primitive) ? Boolean.TRUE : Boolean.FALSE;
1083        } catch (final NullPointerException ex) {
1084            throw new IllegalArgumentException("The array must not contain any null elements");
1085        }
1086    }
1087
1088    /**
1089     * <p>Compares two {@code boolean} values. This is the same functionality as provided in Java 7.</p>
1090     *
1091     * @param x the first {@code boolean} to compare
1092     * @param y the second {@code boolean} to compare
1093     * @return the value {@code 0} if {@code x == y};
1094     *         a value less than {@code 0} if {@code !x && y}; and
1095     *         a value greater than {@code 0} if {@code x && !y}
1096     * @since 3.4
1097     */
1098    public static int compare(boolean x, boolean y) {
1099        if (x == y) {
1100            return 0;
1101        }
1102        if (x) {
1103            return 1;
1104        } else {
1105            return -1;
1106        }
1107    }
1108
1109}