org.cp.elements.lang.BooleanUtils Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of cp-elements Show documentation

Java Simplified. Extensions and Useful Constructs for the Java Platform. Codeprimate Elements (a.k.a. cp-elements) is a Java library and micro-framework used to simplify the development of software applications written in Java. Elements packages several APIs into one library in order to address various application concerns and aspects of software design and development collectively and conveniently. Elements is a highly simple, yet robust and proven library built on solid OO principles, software design patterns and best practices to effectively solve common and reoccurring problems in software development.

There is a newer version: 2.0.0-M1

Show newest version

/*
 * Copyright 2016 Author or Authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.cp.elements.lang;

import static org.cp.elements.util.ArrayUtils.nullSafeArray;

import java.util.concurrent.atomic.AtomicBoolean;

import org.cp.elements.lang.annotation.NullSafe;

/**
 * The BooleanUtils class provides utility methods for working with boolean values.
 *
 * @author John J. Blum
 * @see java.lang.Boolean
 * @see java.lang.Boolean#TYPE
 * @since 1.0.0
 */
public abstract class BooleanUtils {

  /**
   * Performs a logical AND on all the Boolean values and returns true if an only if all Boolean values evaluate
   * to true, as determined by the BooleanUtils.valueOf method on the Boolean wrapper object.  If the Boolean array
   * is null, then the result of the AND operation is false.
   *
   * @param values the array of Boolean values evaluated with the logical AND operator.
   * @return a boolean value of true if the Boolean array is not null and all Boolean wrapper object evaluate to true.
   * @see #valueOf(Boolean)
   */
  @SuppressWarnings("all")
  @NullSafe
  public static boolean and(Boolean... values) {
    boolean result = (values != null); // innocent until proven guilty

    if (result) {
      for (Boolean value : values) {
        result &= valueOf(value);
        if (!result) { // short-circuit if we find a false value
          break;
        }
      }
    }

    return result;
  }

  /**
   * Negates the specified evaluation of the Boolean value, which is determined by the BooleanUtils.valueOf method.
   * If the Boolean wrapper object is null or false, then this method returns true.  If the Boolean wrapper object
   * is true, then this method returns false.
   *
   * @param value the Boolean value being negated.
   * @return a negated boolean value of the specified Boolean wrapper object.
   * @see #valueOf(Boolean)
   */
  @NullSafe
  public static boolean negate(Boolean value) {
    return !valueOf(value);
  }

  /**
   * Performs a logical OR on all the Boolean values and returns true if just one Boolean value evaluates
   * to true, as determined by the BooleanUtils.valueOf method on the Boolean wrapper object.  If the Boolean array
   * is null, the result of the OR operation is false.
   *
   * @param values the array of Boolean values evaluated with the logical OR operator.
   * @return a boolean value of true if the Boolean array is not null and any of the Boolean values is true.
   * @see #valueOf(Boolean)
   */
  @SuppressWarnings("all")
  @NullSafe
  public static boolean or(Boolean... values) {
    boolean result = false; // guilty until proven innocent

    for (Boolean value : nullSafeArray(values, Boolean.class)) {
      result |= valueOf(value);
      if (result) { // short-circuit if we find a true value
        break;
      }
    }

    return result;
  }

  /**
   * Converts the specified primitive boolean value into a Boolean wrapper object.
   *
   * @param value the primitive boolean value to convert into the equivalent Boolean wrapper object.
   * @return a Boolean wrapper object with the same value as the primitive boolean value.
   * @see java.lang.Boolean
   */
  public static Boolean toBoolean(boolean value) {
    return (value ? Boolean.TRUE : Boolean.FALSE);
  }

  /**
   * Returns a String representation of the specified Boolean value.  If the Boolean value is true, then trueValue
   * is returned, otherwise falseValue is returned.
   *
   * @param value the Boolean value to evaluate and represent as one of the two String values representing true
   * and false.
   * @param trueValue String value representation for true.
   * @param falseValue String value representation of false.
   * @return a String representation of the specified Boolean value customized with values for true and false.
   * @see #valueOf(Boolean)
   */
  @NullSafe
  public static String toString(Boolean value, String trueValue, String falseValue) {
    return (valueOf(value) ? trueValue : falseValue);

  }

  /**
   * Determines the boolean value of the given {@link AtomicBoolean}.
   *
   * @param value {@link AtomicBoolean} to evaluate.
   * @return {@literal true} if the given {@link AtomicBoolean} is not {@literal null}
   * and is equal to a {@literal true} boolean value.
   * @see java.util.concurrent.atomic.AtomicBoolean
   */
  @NullSafe
  public static boolean valueOf(AtomicBoolean value) {
    return (value != null && value.get());
  }

  /**
   * Determines the primitive boolean value of the specified Boolean wrapper object.  The Boolean value is true
   * if and only if it is equal to Boolean.TRUE.  This method handles null values.
   *
   * @param value the Boolean wrapper value to convert to a primitive boolean value.
   * @return a primitive boolean value equivalent to the value of the Boolean wrapper object.
   * @see java.lang.Boolean
   */
  @NullSafe
  public static boolean valueOf(Boolean value) {
    return Boolean.TRUE.equals(value);
  }

  /**
   * Performs a logical exclusive OR on the array of Boolean values and returns true if and only if the Boolean array
   * is not null and 1 and only 1 Boolean wrapper object evaluates to true, as determined by the BooleanUtils.valueof
   * method.
   *
   * @param values the array of Boolean values evaluated with the logical exclusive OR operator.
   * @return a boolean value of true if and only if the Boolean array is not null and 1 and only 1 of the Boolean
   * wrapper objects evaluates to true.
   * @see #valueOf(Boolean)
   */
  @NullSafe
  public static boolean xor(Boolean... values) {
    boolean result = false; // guilty until proven innocent.

    for (Boolean value : nullSafeArray(values, Boolean.class)) {
      boolean primitiveValue = valueOf(value);

      if (result && primitiveValue) {
        return false; // short-circuit if we find more than 1 true value
      }

      result |= primitiveValue;
    }

    return result;
  }
}