Source code
Description: source: package: org.apache.commons.lang3, class: BooleanUtils

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