BooleanUtils
Date: 2017-02-08

org.apache.commons.lang3

## Class BooleanUtils

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

-     public class BooleanUtils
      extends java.lang.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 behaviour in more detail.

  #ThreadSafe#

  Since:
    2.0

- - ### Constructor Summary

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

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static boolean` | `and(boolean... array)` Performs an and on a set of booleans.
    `static java.lang.Boolean` | `and(java.lang.Boolean... array)` Performs an and on an array of Booleans.
    `static int` | `compare(boolean x, boolean y)` Compares two `boolean` values.
    `static boolean` | `isFalse(java.lang.Boolean bool)` Checks if a `Boolean` value is `false`, handling `null` by returning `false`.
    `static boolean` | `isNotFalse(java.lang.Boolean bool)` Checks if a `Boolean` value is not `false`, handling `null` by returning `true`.
    `static boolean` | `isNotTrue(java.lang.Boolean bool)` Checks if a `Boolean` value is not `true`, handling `null` by returning `true`.
    `static boolean` | `isTrue(java.lang.Boolean bool)` Checks if a `Boolean` value is `true`, handling `null` by returning `false`.
    `static java.lang.Boolean` | `negate(java.lang.Boolean bool)` Negates the specified boolean.
    `static boolean` | `or(boolean... array)` Performs an or on a set of booleans.
    `static java.lang.Boolean` | `or(java.lang.Boolean... array)` Performs an or on an array of Booleans.
    `static boolean` | `toBoolean(java.lang.Boolean bool)` Converts a Boolean to a boolean handling `null` by returning `false`.
    `static boolean` | `toBoolean(int value)` Converts an int to a boolean using the convention that `zero` is `false`.
    `static boolean` | `toBoolean(java.lang.Integer value, java.lang.Integer trueValue, java.lang.Integer falseValue)` Converts an Integer to a boolean specifying the conversion values.
    `static boolean` | `toBoolean(int value, int trueValue, int falseValue)` Converts an int to a boolean specifying the conversion values.
    `static boolean` | `toBoolean(java.lang.String str)` Converts a String to a boolean (optimised for performance).
    `static boolean` | `toBoolean(java.lang.String str, java.lang.String trueString, java.lang.String falseString)` Converts a String to a Boolean throwing an exception if no match found.
    `static boolean` | `toBooleanDefaultIfNull(java.lang.Boolean bool, boolean valueIfNull)` Converts a Boolean to a boolean handling `null`.
    `static java.lang.Boolean` | `toBooleanObject(int value)` Converts an int to a Boolean using the convention that `zero` is `false`.
    `static java.lang.Boolean` | `toBooleanObject(java.lang.Integer value)` Converts an Integer to a Boolean using the convention that `zero` is `false`.
    `static java.lang.Boolean` | `toBooleanObject(java.lang.Integer value, java.lang.Integer trueValue, java.lang.Integer falseValue, java.lang.Integer nullValue)` Converts an Integer to a Boolean specifying the conversion values.
    `static java.lang.Boolean` | `toBooleanObject(int value, int trueValue, int falseValue, int nullValue)` Converts an int to a Boolean specifying the conversion values.
    `static java.lang.Boolean` | `toBooleanObject(java.lang.String str)` Converts a String to a Boolean.
    `static java.lang.Boolean` | `toBooleanObject(java.lang.String str, java.lang.String trueString, java.lang.String falseString, java.lang.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 `zero` is `false`.
    `static int` | `toInteger(boolean bool, int trueValue, int falseValue)` Converts a boolean to an int specifying the conversion values.
    `static int` | `toInteger(java.lang.Boolean bool, int trueValue, int falseValue, int nullValue)` Converts a Boolean to an int specifying the conversion values.
    `static java.lang.Integer` | `toIntegerObject(boolean bool)` Converts a boolean to an Integer using the convention that `zero` is `false`.
    `static java.lang.Integer` | `toIntegerObject(java.lang.Boolean bool)` Converts a Boolean to a Integer using the convention that `zero` is `false`.
    `static java.lang.Integer` | `toIntegerObject(boolean bool, java.lang.Integer trueValue, java.lang.Integer falseValue)` Converts a boolean to an Integer specifying the conversion values.
    `static java.lang.Integer` | `toIntegerObject(java.lang.Boolean bool, java.lang.Integer trueValue, java.lang.Integer falseValue, java.lang.Integer nullValue)` Converts a Boolean to an Integer specifying the conversion values.
    `static java.lang.String` | `toString(boolean bool, java.lang.String trueString, java.lang.String falseString)` Converts a boolean to a String returning one of the input Strings.
    `static java.lang.String` | `toString(java.lang.Boolean bool, java.lang.String trueString, java.lang.String falseString, java.lang.String nullString)` Converts a Boolean to a String returning one of the input Strings.
    `static java.lang.String` | `toStringOnOff(boolean bool)` Converts a boolean to a String returning `'on'` or `'off'`.
    `static java.lang.String` | `toStringOnOff(java.lang.Boolean bool)` Converts a Boolean to a String returning `'on'`, `'off'`, or `null`.
    `static java.lang.String` | `toStringTrueFalse(boolean bool)` Converts a boolean to a String returning `'true'` or `'false'`.
    `static java.lang.String` | `toStringTrueFalse(java.lang.Boolean bool)` Converts a Boolean to a String returning `'true'`, `'false'`, or `null`.
    `static java.lang.String` | `toStringYesNo(boolean bool)` Converts a boolean to a String returning `'yes'` or `'no'`.
    `static java.lang.String` | `toStringYesNo(java.lang.Boolean bool)` Converts a Boolean to a String returning `'yes'`, `'no'`, or `null`.
    `static boolean` | `xor(boolean... array)` Performs an xor on a set of booleans.
    `static java.lang.Boolean` | `xor(java.lang.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`

- - ### Constructor Detail

    - #### 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 Detail

    - #### negate

          public static java.lang.Boolean negate(java.lang.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 autoboxed 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

    - #### isTrue

          public static boolean isTrue(java.lang.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

    - #### isNotTrue

          public static boolean isNotTrue(java.lang.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

    - #### isFalse

          public static boolean isFalse(java.lang.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(java.lang.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

    - #### toBoolean

          public static boolean toBoolean(java.lang.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`

    - #### toBooleanDefaultIfNull

          public static boolean toBooleanDefaultIfNull(java.lang.Boolean bool,
                                       boolean valueIfNull)

      Converts a Boolean to a boolean handling `null`.

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

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

    - #### toBoolean

          public static boolean toBoolean(int value)

      Converts an int to a boolean using the convention that `zero` is `false`.

             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

    - #### toBooleanObject

          public static java.lang.Boolean toBooleanObject(int value)

      Converts an int to a Boolean using the convention that `zero` is `false`.

             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 java.lang.Boolean toBooleanObject(java.lang.Integer value)

      Converts an Integer to a Boolean using the convention that `zero` is `false`.

      `null` will be converted to `null`.

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

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

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

    - #### toBoolean

          public static boolean toBoolean(int value,
                          int trueValue,
                          int falseValue)

      Converts an int to a boolean specifying the conversion values.

             BooleanUtils.toBoolean(0, 1, 0) = false
             BooleanUtils.toBoolean(1, 1, 0) = 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:
        `java.lang.IllegalArgumentException` - if no match

    - #### toBoolean

          public static boolean toBoolean(java.lang.Integer value,
                          java.lang.Integer trueValue,
                          java.lang.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:
        `java.lang.IllegalArgumentException` - if no match

    - #### toBooleanObject

          public static java.lang.Boolean toBooleanObject(int value,
                                          int trueValue,
                                          int falseValue,
                                          int nullValue)

      Converts an int to a Boolean specifying the conversion values.

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

             BooleanUtils.toBooleanObject(0, 0, 2, 3) = Boolean.TRUE
             BooleanUtils.toBooleanObject(2, 1, 2, 3) = 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 to match for `null`
      Returns:
        Boolean.TRUE, Boolean.FALSE, or `null`
      Throws:
        `java.lang.IllegalArgumentException` - if no match

    - #### toBooleanObject

          public static java.lang.Boolean toBooleanObject(java.lang.Integer value,
                                          java.lang.Integer trueValue,
                                          java.lang.Integer falseValue,
                                          java.lang.Integer nullValue)

      Converts an Integer to a Boolean specifying the conversion values.

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

             BooleanUtils.toBooleanObject(Integer.valueOf(0), Integer.valueOf(0), Integer.valueOf(2), Integer.valueOf(3)) = Boolean.TRUE
             BooleanUtils.toBooleanObject(Integer.valueOf(2), Integer.valueOf(1), Integer.valueOf(2), Integer.valueOf(3)) = 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 to match for `null`, may be `null`
      Returns:
        Boolean.TRUE, Boolean.FALSE, or `null`
      Throws:
        `java.lang.IllegalArgumentException` - if no match

    - #### toInteger

          public static int toInteger(boolean bool)

      Converts a boolean to an int using the convention that `zero` is `false`.

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

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

    - #### toIntegerObject

          public static java.lang.Integer toIntegerObject(boolean bool)

      Converts a boolean to an Integer using the convention that `zero` is `false`.

             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 java.lang.Integer toIntegerObject(java.lang.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`

    - #### 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(java.lang.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 java.lang.Integer toIntegerObject(boolean bool,
                                          java.lang.Integer trueValue,
                                          java.lang.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 java.lang.Integer toIntegerObject(java.lang.Boolean bool,
                                          java.lang.Integer trueValue,
                                          java.lang.Integer falseValue,
                                          java.lang.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

    - #### toBooleanObject

          public static java.lang.Boolean toBooleanObject(java.lang.String str)

      Converts a String to a Boolean.

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

      NOTE: This returns null and will throw a NullPointerException if autoboxed 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("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 java.lang.Boolean toBooleanObject(java.lang.String str,
                                          java.lang.String trueString,
                                          java.lang.String falseString,
                                          java.lang.String nullString)

      Converts a String to a Boolean throwing an exception if no match.

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

             BooleanUtils.toBooleanObject("true", "true", "false", "null")  = Boolean.TRUE
             BooleanUtils.toBooleanObject("false", "true", "false", "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:
        `java.lang.IllegalArgumentException` - if the String doesn't match

    - #### toBoolean

          public static boolean toBoolean(java.lang.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.toBooleanObject("y") = true
             BooleanUtils.toBooleanObject("n") = false
             BooleanUtils.toBooleanObject("t") = true
             BooleanUtils.toBooleanObject("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(java.lang.String str,
                          java.lang.String trueString,
                          java.lang.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:
        `java.lang.IllegalArgumentException` - if the String doesn't match

    - #### toStringTrueFalse

          public static java.lang.String toStringTrueFalse(java.lang.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`

    - #### toStringOnOff

          public static java.lang.String toStringOnOff(java.lang.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`

    - #### toStringYesNo

          public static java.lang.String toStringYesNo(java.lang.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`

    - #### toString

          public static java.lang.String toString(java.lang.Boolean bool,
                                  java.lang.String trueString,
                                  java.lang.String falseString,
                                  java.lang.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

    - #### toStringTrueFalse

          public static java.lang.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`

    - #### toStringOnOff

          public static java.lang.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`

    - #### toStringYesNo

          public static java.lang.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`

    - #### toString

          public static java.lang.String toString(boolean bool,
                                  java.lang.String trueString,
                                  java.lang.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

    - #### and

          public static boolean and(boolean... array)

      Performs an and 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:
        `true` if the and is successful.
      Throws:
        `java.lang.IllegalArgumentException` - if `array` is `null`
        `java.lang.IllegalArgumentException` - if `array` is empty.
      Since:
        3.0.1

    - #### and

          public static java.lang.Boolean and(java.lang.Boolean... array)

      Performs an and 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

      Parameters:
        `array` - an array of `Boolean`s
      Returns:
        `true` if the and is successful.
      Throws:
        `java.lang.IllegalArgumentException` - if `array` is `null`
        `java.lang.IllegalArgumentException` - if `array` is empty.
        `java.lang.IllegalArgumentException` - if `array` contains a `null`
      Since:
        3.0.1

    - #### or

          public static boolean or(boolean... array)

      Performs an or 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 the or is successful.
      Throws:
        `java.lang.IllegalArgumentException` - if `array` is `null`
        `java.lang.IllegalArgumentException` - if `array` is empty.
      Since:
        3.0.1

    - #### or

          public static java.lang.Boolean or(java.lang.Boolean... array)

      Performs an or 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

      Parameters:
        `array` - an array of `Boolean`s
      Returns:
        `true` if the or is successful.
      Throws:
        `java.lang.IllegalArgumentException` - if `array` is `null`
        `java.lang.IllegalArgumentException` - if `array` is empty.
        `java.lang.IllegalArgumentException` - if `array` contains a `null`
      Since:
        3.0.1

    - #### xor

          public static boolean xor(boolean... array)

      Performs an xor on a set of booleans.

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

      Parameters:
        `array` - an array of `boolean`s
      Returns:
        `true` if the xor is successful.
      Throws:
        `java.lang.IllegalArgumentException` - if `array` is `null`
        `java.lang.IllegalArgumentException` - if `array` is empty.

    - #### xor

          public static java.lang.Boolean xor(java.lang.Boolean... array)

      Performs an xor on an array of Booleans.

             BooleanUtils.xor(new Boolean[] { Boolean.TRUE, Boolean.TRUE })   = Boolean.FALSE
             BooleanUtils.xor(new Boolean[] { Boolean.FALSE, Boolean.FALSE }) = Boolean.FALSE
             BooleanUtils.xor(new Boolean[] { Boolean.TRUE, Boolean.FALSE })  = Boolean.TRUE

      Parameters:
        `array` - an array of `Boolean`s
      Returns:
        `true` if the xor is successful.
      Throws:
        `java.lang.IllegalArgumentException` - if `array` is `null`
        `java.lang.IllegalArgumentException` - if `array` is empty.
        `java.lang.IllegalArgumentException` - if `array` contains a `null`

    - #### 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