1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16 package net.sf.collections15.comparators;
17
18 import java.io.Serializable;
19 import java.util.Comparator;
20
21
22
23 /***
24 * A {@link Comparator} for {@link Boolean} objects that can sort either
25 * <code>true</code> or <code>false</code> first.
26 *
27 * @author Rodney Waldhoff
28 * @author Chris Lambrou (port to Java 5.0)
29 * @see #getTrueFirstComparator()
30 * @see #getFalseFirstComparator()
31 * @see #getInstance(boolean)
32 * @since Collections15 1.0
33 */
34 public final class BooleanComparator implements Comparator<Boolean>, Serializable
35 {
36
37 static final long serialVersionUID = 4616435758859047808L;
38
39 /***
40 * Constant "true first" reference.
41 */
42 private static final BooleanComparator TRUE_FIRST = new BooleanComparator(true);
43
44 /***
45 * Constant "false first" reference.
46 */
47 private static final BooleanComparator FALSE_FIRST = new BooleanComparator(false);
48
49 /***
50 * <code>true</code> iff <code>true</code> values sort before
51 * <code>false</code> values.
52 */
53 private boolean trueFirst = false;
54
55 /***
56 * Returns a <code>BooleanComparator</code> instance that sorts
57 * <code>true</code> values before <code>false</code> values.
58 * <p/>
59 * Clients are encouraged to use the value returned from this method instead
60 * of constructing a new instance to reduce allocation and garbage
61 * collection overhead when multiple <code>BooleanComparators</code> may be
62 * used in the same virtual machine.
63 *
64 * @return a <code>Comparator</code> that sorts <code>true</code> before
65 * <code>false</code>.
66 */
67 public static BooleanComparator getTrueFirstComparator()
68 {
69 return TRUE_FIRST;
70 }
71
72 /***
73 * Returns a <code>BooleanComparator</code> instance that sorts
74 * <code>false</code> values before <code>true</code> values.
75 * <p/>
76 * Clients are encouraged to use the value returned from this method instead
77 * of constructing a new instance to reduce allocation and garbage
78 * collection overhead when multiple <code>BooleanComparators</code> may be
79 * used in the same virtual machine.
80 *
81 * @return a <code>Comparator</code> that sorts <code>false</code> before
82 * <code>true</code>.
83 */
84 public static BooleanComparator getFalseFirstComparator()
85 {
86 return FALSE_FIRST;
87 }
88
89 /***
90 * Returns a <code>BooleanComparator</code> instance with the specified
91 * sorting order.
92 * <p/>
93 * Clients are encouraged to use the value returned from this method instead
94 * of constructing a new instance to reduce allocation and garbage
95 * collection overhead when multiple <code>BooleanComparators</code> may be
96 * used in the same virtual machine.
97 *
98 * @param trueFirst If <code>true</code> the <code>Comparator</code>
99 * instance returned sorts <code>true</code> before
100 * </code>false</code>. If <code>false</code>, the returned
101 * instances sorts <code>false</code> before
102 * <code>true</code>.
103 *
104 * @return A <code>Comparator</code> with the specified sorting order.
105 */
106 public static BooleanComparator getInstance(boolean trueFirst)
107 {
108 return trueFirst ? TRUE_FIRST : FALSE_FIRST;
109 }
110
111 /***
112 * Creates a <code>BooleanComparator</code> that sorts
113 * <code>trueFirst</code> values before <code>!trueFirst</code> values.
114 *
115 * @param trueFirst If <code>true</code> the <code>Comparator</code> sorts
116 * <code>true</code> before </code>false</code>. If
117 * <code>false</code>, the <code>Comparator</code> sorts
118 * <code>false</code> before <code>true</code>.
119 */
120 protected BooleanComparator(boolean trueFirst)
121 {
122 this.trueFirst = trueFirst;
123 }
124
125 /***
126 * Compares two non-<code>null</code> <code>Boolean</code> objects according
127 * to the value of {@link #trueFirst}.
128 *
129 * @param b1 The first boolean to compare.
130 * @param b2 The second boolean to compare.
131 *
132 * @return A negative value if <code>b1</code> is less than <code>b2</code>,
133 * a positive value if <code>b1</code> is greater than
134 * <code>b2</code>, or zero if <code>b1</code> and </code>b2</code>
135 * are equal.
136 *
137 * @throws NullPointerException if either argument <code>null</code>.
138 */
139 public int compare(Boolean b1, Boolean b2)
140 {
141 boolean v1 = b1.booleanValue();
142 boolean v2 = b2.booleanValue();
143 return (v1 ^ v2) ? ((v1 ^ trueFirst) ? 1 : -1) : 0;
144 }
145
146 /***
147 * Implements a hash code for this comparator that is consistent with {@link
148 * #equals(Object) equals}.
149 *
150 * @return A hash code for this comparator.
151 */
152 public int hashCode()
153 {
154 int hash = "BooleanComparator".hashCode();
155 return trueFirst ? -hash : hash;
156 }
157
158 /***
159 * Compares this comparator to a specified object.
160 *
161 * @param object The object to compare to.
162 *
163 * @return <code>true</code> only if <code>object</code> is a
164 * <code>BooleanComparator</code> whose {@link #trueFirst} value is
165 * equal to this <code>BooleanComparator</code>'s value.
166 */
167 public boolean equals(Object object)
168 {
169 return (this == object) ||
170 ((object instanceof BooleanComparator) &&
171 (this.trueFirst == ((BooleanComparator) object).trueFirst));
172 }
173
174 /***
175 * Returns <code>true</code> only if this <code>Boolean</code> comparator
176 * instance sorts <code>true</code> values before <code>false</code> values.
177 * In other words, returns <code>true</code> only if {@link
178 * #compare(Boolean,Boolean) compare(Boolean.FALSE,Boolean.TRUE)} returns a
179 * positive value.
180 *
181 * @return The {@link #trueFirst} flag.
182 */
183 public boolean sortsTrueFirst()
184 {
185 return trueFirst;
186 }
187
188 }