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