BooleanUtils.java

  1. /*
  2.  * Licensed to the Apache Software Foundation (ASF) under one or more
  3.  * contributor license agreements.  See the NOTICE file distributed with
  4.  * this work for additional information regarding copyright ownership.
  5.  * The ASF licenses this file to You under the Apache License, Version 2.0
  6.  * (the "License"); you may not use this file except in compliance with
  7.  * the License.  You may obtain a copy of the License at
  8.  *
  9.  *      http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */
  17. package org.apache.commons.lang3;

  19. import java.util.Arrays;
  20. import java.util.Collections;
  21. import java.util.List;
  22. import java.util.function.Consumer;

  24. import org.apache.commons.lang3.math.NumberUtils;

  26. /**
  27.  * Operations on boolean primitives and Boolean objects.
  28.  *
  29.  * <p>This class tries to handle {@code null} input gracefully.
  30.  * An exception will not be thrown for a {@code null} input.
  31.  * Each method documents its behavior in more detail.</p>
  32.  *
  33.  * <p>#ThreadSafe#</p>
  34.  * @since 2.0
  35.  */
  36. public class BooleanUtils {

  38.     private static final List<Boolean> BOOLEAN_LIST = Collections.unmodifiableList(Arrays.asList(Boolean.FALSE, Boolean.TRUE));

  40.     /**
  41.      * The false String {@code "false"}.
  42.      *
  43.      * @since 3.12.0
  44.      */
  45.     public static final String FALSE = "false";

  47.     /**
  48.      * The no String {@code "no"}.
  49.      *
  50.      * @since 3.12.0
  51.      */
  52.     public static final String NO = "no";

  54.     /**
  55.      * The off String {@code "off"}.
  56.      *
  57.      * @since 3.12.0
  58.      */
  59.     public static final String OFF = "off";

  61.     /**
  62.      * The on String {@code "on"}.
  63.      *
  64.      * @since 3.12.0
  65.      */
  66.     public static final String ON = "on";

  68.     /**
  69.      * The true String {@code "true"}.
  70.      *
  71.      * @since 3.12.0
  72.      */
  73.     public static final String TRUE = "true";

  75.     /**
  76.      * The yes String {@code "yes"}.
  77.      *
  78.      * @since 3.12.0
  79.      */
  80.     public static final String YES = "yes";

  82.     /**
  83.      * Performs an 'and' operation on a set of booleans.
  84.      *
  85.      * <pre>
  86.      *   BooleanUtils.and(true, true)         = true
  87.      *   BooleanUtils.and(false, false)       = false
  88.      *   BooleanUtils.and(true, false)        = false
  89.      *   BooleanUtils.and(true, true, false)  = false
  90.      *   BooleanUtils.and(true, true, true)   = true
  91.      * </pre>
  92.      *
  93.      * @param array  an array of {@code boolean}s
  94.      * @return the result of the logical 'and' operation. That is {@code false}
  95.      * if any of the parameters is {@code false} and {@code true} otherwise.
  96.      * @throws NullPointerException if {@code array} is {@code null}
  97.      * @throws IllegalArgumentException if {@code array} is empty.
  98.      * @since 3.0.1
  99.      */
  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.      *   // N.B. 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.         // Optimisation 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.         }

  823.         return null;
  824.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.         }

  1183.         return result;
  1184.     }

  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.     }

  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.     }

  1224. }
Created with JaCoCo 0.8.12.202403310830