Package org.apache.commons.lang3

# Class BooleanUtils

java.lang.Object
org.apache.commons.lang3.BooleanUtils

public class BooleanUtils extends Object
Operations on boolean primitives and Boolean objects.

This class tries to handle `null` input gracefully. An exception will not be thrown for a `null` input. Each method documents its behavior in more detail.

#ThreadSafe#

Since:
  2.0

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `FALSE`
  The false String `"false"`.
  `static final String`
  `NO`
  The no String `"no"`.
  `static final String`
  `OFF`
  The off String `"off"`.
  `static final String`
  `ON`
  The on String `"on"`.
  `static final String`
  `TRUE`
  The true String `"true"`.
  `static final String`
  `YES`
  The yes String `"yes"`.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `BooleanUtils()`
  `BooleanUtils` instances should NOT be constructed in standard programming.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static boolean`
  `and(boolean... array)`
  Performs an 'and' operation on a set of booleans.
  `static Boolean`
  `and(Boolean... array)`
  Performs an 'and' operation on an array of Booleans.
  `static Boolean[]`
  `booleanValues()`
  Returns a new array of possible values (like an enum would).
  `static int`
  `compare(boolean x, boolean y)`
  Compares two `boolean` values.
  `static void`
  `forEach(Consumer<Boolean> action)`
  Performs the given action for each Boolean `values()`.
  `static boolean`
  `isFalse(Boolean bool)`
  Checks if a `Boolean` value is `false`, handling `null` by returning `false`.
  `static boolean`
  `isNotFalse(Boolean bool)`
  Checks if a `Boolean` value is not `false`, handling `null` by returning `true`.
  `static boolean`
  `isNotTrue(Boolean bool)`
  Checks if a `Boolean` value is not `true`, handling `null` by returning `true`.
  `static boolean`
  `isTrue(Boolean bool)`
  Checks if a `Boolean` value is `true`, handling `null` by returning `false`.
  `static Boolean`
  `negate(Boolean bool)`
  Negates the specified boolean.
  `static boolean`
  `oneHot(boolean... array)`
  Performs a one-hot on an array of booleans.
  `static Boolean`
  `oneHot(Boolean... array)`
  Performs a one-hot on an array of booleans.
  `static boolean`
  `or(boolean... array)`
  Performs an 'or' operation on a set of booleans.
  `static Boolean`
  `or(Boolean... array)`
  Performs an 'or' operation on an array of Booleans.
  `static boolean[]`
  `primitiveValues()`
  Returns a new array of possible values (like an enum would).
  `static boolean`
  `toBoolean(int value)`
  Converts an int to a boolean using the convention that `zero` is `false`, everything else is `true`.
  `static boolean`
  `toBoolean(int value, int trueValue, int falseValue)`
  Converts an int to a boolean specifying the conversion values.
  `static boolean`
  `toBoolean(Boolean bool)`
  Converts a Boolean to a boolean handling `null` by returning `false`.
  `static boolean`
  `toBoolean(Integer value, Integer trueValue, Integer falseValue)`
  Converts an Integer to a boolean specifying the conversion values.
  `static boolean`
  `toBoolean(String str)`
  Converts a String to a boolean (optimised for performance).
  `static boolean`
  `toBoolean(String str, String trueString, String falseString)`
  Converts a String to a Boolean throwing an exception if no match found.
  `static boolean`
  `toBooleanDefaultIfNull(Boolean bool, boolean valueIfNull)`
  Converts a Boolean to a boolean handling `null`.
  `static Boolean`
  `toBooleanObject(int value)`
  Converts an int to a Boolean using the convention that `zero` is `false`, everything else is `true`.
  `static Boolean`
  `toBooleanObject(int value, int trueValue, int falseValue, int nullValue)`
  Converts an int to a Boolean specifying the conversion values.
  `static Boolean`
  `toBooleanObject(Integer value)`
  Converts an Integer to a Boolean using the convention that `zero` is `false`, every other numeric value is `true`.
  `static Boolean`
  `toBooleanObject(Integer value, Integer trueValue, Integer falseValue, Integer nullValue)`
  Converts an Integer to a Boolean specifying the conversion values.
  `static Boolean`
  `toBooleanObject(String str)`
  Converts a String to a Boolean.
  `static Boolean`
  `toBooleanObject(String str, String trueString, String falseString, String nullString)`
  Converts a String to a Boolean throwing an exception if no match.
  `static int`
  `toInteger(boolean bool)`
  Converts a boolean to an int using the convention that `true` is `1` and `false` is `0`.
  `static int`
  `toInteger(boolean bool, int trueValue, int falseValue)`
  Converts a boolean to an int specifying the conversion values.
  `static int`
  `toInteger(Boolean bool, int trueValue, int falseValue, int nullValue)`
  Converts a Boolean to an int specifying the conversion values.
  `static Integer`
  `toIntegerObject(boolean bool)`
  Converts a boolean to an Integer using the convention that `true` is `1` and `false` is `0`.
  `static Integer`
  `toIntegerObject(boolean bool, Integer trueValue, Integer falseValue)`
  Converts a boolean to an Integer specifying the conversion values.
  `static Integer`
  `toIntegerObject(Boolean bool)`
  Converts a Boolean to a Integer using the convention that `zero` is `false`.
  `static Integer`
  `toIntegerObject(Boolean bool, Integer trueValue, Integer falseValue, Integer nullValue)`
  Converts a Boolean to an Integer specifying the conversion values.
  `static String`
  `toString(boolean bool, String trueString, String falseString)`
  Converts a boolean to a String returning one of the input Strings.
  `static String`
  `toString(Boolean bool, String trueString, String falseString, String nullString)`
  Converts a Boolean to a String returning one of the input Strings.
  `static String`
  `toStringOnOff(boolean bool)`
  Converts a boolean to a String returning `'on'` or `'off'`.
  `static String`
  `toStringOnOff(Boolean bool)`
  Converts a Boolean to a String returning `'on'`, `'off'`, or `null`.
  `static String`
  `toStringTrueFalse(boolean bool)`
  Converts a boolean to a String returning `'true'` or `'false'`.
  `static String`
  `toStringTrueFalse(Boolean bool)`
  Converts a Boolean to a String returning `'true'`, `'false'`, or `null`.
  `static String`
  `toStringYesNo(boolean bool)`
  Converts a boolean to a String returning `'yes'` or `'no'`.
  `static String`
  `toStringYesNo(Boolean bool)`
  Converts a Boolean to a String returning `'yes'`, `'no'`, or `null`.
  `static List<Boolean>`
  `values()`
  Returns an unmodifiable list of Booleans `[false, true]`.
  `static boolean`
  `xor(boolean... array)`
  Performs an xor on a set of booleans.
  `static Boolean`
  `xor(Boolean... array)`
  Performs an xor on an array of Booleans.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### FALSE

    public static final String FALSE
    The false String `"false"`.
    Since:
      3.12.0
    See Also:
      - Constant Field Values

  - ### NO

    public static final String NO
    The no String `"no"`.
    Since:
      3.12.0
    See Also:
      - Constant Field Values

  - ### OFF

    public static final String OFF
    The off String `"off"`.
    Since:
      3.12.0
    See Also:
      - Constant Field Values

  - ### ON

    public static final String ON
    The on String `"on"`.
    Since:
      3.12.0
    See Also:
      - Constant Field Values

  - ### TRUE

    public static final String TRUE
    The true String `"true"`.
    Since:
      3.12.0
    See Also:
      - Constant Field Values

  - ### YES

    public static final String YES
    The yes String `"yes"`.
    Since:
      3.12.0
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### BooleanUtils

    public BooleanUtils()
    `BooleanUtils` instances should NOT be constructed in standard programming. Instead, the class should be used as `BooleanUtils.negate(true);`.

    This constructor is public to permit tools that require a JavaBean instance to operate.

- ## Method Details

  - ### and

    public static boolean and(boolean... array)
    Performs an 'and' operation on a set of booleans.

           BooleanUtils.and(true, true)         = true
           BooleanUtils.and(false, false)       = false
           BooleanUtils.and(true, false)        = false
           BooleanUtils.and(true, true, false)  = false
           BooleanUtils.and(true, true, true)   = true

    Parameters:
      `array` - an array of `boolean`s
    Returns:
      the result of the logical 'and' operation. That is `false` if any of the parameters is `false` and `true` otherwise.
    Throws:
      `NullPointerException` - if `array` is `null`
      `IllegalArgumentException` - if `array` is empty.
    Since:
      3.0.1

  - ### and

    public static Boolean and(Boolean... array)
    Performs an 'and' operation on an array of Booleans.

           BooleanUtils.and(Boolean.TRUE, Boolean.TRUE)                 = Boolean.TRUE
           BooleanUtils.and(Boolean.FALSE, Boolean.FALSE)               = Boolean.FALSE
           BooleanUtils.and(Boolean.TRUE, Boolean.FALSE)                = Boolean.FALSE
           BooleanUtils.and(Boolean.TRUE, Boolean.TRUE, Boolean.TRUE)   = Boolean.TRUE
           BooleanUtils.and(Boolean.FALSE, Boolean.FALSE, Boolean.TRUE) = Boolean.FALSE
           BooleanUtils.and(Boolean.TRUE, Boolean.FALSE, Boolean.TRUE)  = Boolean.FALSE
           BooleanUtils.and(null, null)                                 = Boolean.FALSE

    Null array elements map to false, like `Boolean.parseBoolean(null)` and its callers return false.

    Parameters:
      `array` - an array of `Boolean`s
    Returns:
      the result of the logical 'and' operation. That is `false` if any of the parameters is `false` and `true` otherwise.
    Throws:
      `NullPointerException` - if `array` is `null`
      `IllegalArgumentException` - if `array` is empty.
    Since:
      3.0.1

  - ### booleanValues

    public static Boolean[] booleanValues()
    Returns a new array of possible values (like an enum would).
    Returns:
      a new array of possible values (like an enum would).
    Since:
      3.12.0

  - ### compare

    public static int compare(boolean x, boolean y)
    Compares two `boolean` values. This is the same functionality as provided in Java 7.
    Parameters:
      `x` - the first `boolean` to compare
      `y` - the second `boolean` to compare
    Returns:
      the value `0` if `x == y`; a value less than `0` if `!x && y`; and a value greater than `0` if `x && !y`
    Since:
      3.4

  - ### forEach

    public static void forEach(Consumer<Boolean> action)
    Performs the given action for each Boolean `values()`.
    Parameters:
      `action` - The action to be performed for each element
    Since:
      3.13.0

  - ### isFalse

    public static boolean isFalse(Boolean bool)
    Checks if a `Boolean` value is `false`, handling `null` by returning `false`.

           BooleanUtils.isFalse(Boolean.TRUE)  = false
           BooleanUtils.isFalse(Boolean.FALSE) = true
           BooleanUtils.isFalse(null)          = false

    Parameters:
      `bool` - the boolean to check, null returns `false`
    Returns:
      `true` only if the input is non-`null` and `false`
    Since:
      2.1

  - ### isNotFalse

    public static boolean isNotFalse(Boolean bool)
    Checks if a `Boolean` value is not `false`, handling `null` by returning `true`.

           BooleanUtils.isNotFalse(Boolean.TRUE)  = true
           BooleanUtils.isNotFalse(Boolean.FALSE) = false
           BooleanUtils.isNotFalse(null)          = true

    Parameters:
      `bool` - the boolean to check, null returns `true`
    Returns:
      `true` if the input is `null` or `true`
    Since:
      2.3

  - ### isNotTrue

    public static boolean isNotTrue(Boolean bool)
    Checks if a `Boolean` value is not `true`, handling `null` by returning `true`.

           BooleanUtils.isNotTrue(Boolean.TRUE)  = false
           BooleanUtils.isNotTrue(Boolean.FALSE) = true
           BooleanUtils.isNotTrue(null)          = true

    Parameters:
      `bool` - the boolean to check, null returns `true`
    Returns:
      `true` if the input is null or false
    Since:
      2.3

  - ### isTrue

    public static boolean isTrue(Boolean bool)
    Checks if a `Boolean` value is `true`, handling `null` by returning `false`.

           BooleanUtils.isTrue(Boolean.TRUE)  = true
           BooleanUtils.isTrue(Boolean.FALSE) = false
           BooleanUtils.isTrue(null)          = false

    Parameters:
      `bool` - the boolean to check, `null` returns `false`
    Returns:
      `true` only if the input is non-null and true
    Since:
      2.1

  - ### negate

    public static Boolean negate(Boolean bool)
    Negates the specified boolean.

    If `null` is passed in, `null` will be returned.

    NOTE: This returns `null` and will throw a `NullPointerException` if unboxed to a boolean.

           BooleanUtils.negate(Boolean.TRUE)  = Boolean.FALSE;
           BooleanUtils.negate(Boolean.FALSE) = Boolean.TRUE;
           BooleanUtils.negate(null)          = null;

    Parameters:
      `bool` - the Boolean to negate, may be null
    Returns:
      the negated Boolean, or `null` if `null` input

  - ### oneHot

    public static boolean oneHot(boolean... array)
    Performs a one-hot on an array of booleans.

    This implementation returns true if one, and only one, of the supplied values is true.

    See also One-hot.

    Parameters:
      `array` - an array of `boolean`s
    Returns:
      the result of the one-hot operations
    Throws:
      `NullPointerException` - if `array` is `null`
      `IllegalArgumentException` - if `array` is empty.

  - ### oneHot

    public static Boolean oneHot(Boolean... array)
    Performs a one-hot on an array of booleans.

    This implementation returns true if one, and only one, of the supplied values is true.

    Null array elements map to false, like `Boolean.parseBoolean(null)` and its callers return false.

    See also One-hot.

    Parameters:
      `array` - an array of `boolean`s
    Returns:
      the result of the one-hot operations
    Throws:
      `NullPointerException` - if `array` is `null`
      `IllegalArgumentException` - if `array` is empty.

  - ### or

    public static boolean or(boolean... array)
    Performs an 'or' operation on a set of booleans.

           BooleanUtils.or(true, true)          = true
           BooleanUtils.or(false, false)        = false
           BooleanUtils.or(true, false)         = true
           BooleanUtils.or(true, true, false)   = true
           BooleanUtils.or(true, true, true)    = true
           BooleanUtils.or(false, false, false) = false

    Parameters:
      `array` - an array of `boolean`s
    Returns:
      `true` if any of the arguments is `true`, and it returns `false` otherwise.
    Throws:
      `NullPointerException` - if `array` is `null`
      `IllegalArgumentException` - if `array` is empty.
    Since:
      3.0.1

  - ### or

    public static Boolean or(Boolean... array)
    Performs an 'or' operation on an array of Booleans.

           BooleanUtils.or(Boolean.TRUE, Boolean.TRUE)                  = Boolean.TRUE
           BooleanUtils.or(Boolean.FALSE, Boolean.FALSE)                = Boolean.FALSE
           BooleanUtils.or(Boolean.TRUE, Boolean.FALSE)                 = Boolean.TRUE
           BooleanUtils.or(Boolean.TRUE, Boolean.TRUE, Boolean.TRUE)    = Boolean.TRUE
           BooleanUtils.or(Boolean.FALSE, Boolean.FALSE, Boolean.TRUE)  = Boolean.TRUE
           BooleanUtils.or(Boolean.TRUE, Boolean.FALSE, Boolean.TRUE)   = Boolean.TRUE
           BooleanUtils.or(Boolean.FALSE, Boolean.FALSE, Boolean.FALSE) = Boolean.FALSE
           BooleanUtils.or(Boolean.TRUE, null)                          = Boolean.TRUE
           BooleanUtils.or(Boolean.FALSE, null)                         = Boolean.FALSE

    Null array elements map to false, like `Boolean.parseBoolean(null)` and its callers return false.

    Parameters:
      `array` - an array of `Boolean`s
    Returns:
      `true` if any of the arguments is `true`, and it returns `false` otherwise.
    Throws:
      `NullPointerException` - if `array` is `null`
      `IllegalArgumentException` - if `array` is empty.
    Since:
      3.0.1

  - ### primitiveValues

    public static boolean[] primitiveValues()
    Returns a new array of possible values (like an enum would).
    Returns:
      a new array of possible values (like an enum would).
    Since:
      3.12.0

  - ### toBoolean

    public static boolean toBoolean(Boolean bool)
    Converts a Boolean to a boolean handling `null` by returning `false`.

           BooleanUtils.toBoolean(Boolean.TRUE)  = true
           BooleanUtils.toBoolean(Boolean.FALSE) = false
           BooleanUtils.toBoolean(null)          = false

    Parameters:
      `bool` - the boolean to convert
    Returns:
      `true` or `false`, `null` returns `false`

  - ### toBoolean

    public static boolean toBoolean(int value)
    Converts an int to a boolean using the convention that `zero` is `false`, everything else is `true`.

           BooleanUtils.toBoolean(0) = false
           BooleanUtils.toBoolean(1) = true
           BooleanUtils.toBoolean(2) = true

    Parameters:
      `value` - the int to convert
    Returns:
      `true` if non-zero, `false` if zero

  - ### toBoolean

    public static boolean toBoolean(int value, int trueValue, int falseValue)
    Converts an int to a boolean specifying the conversion values.

    If the `trueValue` and `falseValue` are the same number then the return value will be `true` in case `value` matches it.

           BooleanUtils.toBoolean(0, 1, 0) = false
           BooleanUtils.toBoolean(1, 1, 0) = true
           BooleanUtils.toBoolean(1, 1, 1) = true
           BooleanUtils.toBoolean(2, 1, 2) = false
           BooleanUtils.toBoolean(2, 2, 0) = true

    Parameters:
      `value` - the `Integer` to convert
      `trueValue` - the value to match for `true`
      `falseValue` - the value to match for `false`
    Returns:
      `true` or `false`
    Throws:
      `IllegalArgumentException` - if `value` does not match neither `trueValue` no `falseValue`

  - ### toBoolean

    public static boolean toBoolean(Integer value, Integer trueValue, Integer falseValue)
    Converts an Integer to a boolean specifying the conversion values.

           BooleanUtils.toBoolean(Integer.valueOf(0), Integer.valueOf(1), Integer.valueOf(0)) = false
           BooleanUtils.toBoolean(Integer.valueOf(1), Integer.valueOf(1), Integer.valueOf(0)) = true
           BooleanUtils.toBoolean(Integer.valueOf(2), Integer.valueOf(1), Integer.valueOf(2)) = false
           BooleanUtils.toBoolean(Integer.valueOf(2), Integer.valueOf(2), Integer.valueOf(0)) = true
           BooleanUtils.toBoolean(null, null, Integer.valueOf(0))                     = true

    Parameters:
      `value` - the Integer to convert
      `trueValue` - the value to match for `true`, may be `null`
      `falseValue` - the value to match for `false`, may be `null`
    Returns:
      `true` or `false`
    Throws:
      `IllegalArgumentException` - if no match

  - ### toBoolean

    public static boolean toBoolean(String str)
    Converts a String to a boolean (optimised for performance).

    `'true'`, `'on'`, `'y'`, `'t'` or `'yes'` (case insensitive) will return `true`. Otherwise, `false` is returned.

    This method performs 4 times faster (JDK1.4) than `Boolean.valueOf(String)`. However, this method accepts 'on' and 'yes', 't', 'y' as true values.

           BooleanUtils.toBoolean(null)    = false
           BooleanUtils.toBoolean("true")  = true
           BooleanUtils.toBoolean("TRUE")  = true
           BooleanUtils.toBoolean("tRUe")  = true
           BooleanUtils.toBoolean("on")    = true
           BooleanUtils.toBoolean("yes")   = true
           BooleanUtils.toBoolean("false") = false
           BooleanUtils.toBoolean("x gti") = false
           BooleanUtils.toBoolean("y") = true
           BooleanUtils.toBoolean("n") = false
           BooleanUtils.toBoolean("t") = true
           BooleanUtils.toBoolean("f") = false

    Parameters:
      `str` - the String to check
    Returns:
      the boolean value of the string, `false` if no match or the String is null

  - ### toBoolean

    public static boolean toBoolean(String str, String trueString, String falseString)
    Converts a String to a Boolean throwing an exception if no match found.

           BooleanUtils.toBoolean("true", "true", "false")  = true
           BooleanUtils.toBoolean("false", "true", "false") = false

    Parameters:
      `str` - the String to check
      `trueString` - the String to match for `true` (case-sensitive), may be `null`
      `falseString` - the String to match for `false` (case-sensitive), may be `null`
    Returns:
      the boolean value of the string
    Throws:
      `IllegalArgumentException` - if the String doesn't match

  - ### toBooleanDefaultIfNull

    public static boolean toBooleanDefaultIfNull(Boolean bool, boolean valueIfNull)
    Converts a Boolean to a boolean handling `null`.

           BooleanUtils.toBooleanDefaultIfNull(Boolean.TRUE, false)  = true
           BooleanUtils.toBooleanDefaultIfNull(Boolean.TRUE, true)   = true
           BooleanUtils.toBooleanDefaultIfNull(Boolean.FALSE, true)  = false
           BooleanUtils.toBooleanDefaultIfNull(Boolean.FALSE, false) = false
           BooleanUtils.toBooleanDefaultIfNull(null, true)           = true
           BooleanUtils.toBooleanDefaultIfNull(null, false)          = false

    Parameters:
      `bool` - the boolean object to convert to primitive
      `valueIfNull` - the boolean value to return if the parameter `bool` is `null`
    Returns:
      `true` or `false`

  - ### toBooleanObject

    public static Boolean toBooleanObject(int value)
    Converts an int to a Boolean using the convention that `zero` is `false`, everything else is `true`.

           BooleanUtils.toBoolean(0) = Boolean.FALSE
           BooleanUtils.toBoolean(1) = Boolean.TRUE
           BooleanUtils.toBoolean(2) = Boolean.TRUE

    Parameters:
      `value` - the int to convert
    Returns:
      Boolean.TRUE if non-zero, Boolean.FALSE if zero, `null` if `null`

  - ### toBooleanObject

    public static Boolean toBooleanObject(int value, int trueValue, int falseValue, int nullValue)
    Converts an int to a Boolean specifying the conversion values.

    NOTE: This method may return `null` and may throw a `NullPointerException` if unboxed to a `boolean`.

    The checks are done first for the `trueValue`, then for the `falseValue` and finally for the `nullValue`.

           BooleanUtils.toBooleanObject(0, 0, 2, 3) = Boolean.TRUE
           BooleanUtils.toBooleanObject(0, 0, 0, 3) = Boolean.TRUE
           BooleanUtils.toBooleanObject(0, 0, 0, 0) = Boolean.TRUE
           BooleanUtils.toBooleanObject(2, 1, 2, 3) = Boolean.FALSE
           BooleanUtils.toBooleanObject(2, 1, 2, 2) = Boolean.FALSE
           BooleanUtils.toBooleanObject(3, 1, 2, 3) = null

    Parameters:
      `value` - the Integer to convert
      `trueValue` - the value to match for `true`
      `falseValue` - the value to match for `false`
      `nullValue` - the value to match for `null`
    Returns:
      Boolean.TRUE, Boolean.FALSE, or `null`
    Throws:
      `IllegalArgumentException` - if no match

  - ### toBooleanObject

    public static Boolean toBooleanObject(Integer value)
    Converts an Integer to a Boolean using the convention that `zero` is `false`, every other numeric value is `true`.

    `null` will be converted to `null`.

    NOTE: This method may return `null` and may throw a `NullPointerException` if unboxed to a `boolean`.

           BooleanUtils.toBooleanObject(Integer.valueOf(0))    = Boolean.FALSE
           BooleanUtils.toBooleanObject(Integer.valueOf(1))    = Boolean.TRUE
           BooleanUtils.toBooleanObject(Integer.valueOf(null)) = null

    Parameters:
      `value` - the Integer to convert
    Returns:
      Boolean.TRUE if non-zero, Boolean.FALSE if zero, `null` if `null` input

  - ### toBooleanObject

    public static Boolean toBooleanObject(Integer value, Integer trueValue, Integer falseValue, Integer nullValue)
    Converts an Integer to a Boolean specifying the conversion values.

    NOTE: This method may return `null` and may throw a `NullPointerException` if unboxed to a `boolean`.

    The checks are done first for the `trueValue`, then for the `falseValue` and finally for the `nullValue`.

           BooleanUtils.toBooleanObject(Integer.valueOf(0), Integer.valueOf(0), Integer.valueOf(2), Integer.valueOf(3)) = Boolean.TRUE
           BooleanUtils.toBooleanObject(Integer.valueOf(0), Integer.valueOf(0), Integer.valueOf(0), Integer.valueOf(3)) = Boolean.TRUE
           BooleanUtils.toBooleanObject(Integer.valueOf(0), Integer.valueOf(0), Integer.valueOf(0), Integer.valueOf(0)) = Boolean.TRUE
           BooleanUtils.toBooleanObject(Integer.valueOf(2), Integer.valueOf(1), Integer.valueOf(2), Integer.valueOf(3)) = Boolean.FALSE
           BooleanUtils.toBooleanObject(Integer.valueOf(2), Integer.valueOf(1), Integer.valueOf(2), Integer.valueOf(2)) = Boolean.FALSE
           BooleanUtils.toBooleanObject(Integer.valueOf(3), Integer.valueOf(1), Integer.valueOf(2), Integer.valueOf(3)) = null

    Parameters:
      `value` - the Integer to convert
      `trueValue` - the value to match for `true`, may be `null`
      `falseValue` - the value to match for `false`, may be `null`
      `nullValue` - the value to match for `null`, may be `null`
    Returns:
      Boolean.TRUE, Boolean.FALSE, or `null`
    Throws:
      `IllegalArgumentException` - if no match

  - ### toBooleanObject

    public static Boolean toBooleanObject(String str)
    Converts a String to a Boolean.

    `'true'`, `'on'`, `'y'`, `'t'`, `'yes'` or `'1'` (case insensitive) will return `true`. `'false'`, `'off'`, `'n'`, `'f'`, `'no'` or `'0'` (case insensitive) will return `false`. Otherwise, `null` is returned.

    NOTE: This method may return `null` and may throw a `NullPointerException` if unboxed to a `boolean`.

           // N.B. case is not significant
           BooleanUtils.toBooleanObject(null)    = null
           BooleanUtils.toBooleanObject("true")  = Boolean.TRUE
           BooleanUtils.toBooleanObject("T")     = Boolean.TRUE // i.e. T[RUE]
           BooleanUtils.toBooleanObject("false") = Boolean.FALSE
           BooleanUtils.toBooleanObject("f")     = Boolean.FALSE // i.e. f[alse]
           BooleanUtils.toBooleanObject("No")    = Boolean.FALSE
           BooleanUtils.toBooleanObject("n")     = Boolean.FALSE // i.e. n[o]
           BooleanUtils.toBooleanObject("on")    = Boolean.TRUE
           BooleanUtils.toBooleanObject("ON")    = Boolean.TRUE
           BooleanUtils.toBooleanObject("off")   = Boolean.FALSE
           BooleanUtils.toBooleanObject("oFf")   = Boolean.FALSE
           BooleanUtils.toBooleanObject("yes")   = Boolean.TRUE
           BooleanUtils.toBooleanObject("Y")     = Boolean.TRUE // i.e. Y[ES]
           BooleanUtils.toBooleanObject("1")     = Boolean.TRUE
           BooleanUtils.toBooleanObject("0")     = Boolean.FALSE
           BooleanUtils.toBooleanObject("blue")  = null
           BooleanUtils.toBooleanObject("true ") = null // trailing space (too long)
           BooleanUtils.toBooleanObject("ono")   = null // does not match on or no

    Parameters:
      `str` - the String to check; upper and lower case are treated as the same
    Returns:
      the Boolean value of the string, `null` if no match or `null` input

  - ### toBooleanObject

    public static Boolean toBooleanObject(String str, String trueString, String falseString, String nullString)
    Converts a String to a Boolean throwing an exception if no match.

    NOTE: This method may return `null` and may throw a `NullPointerException` if unboxed to a `boolean`.

           BooleanUtils.toBooleanObject("true", "true", "false", "null")   = Boolean.TRUE
           BooleanUtils.toBooleanObject(null, null, "false", "null")       = Boolean.TRUE
           BooleanUtils.toBooleanObject(null, null, null, "null")          = Boolean.TRUE
           BooleanUtils.toBooleanObject(null, null, null, null)            = Boolean.TRUE
           BooleanUtils.toBooleanObject("false", "true", "false", "null")  = Boolean.FALSE
           BooleanUtils.toBooleanObject("false", "true", "false", "false") = Boolean.FALSE
           BooleanUtils.toBooleanObject(null, "true", null, "false")       = Boolean.FALSE
           BooleanUtils.toBooleanObject(null, "true", null, null)          = Boolean.FALSE
           BooleanUtils.toBooleanObject("null", "true", "false", "null")   = null

    Parameters:
      `str` - the String to check
      `trueString` - the String to match for `true` (case-sensitive), may be `null`
      `falseString` - the String to match for `false` (case-sensitive), may be `null`
      `nullString` - the String to match for `null` (case-sensitive), may be `null`
    Returns:
      the Boolean value of the string, `null` if either the String matches `nullString` or if `null` input and `nullString` is `null`
    Throws:
      `IllegalArgumentException` - if the String doesn't match

  - ### toInteger

    public static int toInteger(boolean bool)
    Converts a boolean to an int using the convention that `true` is `1` and `false` is `0`.

           BooleanUtils.toInteger(true)  = 1
           BooleanUtils.toInteger(false) = 0

    Parameters:
      `bool` - the boolean to convert
    Returns:
      one if `true`, zero if `false`

  - ### toInteger

    public static int toInteger(boolean bool, int trueValue, int falseValue)
    Converts a boolean to an int specifying the conversion values.

           BooleanUtils.toInteger(true, 1, 0)  = 1
           BooleanUtils.toInteger(false, 1, 0) = 0

    Parameters:
      `bool` - the to convert
      `trueValue` - the value to return if `true`
      `falseValue` - the value to return if `false`
    Returns:
      the appropriate value

  - ### toInteger

    public static int toInteger(Boolean bool, int trueValue, int falseValue, int nullValue)
    Converts a Boolean to an int specifying the conversion values.

           BooleanUtils.toInteger(Boolean.TRUE, 1, 0, 2)  = 1
           BooleanUtils.toInteger(Boolean.FALSE, 1, 0, 2) = 0
           BooleanUtils.toInteger(null, 1, 0, 2)          = 2

    Parameters:
      `bool` - the Boolean to convert
      `trueValue` - the value to return if `true`
      `falseValue` - the value to return if `false`
      `nullValue` - the value to return if `null`
    Returns:
      the appropriate value

  - ### toIntegerObject

    public static Integer toIntegerObject(boolean bool)
    Converts a boolean to an Integer using the convention that `true` is `1` and `false` is `0`.

           BooleanUtils.toIntegerObject(true)  = Integer.valueOf(1)
           BooleanUtils.toIntegerObject(false) = Integer.valueOf(0)

    Parameters:
      `bool` - the boolean to convert
    Returns:
      one if `true`, zero if `false`

  - ### toIntegerObject

    public static Integer toIntegerObject(boolean bool, Integer trueValue, Integer falseValue)
    Converts a boolean to an Integer specifying the conversion values.

           BooleanUtils.toIntegerObject(true, Integer.valueOf(1), Integer.valueOf(0))  = Integer.valueOf(1)
           BooleanUtils.toIntegerObject(false, Integer.valueOf(1), Integer.valueOf(0)) = Integer.valueOf(0)

    Parameters:
      `bool` - the to convert
      `trueValue` - the value to return if `true`, may be `null`
      `falseValue` - the value to return if `false`, may be `null`
    Returns:
      the appropriate value

  - ### toIntegerObject

    public static Integer toIntegerObject(Boolean bool)
    Converts a Boolean to a Integer using the convention that `zero` is `false`.

    `null` will be converted to `null`.

           BooleanUtils.toIntegerObject(Boolean.TRUE)  = Integer.valueOf(1)
           BooleanUtils.toIntegerObject(Boolean.FALSE) = Integer.valueOf(0)

    Parameters:
      `bool` - the Boolean to convert
    Returns:
      one if Boolean.TRUE, zero if Boolean.FALSE, `null` if `null`

  - ### toIntegerObject

    public static Integer toIntegerObject(Boolean bool, Integer trueValue, Integer falseValue, Integer nullValue)
    Converts a Boolean to an Integer specifying the conversion values.

           BooleanUtils.toIntegerObject(Boolean.TRUE, Integer.valueOf(1), Integer.valueOf(0), Integer.valueOf(2))  = Integer.valueOf(1)
           BooleanUtils.toIntegerObject(Boolean.FALSE, Integer.valueOf(1), Integer.valueOf(0), Integer.valueOf(2)) = Integer.valueOf(0)
           BooleanUtils.toIntegerObject(null, Integer.valueOf(1), Integer.valueOf(0), Integer.valueOf(2))          = Integer.valueOf(2)

    Parameters:
      `bool` - the Boolean to convert
      `trueValue` - the value to return if `true`, may be `null`
      `falseValue` - the value to return if `false`, may be `null`
      `nullValue` - the value to return if `null`, may be `null`
    Returns:
      the appropriate value

  - ### toString

    public static String toString(boolean bool, String trueString, String falseString)
    Converts a boolean to a String returning one of the input Strings.

           BooleanUtils.toString(true, "true", "false")   = "true"
           BooleanUtils.toString(false, "true", "false")  = "false"

    Parameters:
      `bool` - the Boolean to check
      `trueString` - the String to return if `true`, may be `null`
      `falseString` - the String to return if `false`, may be `null`
    Returns:
      one of the two input Strings

  - ### toString

    public static String toString(Boolean bool, String trueString, String falseString, String nullString)
    Converts a Boolean to a String returning one of the input Strings.

           BooleanUtils.toString(Boolean.TRUE, "true", "false", null)   = "true"
           BooleanUtils.toString(Boolean.FALSE, "true", "false", null)  = "false"
           BooleanUtils.toString(null, "true", "false", null)           = null;

    Parameters:
      `bool` - the Boolean to check
      `trueString` - the String to return if `true`, may be `null`
      `falseString` - the String to return if `false`, may be `null`
      `nullString` - the String to return if `null`, may be `null`
    Returns:
      one of the three input Strings

  - ### toStringOnOff

    public static String toStringOnOff(boolean bool)
    Converts a boolean to a String returning `'on'` or `'off'`.

           BooleanUtils.toStringOnOff(true)   = "on"
           BooleanUtils.toStringOnOff(false)  = "off"

    Parameters:
      `bool` - the Boolean to check
    Returns:
      `'on'`, `'off'`, or `null`

  - ### toStringOnOff

    public static String toStringOnOff(Boolean bool)
    Converts a Boolean to a String returning `'on'`, `'off'`, or `null`.

           BooleanUtils.toStringOnOff(Boolean.TRUE)  = "on"
           BooleanUtils.toStringOnOff(Boolean.FALSE) = "off"
           BooleanUtils.toStringOnOff(null)          = null;

    Parameters:
      `bool` - the Boolean to check
    Returns:
      `'on'`, `'off'`, or `null`

  - ### toStringTrueFalse

    public static String toStringTrueFalse(boolean bool)
    Converts a boolean to a String returning `'true'` or `'false'`.

           BooleanUtils.toStringTrueFalse(true)   = "true"
           BooleanUtils.toStringTrueFalse(false)  = "false"

    Parameters:
      `bool` - the Boolean to check
    Returns:
      `'true'`, `'false'`, or `null`

  - ### toStringTrueFalse

    public static String toStringTrueFalse(Boolean bool)
    Converts a Boolean to a String returning `'true'`, `'false'`, or `null`.

           BooleanUtils.toStringTrueFalse(Boolean.TRUE)  = "true"
           BooleanUtils.toStringTrueFalse(Boolean.FALSE) = "false"
           BooleanUtils.toStringTrueFalse(null)          = null;

    Parameters:
      `bool` - the Boolean to check
    Returns:
      `'true'`, `'false'`, or `null`

  - ### toStringYesNo

    public static String toStringYesNo(boolean bool)
    Converts a boolean to a String returning `'yes'` or `'no'`.

           BooleanUtils.toStringYesNo(true)   = "yes"
           BooleanUtils.toStringYesNo(false)  = "no"

    Parameters:
      `bool` - the Boolean to check
    Returns:
      `'yes'`, `'no'`, or `null`

  - ### toStringYesNo

    public static String toStringYesNo(Boolean bool)
    Converts a Boolean to a String returning `'yes'`, `'no'`, or `null`.

           BooleanUtils.toStringYesNo(Boolean.TRUE)  = "yes"
           BooleanUtils.toStringYesNo(Boolean.FALSE) = "no"
           BooleanUtils.toStringYesNo(null)          = null;

    Parameters:
      `bool` - the Boolean to check
    Returns:
      `'yes'`, `'no'`, or `null`

  - ### values

    public static List<Boolean> values()
    Returns an unmodifiable list of Booleans `[false, true]`.
    Returns:
      an unmodifiable list of Booleans `[false, true]`.
    Since:
      3.13.0

  - ### xor

    public static boolean xor(boolean... array)
    Performs an xor on a set of booleans.

    This behaves like an XOR gate; it returns true if the number of true values is odd, and false if the number of true values is zero or even.

           BooleanUtils.xor(true, true)             = false
           BooleanUtils.xor(false, false)           = false
           BooleanUtils.xor(true, false)            = true
           BooleanUtils.xor(true, false, false)     = true
           BooleanUtils.xor(true, true, true)       = true
           BooleanUtils.xor(true, true, true, true) = false

    Parameters:
      `array` - an array of `boolean`s
    Returns:
      true if the number of true values in the array is odd; otherwise returns false.
    Throws:
      `NullPointerException` - if `array` is `null`
      `IllegalArgumentException` - if `array` is empty.

  - ### xor

    public static Boolean xor(Boolean... array)
    Performs an xor on an array of Booleans.

           BooleanUtils.xor(Boolean.TRUE, Boolean.TRUE)                 = Boolean.FALSE
           BooleanUtils.xor(Boolean.FALSE, Boolean.FALSE)               = Boolean.FALSE
           BooleanUtils.xor(Boolean.TRUE, Boolean.FALSE)                = Boolean.TRUE
           BooleanUtils.xor(Boolean.TRUE, Boolean.FALSE, Boolean.FALSE) = Boolean.TRUE
           BooleanUtils.xor(Boolean.FALSE, null)                        = Boolean.FALSE
           BooleanUtils.xor(Boolean.TRUE, null)                         = Boolean.TRUE

    Null array elements map to false, like `Boolean.parseBoolean(null)` and its callers return false.

    Parameters:
      `array` - an array of `Boolean`s
    Returns:
      the result of the xor operations
    Throws:
      `NullPointerException` - if `array` is `null`
      `IllegalArgumentException` - if `array` is empty.