1 /*
2 * Copyright (C) 2014 The Guava Authors
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
5 * in compliance with the License. You may obtain a copy of the License at
6 *
7 * http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software distributed under the License
10 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
11 * or implied. See the License for the specific language governing permissions and limitations under
12 * the License.
13 */
14
15 package com.google.common.base;
16
17 import static com.google.common.base.Preconditions.checkNotNull;
18
19 import com.google.common.annotations.GwtCompatible;
20 import com.google.errorprone.annotations.CanIgnoreReturnValue;
21 import java.lang.reflect.Array;
22 import java.util.Arrays;
23 import java.util.Collection;
24 import java.util.Map;
25 import java.util.OptionalDouble;
26 import java.util.OptionalInt;
27 import java.util.OptionalLong;
28 import javax.annotation.CheckForNull;
29
30 /**
31 * Helper functions that operate on any {@code Object}, and are not already provided in {@link
32 * java.util.Objects}.
33 *
34 * <p>See the Guava User Guide on <a
35 * href="https://github.com/google/guava/wiki/CommonObjectUtilitiesExplained">writing {@code Object}
36 * methods with {@code MoreObjects}</a>.
37 *
38 * @author Laurence Gonsalves
39 * @since 18.0 (since 2.0 as {@code Objects})
40 */
41 @GwtCompatible
42 @ElementTypesAreNonnullByDefault
43 public final class MoreObjects {
44 /**
45 * Returns the first of two given parameters that is not {@code null}, if either is, or otherwise
46 * throws a {@link NullPointerException}.
47 *
48 * <p>To find the first non-null element in an iterable, use {@code Iterables.find(iterable,
49 * Predicates.notNull())}. For varargs, use {@code Iterables.find(Arrays.asList(a, b, c, ...),
50 * Predicates.notNull())}, static importing as necessary.
51 *
52 * <p><b>Note:</b> if {@code first} is represented as an {@link Optional}, this can be
53 * accomplished with {@link Optional#or(Object) first.or(second)}. That approach also allows for
54 * lazy evaluation of the fallback instance, using {@link Optional#or(Supplier)
55 * first.or(supplier)}.
56 *
57 * <p><b>Java 9 users:</b> use {@code java.util.Objects.requireNonNullElse(first, second)}
58 * instead.
59 *
60 * @return {@code first} if it is non-null; otherwise {@code second} if it is non-null
61 * @throws NullPointerException if both {@code first} and {@code second} are null
62 * @since 18.0 (since 3.0 as {@code Objects.firstNonNull()}).
63 */
64 /*
65 * We annotate firstNonNull in a way that protects against NullPointerException at the cost of
66 * forbidding some reasonable calls.
67 *
68 * The more permissive signature would be to accept (@CheckForNull T first, @CheckForNull T
69 * second), since it's OK for `second` to be null as long as `first` is not also null. But we
70 * expect for that flexibility to be useful relatively rarely: The more common use case is to
71 * supply a clearly non-null default, like `firstNonNull(someString, "")`. And users who really
72 * know that `first` is guaranteed non-null when `second` is null can write the logic out
73 * longhand, including a requireNonNull call, which calls attention to the fact that the static
74 * analyzer can't prove that the operation is safe.
75 *
76 * This matches the signature we currently have for requireNonNullElse in our own checker. (And
77 * that in turn matches that method's signature under the Checker Framework.) As always, we could
78 * consider the more flexible signature if we judge it worth the risks. If we do, we would likely
79 * update both methods so that they continue to match.
80 */
81 public static <T> T firstNonNull(@CheckForNull T first, T second) {
82 if (first != null) {
83 return first;
84 }
85 if (second != null) {
86 return second;
87 }
88 throw new NullPointerException("Both parameters are null");
89 }
90
91 /**
92 * Creates an instance of {@link ToStringHelper}.
93 *
94 * <p>This is helpful for implementing {@link Object#toString()}. Specification by example:
95 *
96 * <pre>{@code
97 * // Returns "ClassName{}"
98 * MoreObjects.toStringHelper(this)
99 * .toString();
100 *
101 * // Returns "ClassName{x=1}"
102 * MoreObjects.toStringHelper(this)
103 * .add("x", 1)
104 * .toString();
105 *
106 * // Returns "MyObject{x=1}"
107 * MoreObjects.toStringHelper("MyObject")
108 * .add("x", 1)
109 * .toString();
110 *
111 * // Returns "ClassName{x=1, y=foo}"
112 * MoreObjects.toStringHelper(this)
113 * .add("x", 1)
114 * .add("y", "foo")
115 * .toString();
116 *
117 * // Returns "ClassName{x=1}"
118 * MoreObjects.toStringHelper(this)
119 * .omitNullValues()
120 * .add("x", 1)
121 * .add("y", null)
122 * .toString();
123 * }</pre>
124 *
125 * <p>Note that in GWT, class names are often obfuscated.
126 *
127 * @param self the object to generate the string for (typically {@code this}), used only for its
128 * class name
129 * @since 18.0 (since 2.0 as {@code Objects.toStringHelper()}).
130 */
131 public static ToStringHelper toStringHelper(Object self) {
132 return new ToStringHelper(self.getClass().getSimpleName());
133 }
134
135 /**
136 * Creates an instance of {@link ToStringHelper} in the same manner as {@link
137 * #toStringHelper(Object)}, but using the simple name of {@code clazz} instead of using an
138 * instance's {@link Object#getClass()}.
139 *
140 * <p>Note that in GWT, class names are often obfuscated.
141 *
142 * @param clazz the {@link Class} of the instance
143 * @since 18.0 (since 7.0 as {@code Objects.toStringHelper()}).
144 */
145 public static ToStringHelper toStringHelper(Class<?> clazz) {
146 return new ToStringHelper(clazz.getSimpleName());
147 }
148
149 /**
150 * Creates an instance of {@link ToStringHelper} in the same manner as {@link
151 * #toStringHelper(Object)}, but using {@code className} instead of using an instance's {@link
152 * Object#getClass()}.
153 *
154 * @param className the name of the instance type
155 * @since 18.0 (since 7.0 as {@code Objects.toStringHelper()}).
156 */
157 public static ToStringHelper toStringHelper(String className) {
158 return new ToStringHelper(className);
159 }
160
161 /**
162 * Support class for {@link MoreObjects#toStringHelper}.
163 *
164 * @author Jason Lee
165 * @since 18.0 (since 2.0 as {@code Objects.ToStringHelper}).
166 */
167 public static final class ToStringHelper {
168 private final String className;
169 private final ValueHolder holderHead = new ValueHolder();
170 private ValueHolder holderTail = holderHead;
171 private boolean omitNullValues = false;
172 private boolean omitEmptyValues = false;
173
174 /** Use {@link MoreObjects#toStringHelper(Object)} to create an instance. */
175 private ToStringHelper(String className) {
176 this.className = checkNotNull(className);
177 }
178
179 /**
180 * Configures the {@link ToStringHelper} so {@link #toString()} will ignore properties with null
181 * value. The order of calling this method, relative to the {@code add()}/{@code addValue()}
182 * methods, is not significant.
183 *
184 * @since 18.0 (since 12.0 as {@code Objects.ToStringHelper.omitNullValues()}).
185 */
186 @CanIgnoreReturnValue
187 public ToStringHelper omitNullValues() {
188 omitNullValues = true;
189 return this;
190 }
191
192 /**
193 * Adds a name/value pair to the formatted output in {@code name=value} format. If {@code value}
194 * is {@code null}, the string {@code "null"} is used, unless {@link #omitNullValues()} is
195 * called, in which case this name/value pair will not be added.
196 */
197 @CanIgnoreReturnValue
198 public ToStringHelper add(String name, @CheckForNull Object value) {
199 return addHolder(name, value);
200 }
201
202 /**
203 * Adds a name/value pair to the formatted output in {@code name=value} format.
204 *
205 * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add()}).
206 */
207 @CanIgnoreReturnValue
208 public ToStringHelper add(String name, boolean value) {
209 return addUnconditionalHolder(name, String.valueOf(value));
210 }
211
212 /**
213 * Adds a name/value pair to the formatted output in {@code name=value} format.
214 *
215 * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add()}).
216 */
217 @CanIgnoreReturnValue
218 public ToStringHelper add(String name, char value) {
219 return addUnconditionalHolder(name, String.valueOf(value));
220 }
221
222 /**
223 * Adds a name/value pair to the formatted output in {@code name=value} format.
224 *
225 * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add()}).
226 */
227 @CanIgnoreReturnValue
228 public ToStringHelper add(String name, double value) {
229 return addUnconditionalHolder(name, String.valueOf(value));
230 }
231
232 /**
233 * Adds a name/value pair to the formatted output in {@code name=value} format.
234 *
235 * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add()}).
236 */
237 @CanIgnoreReturnValue
238 public ToStringHelper add(String name, float value) {
239 return addUnconditionalHolder(name, String.valueOf(value));
240 }
241
242 /**
243 * Adds a name/value pair to the formatted output in {@code name=value} format.
244 *
245 * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add()}).
246 */
247 @CanIgnoreReturnValue
248 public ToStringHelper add(String name, int value) {
249 return addUnconditionalHolder(name, String.valueOf(value));
250 }
251
252 /**
253 * Adds a name/value pair to the formatted output in {@code name=value} format.
254 *
255 * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add()}).
256 */
257 @CanIgnoreReturnValue
258 public ToStringHelper add(String name, long value) {
259 return addUnconditionalHolder(name, String.valueOf(value));
260 }
261
262 /**
263 * Adds an unnamed value to the formatted output.
264 *
265 * <p>It is strongly encouraged to use {@link #add(String, Object)} instead and give value a
266 * readable name.
267 */
268 @CanIgnoreReturnValue
269 public ToStringHelper addValue(@CheckForNull Object value) {
270 return addHolder(value);
271 }
272
273 /**
274 * Adds an unnamed value to the formatted output.
275 *
276 * <p>It is strongly encouraged to use {@link #add(String, boolean)} instead and give value a
277 * readable name.
278 *
279 * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue()}).
280 */
281 @CanIgnoreReturnValue
282 public ToStringHelper addValue(boolean value) {
283 return addUnconditionalHolder(String.valueOf(value));
284 }
285
286 /**
287 * Adds an unnamed value to the formatted output.
288 *
289 * <p>It is strongly encouraged to use {@link #add(String, char)} instead and give value a
290 * readable name.
291 *
292 * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue()}).
293 */
294 @CanIgnoreReturnValue
295 public ToStringHelper addValue(char value) {
296 return addUnconditionalHolder(String.valueOf(value));
297 }
298
299 /**
300 * Adds an unnamed value to the formatted output.
301 *
302 * <p>It is strongly encouraged to use {@link #add(String, double)} instead and give value a
303 * readable name.
304 *
305 * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue()}).
306 */
307 @CanIgnoreReturnValue
308 public ToStringHelper addValue(double value) {
309 return addUnconditionalHolder(String.valueOf(value));
310 }
311
312 /**
313 * Adds an unnamed value to the formatted output.
314 *
315 * <p>It is strongly encouraged to use {@link #add(String, float)} instead and give value a
316 * readable name.
317 *
318 * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue()}).
319 */
320 @CanIgnoreReturnValue
321 public ToStringHelper addValue(float value) {
322 return addUnconditionalHolder(String.valueOf(value));
323 }
324
325 /**
326 * Adds an unnamed value to the formatted output.
327 *
328 * <p>It is strongly encouraged to use {@link #add(String, int)} instead and give value a
329 * readable name.
330 *
331 * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue()}).
332 */
333 @CanIgnoreReturnValue
334 public ToStringHelper addValue(int value) {
335 return addUnconditionalHolder(String.valueOf(value));
336 }
337
338 /**
339 * Adds an unnamed value to the formatted output.
340 *
341 * <p>It is strongly encouraged to use {@link #add(String, long)} instead and give value a
342 * readable name.
343 *
344 * @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue()}).
345 */
346 @CanIgnoreReturnValue
347 public ToStringHelper addValue(long value) {
348 return addUnconditionalHolder(String.valueOf(value));
349 }
350
351 private static boolean isEmpty(Object value) {
352 // Put types estimated to be most frequent first.
353 if (value instanceof CharSequence) {
354 return ((CharSequence) value).length() == 0;
355 } else if (value instanceof Collection) {
356 return ((Collection<?>) value).isEmpty();
357 } else if (value instanceof Map) {
358 return ((Map<?, ?>) value).isEmpty();
359 } else if (value instanceof java.util.Optional) {
360 return !((java.util.Optional<?>) value).isPresent();
361 } else if (value instanceof OptionalInt) {
362 return !((OptionalInt) value).isPresent();
363 } else if (value instanceof OptionalLong) {
364 return !((OptionalLong) value).isPresent();
365 } else if (value instanceof OptionalDouble) {
366 return !((OptionalDouble) value).isPresent();
367 } else if (value instanceof Optional) {
368 return !((Optional) value).isPresent();
369 } else if (value.getClass().isArray()) {
370 return Array.getLength(value) == 0;
371 }
372 return false;
373 }
374
375 /**
376 * Returns a string in the format specified by {@link MoreObjects#toStringHelper(Object)}.
377 *
378 * <p>After calling this method, you can keep adding more properties to later call toString()
379 * again and get a more complete representation of the same object; but properties cannot be
380 * removed, so this only allows limited reuse of the helper instance. The helper allows
381 * duplication of properties (multiple name/value pairs with the same name can be added).
382 */
383 @Override
384 public String toString() {
385 // create a copy to keep it consistent in case value changes
386 boolean omitNullValuesSnapshot = omitNullValues;
387 boolean omitEmptyValuesSnapshot = omitEmptyValues;
388 String nextSeparator = "";
389 StringBuilder builder = new StringBuilder(32).append(className).append('{');
390 for (ValueHolder valueHolder = holderHead.next;
391 valueHolder != null;
392 valueHolder = valueHolder.next) {
393 Object value = valueHolder.value;
394 if (valueHolder instanceof UnconditionalValueHolder
395 || (value == null
396 ? !omitNullValuesSnapshot
397 : (!omitEmptyValuesSnapshot || !isEmpty(value)))) {
398 builder.append(nextSeparator);
399 nextSeparator = ", ";
400
401 if (valueHolder.name != null) {
402 builder.append(valueHolder.name).append('=');
403 }
404 if (value != null && value.getClass().isArray()) {
405 Object[] objectArray = {value};
406 String arrayString = Arrays.deepToString(objectArray);
407 builder.append(arrayString, 1, arrayString.length() - 1);
408 } else {
409 builder.append(value);
410 }
411 }
412 }
413 return builder.append('}').toString();
414 }
415
416 private ValueHolder addHolder() {
417 ValueHolder valueHolder = new ValueHolder();
418 holderTail = holderTail.next = valueHolder;
419 return valueHolder;
420 }
421
422 private ToStringHelper addHolder(@CheckForNull Object value) {
423 ValueHolder valueHolder = addHolder();
424 valueHolder.value = value;
425 return this;
426 }
427
428 private ToStringHelper addHolder(String name, @CheckForNull Object value) {
429 ValueHolder valueHolder = addHolder();
430 valueHolder.value = value;
431 valueHolder.name = checkNotNull(name);
432 return this;
433 }
434
435 private UnconditionalValueHolder addUnconditionalHolder() {
436 UnconditionalValueHolder valueHolder = new UnconditionalValueHolder();
437 holderTail = holderTail.next = valueHolder;
438 return valueHolder;
439 }
440
441 private ToStringHelper addUnconditionalHolder(Object value) {
442 UnconditionalValueHolder valueHolder = addUnconditionalHolder();
443 valueHolder.value = value;
444 return this;
445 }
446
447 private ToStringHelper addUnconditionalHolder(String name, Object value) {
448 UnconditionalValueHolder valueHolder = addUnconditionalHolder();
449 valueHolder.value = value;
450 valueHolder.name = checkNotNull(name);
451 return this;
452 }
453
454 // Holder object for values that might be null and/or empty.
455 private static class ValueHolder {
456 @CheckForNull String name;
457 @CheckForNull Object value;
458 @CheckForNull ValueHolder next;
459 }
460
461 /**
462 * Holder object for values that cannot be null or empty (will be printed unconditionally). This
463 * helps to shortcut most calls to isEmpty(), which is important because the check for emptiness
464 * is relatively expensive. Use a subtype so this also doesn't need any extra storage.
465 */
466 private static final class UnconditionalValueHolder extends ValueHolder {}
467 }
468
469 private MoreObjects() {}
470 }