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