1 /*
2 * Copyright (C) 2009 The Guava Authors
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 package com.google.common.collect;
18
19 import com.google.common.annotations.GwtCompatible;
20 import com.google.common.primitives.Booleans;
21 import com.google.common.primitives.Ints;
22 import com.google.common.primitives.Longs;
23 import java.util.Comparator;
24 import org.checkerframework.checker.nullness.qual.Nullable;
25
26 /**
27 * A utility for performing a chained comparison statement. For example:
28 *
29 * <pre>{@code
30 * public int compareTo(Foo that) {
31 * return ComparisonChain.start()
32 * .compare(this.aString, that.aString)
33 * .compare(this.anInt, that.anInt)
34 * .compare(this.anEnum, that.anEnum, Ordering.natural().nullsLast())
35 * .result();
36 * }
37 * }</pre>
38 *
39 * <p>The value of this expression will have the same sign as the <i>first nonzero</i> comparison
40 * result in the chain, or will be zero if every comparison result was zero.
41 *
42 * <p><b>Note:</b> {@code ComparisonChain} instances are <b>immutable</b>. For this utility to work
43 * correctly, calls must be chained as illustrated above.
44 *
45 * <p>Performance note: Even though the {@code ComparisonChain} caller always invokes its {@code
46 * compare} methods unconditionally, the {@code ComparisonChain} implementation stops calling its
47 * inputs' {@link Comparable#compareTo compareTo} and {@link Comparator#compare compare} methods as
48 * soon as one of them returns a nonzero result. This optimization is typically important only in
49 * the presence of expensive {@code compareTo} and {@code compare} implementations.
50 *
51 * <p>See the Guava User Guide article on <a href=
52 * "https://github.com/google/guava/wiki/CommonObjectUtilitiesExplained#comparecompareto"> {@code
53 * ComparisonChain}</a>.
54 *
55 * @author Mark Davis
56 * @author Kevin Bourrillion
57 * @since 2.0
58 */
59 @GwtCompatible
60 public abstract class ComparisonChain {
61 private ComparisonChain() {}
62
63 /** Begins a new chained comparison statement. See example in the class documentation. */
64 public static ComparisonChain start() {
65 return ACTIVE;
66 }
67
68 private static final ComparisonChain ACTIVE =
69 new ComparisonChain() {
70 @SuppressWarnings("unchecked")
71 @Override
72 public ComparisonChain compare(Comparable left, Comparable right) {
73 return classify(left.compareTo(right));
74 }
75
76 @Override
77 public <T> ComparisonChain compare(
78 @Nullable T left, @Nullable T right, Comparator<T> comparator) {
79 return classify(comparator.compare(left, right));
80 }
81
82 @Override
83 public ComparisonChain compare(int left, int right) {
84 return classify(Ints.compare(left, right));
85 }
86
87 @Override
88 public ComparisonChain compare(long left, long right) {
89 return classify(Longs.compare(left, right));
90 }
91
92 @Override
93 public ComparisonChain compare(float left, float right) {
94 return classify(Float.compare(left, right));
95 }
96
97 @Override
98 public ComparisonChain compare(double left, double right) {
99 return classify(Double.compare(left, right));
100 }
101
102 @Override
103 public ComparisonChain compareTrueFirst(boolean left, boolean right) {
104 return classify(Booleans.compare(right, left)); // reversed
105 }
106
107 @Override
108 public ComparisonChain compareFalseFirst(boolean left, boolean right) {
109 return classify(Booleans.compare(left, right));
110 }
111
112 ComparisonChain classify(int result) {
113 return (result < 0) ? LESS : (result > 0) ? GREATER : ACTIVE;
114 }
115
116 @Override
117 public int result() {
118 return 0;
119 }
120 };
121
122 private static final ComparisonChain LESS = new InactiveComparisonChain(-1);
123
124 private static final ComparisonChain GREATER = new InactiveComparisonChain(1);
125
126 private static final class InactiveComparisonChain extends ComparisonChain {
127 final int result;
128
129 InactiveComparisonChain(int result) {
130 this.result = result;
131 }
132
133 @Override
134 public ComparisonChain compare(@Nullable Comparable left, @Nullable Comparable right) {
135 return this;
136 }
137
138 @Override
139 public <T> ComparisonChain compare(
140 @Nullable T left, @Nullable T right, @Nullable Comparator<T> comparator) {
141 return this;
142 }
143
144 @Override
145 public ComparisonChain compare(int left, int right) {
146 return this;
147 }
148
149 @Override
150 public ComparisonChain compare(long left, long right) {
151 return this;
152 }
153
154 @Override
155 public ComparisonChain compare(float left, float right) {
156 return this;
157 }
158
159 @Override
160 public ComparisonChain compare(double left, double right) {
161 return this;
162 }
163
164 @Override
165 public ComparisonChain compareTrueFirst(boolean left, boolean right) {
166 return this;
167 }
168
169 @Override
170 public ComparisonChain compareFalseFirst(boolean left, boolean right) {
171 return this;
172 }
173
174 @Override
175 public int result() {
176 return result;
177 }
178 }
179
180 /**
181 * Compares two comparable objects as specified by {@link Comparable#compareTo}, <i>if</i> the
182 * result of this comparison chain has not already been determined.
183 */
184 public abstract ComparisonChain compare(Comparable<?> left, Comparable<?> right);
185
186 /**
187 * Compares two objects using a comparator, <i>if</i> the result of this comparison chain has not
188 * already been determined.
189 */
190 public abstract <T> ComparisonChain compare(
191 @Nullable T left, @Nullable T right, Comparator<T> comparator);
192
193 /**
194 * Compares two {@code int} values as specified by {@link Ints#compare}, <i>if</i> the result of
195 * this comparison chain has not already been determined.
196 */
197 public abstract ComparisonChain compare(int left, int right);
198
199 /**
200 * Compares two {@code long} values as specified by {@link Longs#compare}, <i>if</i> the result of
201 * this comparison chain has not already been determined.
202 */
203 public abstract ComparisonChain compare(long left, long right);
204
205 /**
206 * Compares two {@code float} values as specified by {@link Float#compare}, <i>if</i> the result
207 * of this comparison chain has not already been determined.
208 */
209 public abstract ComparisonChain compare(float left, float right);
210
211 /**
212 * Compares two {@code double} values as specified by {@link Double#compare}, <i>if</i> the result
213 * of this comparison chain has not already been determined.
214 */
215 public abstract ComparisonChain compare(double left, double right);
216
217 /**
218 * Discouraged synonym for {@link #compareFalseFirst}.
219 *
220 * @deprecated Use {@link #compareFalseFirst}; or, if the parameters passed are being either
221 * negated or reversed, undo the negation or reversal and use {@link #compareTrueFirst}.
222 * @since 19.0
223 */
224 @Deprecated
225 public final ComparisonChain compare(Boolean left, Boolean right) {
226 return compareFalseFirst(left, right);
227 }
228
229 /**
230 * Compares two {@code boolean} values, considering {@code true} to be less than {@code false},
231 * <i>if</i> the result of this comparison chain has not already been determined.
232 *
233 * @since 12.0
234 */
235 public abstract ComparisonChain compareTrueFirst(boolean left, boolean right);
236
237 /**
238 * Compares two {@code boolean} values, considering {@code false} to be less than {@code true},
239 * <i>if</i> the result of this comparison chain has not already been determined.
240 *
241 * @since 12.0 (present as {@code compare} since 2.0)
242 */
243 public abstract ComparisonChain compareFalseFirst(boolean left, boolean right);
244
245 /**
246 * Ends this comparison chain and returns its result: a value having the same sign as the first
247 * nonzero comparison result in the chain, or zero if every result was zero.
248 */
249 public abstract int result();
250 }