BooleanComparator.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.collections4.comparators;

  18. import java.io.Serializable;
  19. import java.util.Comparator;

  20. /**
  21.  * A {@link Comparator} for {@link Boolean} objects that can sort either
  22.  * true or false first.
  23.  *
  24.  * @see #getTrueFirstComparator()
  25.  * @see #getFalseFirstComparator()
  26.  * @see #booleanComparator(boolean)
  27.  * @since 3.0
  28.  */
  29. public final class BooleanComparator implements Comparator<Boolean>, Serializable {

  30.     /** Serialization version. */
  31.     private static final long serialVersionUID = 1830042991606340609L;

  32.     /** Constant "true first" reference. */
  33.     private static final BooleanComparator TRUE_FIRST = new BooleanComparator(true);

  34.     /** Constant "false first" reference. */
  35.     private static final BooleanComparator FALSE_FIRST = new BooleanComparator(false);

  36.     /**
  37.      * Returns a BooleanComparator instance that sorts
  38.      * {@code <em>trueFirst</em>} values before
  39.      * {@code &#x21;<em>trueFirst</em>} values.
  40.      * <p>
  41.      * Clients are encouraged to use the value returned from
  42.      * this method instead of constructing a new instance
  43.      * to reduce allocation and garbage collection overhead when
  44.      * multiple BooleanComparators may be used in the same
  45.      * virtual machine.
  46.      * </p>
  47.      *
  48.      * @param trueFirst when {@code true}, sort
  49.      * {@code true} {@code Boolean}s before {@code false}
  50.      * @return a singleton BooleanComparator instance
  51.      * @since 4.0
  52.      */
  53.     public static BooleanComparator booleanComparator(final boolean trueFirst) {
  54.         return trueFirst ? TRUE_FIRST : FALSE_FIRST;
  55.     }

  56.     /**
  57.      * Gets a BooleanComparator instance that sorts
  58.      * {@code false} values before {@code true} values.
  59.      * <p>
  60.      * Clients are encouraged to use the value returned from
  61.      * this method instead of constructing a new instance
  62.      * to reduce allocation and garbage collection overhead when
  63.      * multiple BooleanComparators may be used in the same
  64.      * virtual machine.
  65.      * </p>
  66.      *
  67.      * @return the false first singleton BooleanComparator
  68.      */
  69.     public static BooleanComparator getFalseFirstComparator() {
  70.         return FALSE_FIRST;
  71.     }

  72.     /**
  73.      * Gets a BooleanComparator instance that sorts
  74.      * {@code true} values before {@code false} values.
  75.      * <p>
  76.      * Clients are encouraged to use the value returned from
  77.      * this method instead of constructing a new instance
  78.      * to reduce allocation and garbage collection overhead when
  79.      * multiple BooleanComparators may be used in the same
  80.      * virtual machine.
  81.      * </p>
  82.      *
  83.      * @return the true first singleton BooleanComparator
  84.      */
  85.     public static BooleanComparator getTrueFirstComparator() {
  86.         return TRUE_FIRST;
  87.     }

  88.     /** {@code true} iff {@code true} values sort before {@code false} values. */
  89.     private final boolean trueFirst;

  90.     /**
  91.      * Creates a {@code BooleanComparator} that sorts
  92.      * {@code false} values before {@code true} values.
  93.      * <p>
  94.      * Equivalent to {@link #BooleanComparator(boolean) BooleanComparator(false)}.
  95.      * <p>
  96.      * Please use the static factory instead whenever possible.
  97.      */
  98.     public BooleanComparator() {
  99.         this(false);
  100.     }

  101.     /**
  102.      * Creates a {@code BooleanComparator} that sorts
  103.      * {@code <em>trueFirst</em>} values before
  104.      * {@code &#x21;<em>trueFirst</em>} values.
  105.      * <p>
  106.      * Please use the static factories instead whenever possible.
  107.      *
  108.      * @param trueFirst when {@code true}, sort
  109.      *  {@code true} boolean values before {@code false}
  110.      */
  111.     public BooleanComparator(final boolean trueFirst) {
  112.         this.trueFirst = trueFirst;
  113.     }

  114.     /**
  115.      * Compares two non-{@code null} {@code Boolean} objects
  116.      * according to the value of {@link #sortsTrueFirst()}.
  117.      *
  118.      * @param b1  the first boolean to compare
  119.      * @param b2  the second boolean to compare
  120.      * @return negative if obj1 is less, positive if greater, zero if equal
  121.      * @throws NullPointerException when either argument {@code null}
  122.      */
  123.     @Override
  124.     public int compare(final Boolean b1, final Boolean b2) {
  125.         final boolean v1 = b1.booleanValue();
  126.         final boolean v2 = b2.booleanValue();

  127.         return v1 ^ v2 ? v1 ^ trueFirst ? 1 : -1 : 0;
  128.     }

  129.     /**
  130.      * Returns {@code true} iff <em>that</em> Object is
  131.      * a {@link Comparator} whose ordering is known to be
  132.      * equivalent to mine.
  133.      * <p>
  134.      * This implementation returns {@code true}
  135.      * iff {@code <em>that</em>} is a {@link BooleanComparator}
  136.      * whose value of {@link #sortsTrueFirst()} is equal to mine.
  137.      *
  138.      * @param object  the object to compare to
  139.      * @return true if equal
  140.      */
  141.     @Override
  142.     public boolean equals(final Object object) {
  143.         return this == object ||
  144.                object instanceof BooleanComparator &&
  145.                 trueFirst == ((BooleanComparator) object).trueFirst;
  146.     }

  147.     /**
  148.      * Implement a hash code for this comparator that is consistent with
  149.      * {@link #equals(Object) equals}.
  150.      *
  151.      * @return a hash code for this comparator.
  152.      */
  153.     @Override
  154.     public int hashCode() {
  155.         final int hash = "BooleanComparator".hashCode();
  156.         return trueFirst ? -1 * hash : hash;
  157.     }

  158.     /**
  159.      * Returns {@code true} iff
  160.      * I sort {@code true} values before
  161.      * {@code false} values.  In other words,
  162.      * returns {@code true} iff
  163.      * {@link #compare(Boolean,Boolean) compare(Boolean.FALSE,Boolean.TRUE)}
  164.      * returns a positive value.
  165.      *
  166.      * @return the trueFirst flag
  167.      */
  168.     public boolean sortsTrueFirst() {
  169.         return trueFirst;
  170.     }

  171. }