Source code

001/*
002 * Copyright (C) 2007 The Guava Authors
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
005 * in compliance with the License. You may obtain a copy of the License at
006 *
007 * http://www.apache.org/licenses/LICENSE-2.0
008 *
009 * Unless required by applicable law or agreed to in writing, software distributed under the License
010 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
011 * or implied. See the License for the specific language governing permissions and limitations under
012 * the License.
013 */
014
015package com.google.common.base;
016
017import static com.google.common.base.Strings.lenientFormat;
018import static java.util.logging.Level.WARNING;
019
020import com.google.common.annotations.GwtCompatible;
021import com.google.errorprone.annotations.CanIgnoreReturnValue;
022import java.util.logging.Logger;
023import org.checkerframework.checker.nullness.compatqual.NonNullDecl;
024import org.checkerframework.checker.nullness.compatqual.NullableDecl;
025
026/**
027 * Static convenience methods that help a method or constructor check whether it was invoked
028 * correctly (that is, whether its <i>preconditions</i> were met).
029 *
030 * <p>If the precondition is not met, the {@code Preconditions} method throws an unchecked exception
031 * of a specified type, which helps the method in which the exception was thrown communicate that
032 * its caller has made a mistake. This allows constructs such as
033 *
034 * <pre>{@code
035 * public static double sqrt(double value) {
036 *   if (value < 0) {
037 *     throw new IllegalArgumentException("input is negative: " + value);
038 *   }
039 *   // calculate square root
040 * }
041 * }</pre>
042 *
043 * <p>to be replaced with the more compact
044 *
045 * <pre>{@code
046 * public static double sqrt(double value) {
047 *   checkArgument(value >= 0, "input is negative: %s", value);
048 *   // calculate square root
049 * }
050 * }</pre>
051 *
052 * <p>so that a hypothetical bad caller of this method, such as:
053 *
054 * <pre>{@code
055 * void exampleBadCaller() {
056 *   double d = sqrt(-1.0);
057 * }
058 * }</pre>
059 *
060 * <p>would be flagged as having called {@code sqrt()} with an illegal argument.
061 *
062 * <h3>Performance</h3>
063 *
064 * <p>Avoid passing message arguments that are expensive to compute; your code will always compute
065 * them, even though they usually won't be needed. If you have such arguments, use the conventional
066 * if/throw idiom instead.
067 *
068 * <p>Depending on your message arguments, memory may be allocated for boxing and varargs array
069 * creation. However, the methods of this class have a large number of overloads that prevent such
070 * allocations in many common cases.
071 *
072 * <p>The message string is not formatted unless the exception will be thrown, so the cost of the
073 * string formatting itself should not be a concern.
074 *
075 * <p>As with any performance concerns, you should consider profiling your code (in a production
076 * environment if possible) before spending a lot of effort on tweaking a particular element.
077 *
078 * <h3>Other types of preconditions</h3>
079 *
080 * <p>Not every type of precondition failure is supported by these methods. Continue to throw
081 * standard JDK exceptions such as {@link java.util.NoSuchElementException} or {@link
082 * UnsupportedOperationException} in the situations they are intended for.
083 *
084 * <h3>Non-preconditions</h3>
085 *
086 * <p>It is of course possible to use the methods of this class to check for invalid conditions
087 * which are <i>not the caller's fault</i>. Doing so is <b>not recommended</b> because it is
088 * misleading to future readers of the code and of stack traces. See <a
089 * href="https://github.com/google/guava/wiki/ConditionalFailuresExplained">Conditional failures
090 * explained</a> in the Guava User Guide for more advice. Notably, {@link Verify} offers assertions
091 * similar to those in this class for non-precondition checks.
092 *
093 * <h3>{@code java.util.Objects.requireNonNull()}</h3>
094 *
095 * <p>Projects which use {@code com.google.common} should generally avoid the use of {@link
096 * java.util.Objects#requireNonNull(Object)}. Instead, use whichever of {@link
097 * #checkNotNull(Object)} or {@link Verify#verifyNotNull(Object)} is appropriate to the situation.
098 * (The same goes for the message-accepting overloads.)
099 *
100 * <h3>Only {@code %s} is supported</h3>
101 *
102 * <p>{@code Preconditions} uses {@link Strings#lenientFormat} to format error message template
103 * strings. This only supports the {@code "%s"} specifier, not the full range of {@link
104 * java.util.Formatter} specifiers. However, note that if the number of arguments does not match the
105 * number of occurrences of {@code "%s"} in the format string, {@code Preconditions} will still
106 * behave as expected, and will still include all argument values in the error message; the message
107 * will simply not be formatted exactly as intended.
108 *
109 * <h3>More information</h3>
110 *
111 * <p>See the Guava User Guide on <a
112 * href="https://github.com/google/guava/wiki/PreconditionsExplained">using {@code
113 * Preconditions}</a>.
114 *
115 * @author Kevin Bourrillion
116 * @since 2.0
117 */
118@GwtCompatible
119public final class Preconditions {
120  private Preconditions() {}
121
122  /**
123   * Ensures the truth of an expression involving one or more parameters to the calling method.
124   *
125   * @param expression a boolean expression
126   * @throws IllegalArgumentException if {@code expression} is false
127   */
128  public static void checkArgument(boolean expression) {
129    if (!expression) {
130      throw new IllegalArgumentException();
131    }
132  }
133
134  /**
135   * Ensures the truth of an expression involving one or more parameters to the calling method.
136   *
137   * @param expression a boolean expression
138   * @param errorMessage the exception message to use if the check fails; will be converted to a
139   *     string using {@link String#valueOf(Object)}
140   * @throws IllegalArgumentException if {@code expression} is false
141   */
142  public static void checkArgument(boolean expression, @NullableDecl Object errorMessage) {
143    if (!expression) {
144      throw new IllegalArgumentException(String.valueOf(errorMessage));
145    }
146  }
147
148  /**
149   * Ensures the truth of an expression involving one or more parameters to the calling method.
150   *
151   * @param expression a boolean expression
152   * @param errorMessageTemplate a template for the exception message should the check fail. The
153   *     message is formed by replacing each {@code %s} placeholder in the template with an
154   *     argument. These are matched by position - the first {@code %s} gets {@code
155   *     errorMessageArgs[0]}, etc. Unmatched arguments will be appended to the formatted message in
156   *     square braces. Unmatched placeholders will be left as-is.
157   * @param errorMessageArgs the arguments to be substituted into the message template. Arguments
158   *     are converted to strings using {@link String#valueOf(Object)}.
159   * @throws IllegalArgumentException if {@code expression} is false
160   */
161  public static void checkArgument(
162      boolean expression,
163      @NullableDecl String errorMessageTemplate,
164      @NullableDecl Object... errorMessageArgs) {
165    if (!expression) {
166      throw new IllegalArgumentException(lenientFormat(errorMessageTemplate, errorMessageArgs));
167    }
168  }
169
170  /**
171   * Ensures the truth of an expression involving one or more parameters to the calling method.
172   *
173   * <p>See {@link #checkArgument(boolean, String, Object...)} for details.
174   *
175   * @since 20.0 (varargs overload since 2.0)
176   */
177  public static void checkArgument(boolean b, @NullableDecl String errorMessageTemplate, char p1) {
178    if (!b) {
179      throw new IllegalArgumentException(lenientFormat(errorMessageTemplate, p1));
180    }
181  }
182
183  /**
184   * Ensures the truth of an expression involving one or more parameters to the calling method.
185   *
186   * <p>See {@link #checkArgument(boolean, String, Object...)} for details.
187   *
188   * @since 20.0 (varargs overload since 2.0)
189   */
190  public static void checkArgument(boolean b, @NullableDecl String errorMessageTemplate, int p1) {
191    if (!b) {
192      throw new IllegalArgumentException(lenientFormat(errorMessageTemplate, p1));
193    }
194  }
195
196  /**
197   * Ensures the truth of an expression involving one or more parameters to the calling method.
198   *
199   * <p>See {@link #checkArgument(boolean, String, Object...)} for details.
200   *
201   * @since 20.0 (varargs overload since 2.0)
202   */
203  public static void checkArgument(boolean b, @NullableDecl String errorMessageTemplate, long p1) {
204    if (!b) {
205      throw new IllegalArgumentException(lenientFormat(errorMessageTemplate, p1));
206    }
207  }
208
209  /**
210   * Ensures the truth of an expression involving one or more parameters to the calling method.
211   *
212   * <p>See {@link #checkArgument(boolean, String, Object...)} for details.
213   *
214   * @since 20.0 (varargs overload since 2.0)
215   */
216  public static void checkArgument(
217      boolean b, @NullableDecl String errorMessageTemplate, @NullableDecl Object p1) {
218    if (!b) {
219      throw new IllegalArgumentException(lenientFormat(errorMessageTemplate, p1));
220    }
221  }
222
223  /**
224   * Ensures the truth of an expression involving one or more parameters to the calling method.
225   *
226   * <p>See {@link #checkArgument(boolean, String, Object...)} for details.
227   *
228   * @since 20.0 (varargs overload since 2.0)
229   */
230  public static void checkArgument(
231      boolean b, @NullableDecl String errorMessageTemplate, char p1, char p2) {
232    if (!b) {
233      throw new IllegalArgumentException(lenientFormat(errorMessageTemplate, p1, p2));
234    }
235  }
236
237  /**
238   * Ensures the truth of an expression involving one or more parameters to the calling method.
239   *
240   * <p>See {@link #checkArgument(boolean, String, Object...)} for details.
241   *
242   * @since 20.0 (varargs overload since 2.0)
243   */
244  public static void checkArgument(
245      boolean b, @NullableDecl String errorMessageTemplate, char p1, int p2) {
246    if (!b) {
247      throw new IllegalArgumentException(lenientFormat(errorMessageTemplate, p1, p2));
248    }
249  }
250
251  /**
252   * Ensures the truth of an expression involving one or more parameters to the calling method.
253   *
254   * <p>See {@link #checkArgument(boolean, String, Object...)} for details.
255   *
256   * @since 20.0 (varargs overload since 2.0)
257   */
258  public static void checkArgument(
259      boolean b, @NullableDecl String errorMessageTemplate, char p1, long p2) {
260    if (!b) {
261      throw new IllegalArgumentException(lenientFormat(errorMessageTemplate, p1, p2));
262    }
263  }
264
265  /**
266   * Ensures the truth of an expression involving one or more parameters to the calling method.
267   *
268   * <p>See {@link #checkArgument(boolean, String, Object...)} for details.
269   *
270   * @since 20.0 (varargs overload since 2.0)
271   */
272  public static void checkArgument(
273      boolean b, @NullableDecl String errorMessageTemplate, char p1, @NullableDecl Object p2) {
274    if (!b) {
275      throw new IllegalArgumentException(lenientFormat(errorMessageTemplate, p1, p2));
276    }
277  }
278
279  /**
280   * Ensures the truth of an expression involving one or more parameters to the calling method.
281   *
282   * <p>See {@link #checkArgument(boolean, String, Object...)} for details.
283   *
284   * @since 20.0 (varargs overload since 2.0)
285   */
286  public static void checkArgument(
287      boolean b, @NullableDecl String errorMessageTemplate, int p1, char p2) {
288    if (!b) {
289      throw new IllegalArgumentException(lenientFormat(errorMessageTemplate, p1, p2));
290    }
291  }
292
293  /**
294   * Ensures the truth of an expression involving one or more parameters to the calling method.
295   *
296   * <p>See {@link #checkArgument(boolean, String, Object...)} for details.
297   *
298   * @since 20.0 (varargs overload since 2.0)
299   */
300  public static void checkArgument(
301      boolean b, @NullableDecl String errorMessageTemplate, int p1, int p2) {
302    if (!b) {
303      throw new IllegalArgumentException(lenientFormat(errorMessageTemplate, p1, p2));
304    }
305  }
306
307  /**
308   * Ensures the truth of an expression involving one or more parameters to the calling method.
309   *
310   * <p>See {@link #checkArgument(boolean, String, Object...)} for details.
311   *
312   * @since 20.0 (varargs overload since 2.0)
313   */
314  public static void checkArgument(
315      boolean b, @NullableDecl String errorMessageTemplate, int p1, long p2) {
316    if (!b) {
317      throw new IllegalArgumentException(lenientFormat(errorMessageTemplate, p1, p2));
318    }
319  }
320
321  /**
322   * Ensures the truth of an expression involving one or more parameters to the calling method.
323   *
324   * <p>See {@link #checkArgument(boolean, String, Object...)} for details.
325   *
326   * @since 20.0 (varargs overload since 2.0)
327   */
328  public static void checkArgument(
329      boolean b, @NullableDecl String errorMessageTemplate, int p1, @NullableDecl Object p2) {
330    if (!b) {
331      throw new IllegalArgumentException(lenientFormat(errorMessageTemplate, p1, p2));
332    }
333  }
334
335  /**
336   * Ensures the truth of an expression involving one or more parameters to the calling method.
337   *
338   * <p>See {@link #checkArgument(boolean, String, Object...)} for details.
339   *
340   * @since 20.0 (varargs overload since 2.0)
341   */
342  public static void checkArgument(
343      boolean b, @NullableDecl String errorMessageTemplate, long p1, char p2) {
344    if (!b) {
345      throw new IllegalArgumentException(lenientFormat(errorMessageTemplate, p1, p2));
346    }
347  }
348
349  /**
350   * Ensures the truth of an expression involving one or more parameters to the calling method.
351   *
352   * <p>See {@link #checkArgument(boolean, String, Object...)} for details.
353   *
354   * @since 20.0 (varargs overload since 2.0)
355   */
356  public static void checkArgument(
357      boolean b, @NullableDecl String errorMessageTemplate, long p1, int p2) {
358    if (!b) {
359      throw new IllegalArgumentException(lenientFormat(errorMessageTemplate, p1, p2));
360    }
361  }
362
363  /**
364   * Ensures the truth of an expression involving one or more parameters to the calling method.
365   *
366   * <p>See {@link #checkArgument(boolean, String, Object...)} for details.
367   *
368   * @since 20.0 (varargs overload since 2.0)
369   */
370  public static void checkArgument(
371      boolean b, @NullableDecl String errorMessageTemplate, long p1, long p2) {
372    if (!b) {
373      throw new IllegalArgumentException(lenientFormat(errorMessageTemplate, p1, p2));
374    }
375  }
376
377  /**
378   * Ensures the truth of an expression involving one or more parameters to the calling method.
379   *
380   * <p>See {@link #checkArgument(boolean, String, Object...)} for details.
381   *
382   * @since 20.0 (varargs overload since 2.0)
383   */
384  public static void checkArgument(
385      boolean b, @NullableDecl String errorMessageTemplate, long p1, @NullableDecl Object p2) {
386    if (!b) {
387      throw new IllegalArgumentException(lenientFormat(errorMessageTemplate, p1, p2));
388    }
389  }
390
391  /**
392   * Ensures the truth of an expression involving one or more parameters to the calling method.
393   *
394   * <p>See {@link #checkArgument(boolean, String, Object...)} for details.
395   *
396   * @since 20.0 (varargs overload since 2.0)
397   */
398  public static void checkArgument(
399      boolean b, @NullableDecl String errorMessageTemplate, @NullableDecl Object p1, char p2) {
400    if (!b) {
401      throw new IllegalArgumentException(lenientFormat(errorMessageTemplate, p1, p2));
402    }
403  }
404
405  /**
406   * Ensures the truth of an expression involving one or more parameters to the calling method.
407   *
408   * <p>See {@link #checkArgument(boolean, String, Object...)} for details.
409   *
410   * @since 20.0 (varargs overload since 2.0)
411   */
412  public static void checkArgument(
413      boolean b, @NullableDecl String errorMessageTemplate, @NullableDecl Object p1, int p2) {
414    if (!b) {
415      throw new IllegalArgumentException(lenientFormat(errorMessageTemplate, p1, p2));
416    }
417  }
418
419  /**
420   * Ensures the truth of an expression involving one or more parameters to the calling method.
421   *
422   * <p>See {@link #checkArgument(boolean, String, Object...)} for details.
423   *
424   * @since 20.0 (varargs overload since 2.0)
425   */
426  public static void checkArgument(
427      boolean b, @NullableDecl String errorMessageTemplate, @NullableDecl Object p1, long p2) {
428    if (!b) {
429      throw new IllegalArgumentException(lenientFormat(errorMessageTemplate, p1, p2));
430    }
431  }
432
433  /**
434   * Ensures the truth of an expression involving one or more parameters to the calling method.
435   *
436   * <p>See {@link #checkArgument(boolean, String, Object...)} for details.
437   *
438   * @since 20.0 (varargs overload since 2.0)
439   */
440  public static void checkArgument(
441      boolean b,
442      @NullableDecl String errorMessageTemplate,
443      @NullableDecl Object p1,
444      @NullableDecl Object p2) {
445    if (!b) {
446      throw new IllegalArgumentException(lenientFormat(errorMessageTemplate, p1, p2));
447    }
448  }
449
450  /**
451   * Ensures the truth of an expression involving one or more parameters to the calling method.
452   *
453   * <p>See {@link #checkArgument(boolean, String, Object...)} for details.
454   *
455   * @since 20.0 (varargs overload since 2.0)
456   */
457  public static void checkArgument(
458      boolean b,
459      @NullableDecl String errorMessageTemplate,
460      @NullableDecl Object p1,
461      @NullableDecl Object p2,
462      @NullableDecl Object p3) {
463    if (!b) {
464      throw new IllegalArgumentException(lenientFormat(errorMessageTemplate, p1, p2, p3));
465    }
466  }
467
468  /**
469   * Ensures the truth of an expression involving one or more parameters to the calling method.
470   *
471   * <p>See {@link #checkArgument(boolean, String, Object...)} for details.
472   *
473   * @since 20.0 (varargs overload since 2.0)
474   */
475  public static void checkArgument(
476      boolean b,
477      @NullableDecl String errorMessageTemplate,
478      @NullableDecl Object p1,
479      @NullableDecl Object p2,
480      @NullableDecl Object p3,
481      @NullableDecl Object p4) {
482    if (!b) {
483      throw new IllegalArgumentException(lenientFormat(errorMessageTemplate, p1, p2, p3, p4));
484    }
485  }
486
487  /**
488   * Ensures the truth of an expression involving the state of the calling instance, but not
489   * involving any parameters to the calling method.
490   *
491   * @param expression a boolean expression
492   * @throws IllegalStateException if {@code expression} is false
493   * @see Verify#verify Verify.verify()
494   */
495  public static void checkState(boolean expression) {
496    if (!expression) {
497      throw new IllegalStateException();
498    }
499  }
500
501  /**
502   * Ensures the truth of an expression involving the state of the calling instance, but not
503   * involving any parameters to the calling method.
504   *
505   * @param expression a boolean expression
506   * @param errorMessage the exception message to use if the check fails; will be converted to a
507   *     string using {@link String#valueOf(Object)}
508   * @throws IllegalStateException if {@code expression} is false
509   * @see Verify#verify Verify.verify()
510   */
511  public static void checkState(boolean expression, @NullableDecl Object errorMessage) {
512    if (!expression) {
513      throw new IllegalStateException(String.valueOf(errorMessage));
514    }
515  }
516
517  /**
518   * Ensures the truth of an expression involving the state of the calling instance, but not
519   * involving any parameters to the calling method.
520   *
521   * @param expression a boolean expression
522   * @param errorMessageTemplate a template for the exception message should the check fail. The
523   *     message is formed by replacing each {@code %s} placeholder in the template with an
524   *     argument. These are matched by position - the first {@code %s} gets {@code
525   *     errorMessageArgs[0]}, etc. Unmatched arguments will be appended to the formatted message in
526   *     square braces. Unmatched placeholders will be left as-is.
527   * @param errorMessageArgs the arguments to be substituted into the message template. Arguments
528   *     are converted to strings using {@link String#valueOf(Object)}.
529   * @throws IllegalStateException if {@code expression} is false
530   * @see Verify#verify Verify.verify()
531   */
532  public static void checkState(
533      boolean expression,
534      @NullableDecl String errorMessageTemplate,
535      @NullableDecl Object... errorMessageArgs) {
536    if (!expression) {
537      throw new IllegalStateException(lenientFormat(errorMessageTemplate, errorMessageArgs));
538    }
539  }
540
541  /**
542   * Ensures the truth of an expression involving the state of the calling instance, but not
543   * involving any parameters to the calling method.
544   *
545   * <p>See {@link #checkState(boolean, String, Object...)} for details.
546   *
547   * @since 20.0 (varargs overload since 2.0)
548   */
549  public static void checkState(boolean b, @NullableDecl String errorMessageTemplate, char p1) {
550    if (!b) {
551      throw new IllegalStateException(lenientFormat(errorMessageTemplate, p1));
552    }
553  }
554
555  /**
556   * Ensures the truth of an expression involving the state of the calling instance, but not
557   * involving any parameters to the calling method.
558   *
559   * <p>See {@link #checkState(boolean, String, Object...)} for details.
560   *
561   * @since 20.0 (varargs overload since 2.0)
562   */
563  public static void checkState(boolean b, @NullableDecl String errorMessageTemplate, int p1) {
564    if (!b) {
565      throw new IllegalStateException(lenientFormat(errorMessageTemplate, p1));
566    }
567  }
568
569  /**
570   * Ensures the truth of an expression involving the state of the calling instance, but not
571   * involving any parameters to the calling method.
572   *
573   * <p>See {@link #checkState(boolean, String, Object...)} for details.
574   *
575   * @since 20.0 (varargs overload since 2.0)
576   */
577  public static void checkState(boolean b, @NullableDecl String errorMessageTemplate, long p1) {
578    if (!b) {
579      throw new IllegalStateException(lenientFormat(errorMessageTemplate, p1));
580    }
581  }
582
583  /**
584   * Ensures the truth of an expression involving the state of the calling instance, but not
585   * involving any parameters to the calling method.
586   *
587   * <p>See {@link #checkState(boolean, String, Object...)} for details.
588   *
589   * @since 20.0 (varargs overload since 2.0)
590   */
591  public static void checkState(
592      boolean b, @NullableDecl String errorMessageTemplate, @NullableDecl Object p1) {
593    if (!b) {
594      throw new IllegalStateException(lenientFormat(errorMessageTemplate, p1));
595    }
596  }
597
598  /**
599   * Ensures the truth of an expression involving the state of the calling instance, but not
600   * involving any parameters to the calling method.
601   *
602   * <p>See {@link #checkState(boolean, String, Object...)} for details.
603   *
604   * @since 20.0 (varargs overload since 2.0)
605   */
606  public static void checkState(
607      boolean b, @NullableDecl String errorMessageTemplate, char p1, char p2) {
608    if (!b) {
609      throw new IllegalStateException(lenientFormat(errorMessageTemplate, p1, p2));
610    }
611  }
612
613  /**
614   * Ensures the truth of an expression involving the state of the calling instance, but not
615   * involving any parameters to the calling method.
616   *
617   * <p>See {@link #checkState(boolean, String, Object...)} for details.
618   *
619   * @since 20.0 (varargs overload since 2.0)
620   */
621  public static void checkState(
622      boolean b, @NullableDecl String errorMessageTemplate, char p1, int p2) {
623    if (!b) {
624      throw new IllegalStateException(lenientFormat(errorMessageTemplate, p1, p2));
625    }
626  }
627
628  /**
629   * Ensures the truth of an expression involving the state of the calling instance, but not
630   * involving any parameters to the calling method.
631   *
632   * <p>See {@link #checkState(boolean, String, Object...)} for details.
633   *
634   * @since 20.0 (varargs overload since 2.0)
635   */
636  public static void checkState(
637      boolean b, @NullableDecl String errorMessageTemplate, char p1, long p2) {
638    if (!b) {
639      throw new IllegalStateException(lenientFormat(errorMessageTemplate, p1, p2));
640    }
641  }
642
643  /**
644   * Ensures the truth of an expression involving the state of the calling instance, but not
645   * involving any parameters to the calling method.
646   *
647   * <p>See {@link #checkState(boolean, String, Object...)} for details.
648   *
649   * @since 20.0 (varargs overload since 2.0)
650   */
651  public static void checkState(
652      boolean b, @NullableDecl String errorMessageTemplate, char p1, @NullableDecl Object p2) {
653    if (!b) {
654      throw new IllegalStateException(lenientFormat(errorMessageTemplate, p1, p2));
655    }
656  }
657
658  /**
659   * Ensures the truth of an expression involving the state of the calling instance, but not
660   * involving any parameters to the calling method.
661   *
662   * <p>See {@link #checkState(boolean, String, Object...)} for details.
663   *
664   * @since 20.0 (varargs overload since 2.0)
665   */
666  public static void checkState(
667      boolean b, @NullableDecl String errorMessageTemplate, int p1, char p2) {
668    if (!b) {
669      throw new IllegalStateException(lenientFormat(errorMessageTemplate, p1, p2));
670    }
671  }
672
673  /**
674   * Ensures the truth of an expression involving the state of the calling instance, but not
675   * involving any parameters to the calling method.
676   *
677   * <p>See {@link #checkState(boolean, String, Object...)} for details.
678   *
679   * @since 20.0 (varargs overload since 2.0)
680   */
681  public static void checkState(
682      boolean b, @NullableDecl String errorMessageTemplate, int p1, int p2) {
683    if (!b) {
684      throw new IllegalStateException(lenientFormat(errorMessageTemplate, p1, p2));
685    }
686  }
687
688  /**
689   * Ensures the truth of an expression involving the state of the calling instance, but not
690   * involving any parameters to the calling method.
691   *
692   * <p>See {@link #checkState(boolean, String, Object...)} for details.
693   *
694   * @since 20.0 (varargs overload since 2.0)
695   */
696  public static void checkState(
697      boolean b, @NullableDecl String errorMessageTemplate, int p1, long p2) {
698    if (!b) {
699      throw new IllegalStateException(lenientFormat(errorMessageTemplate, p1, p2));
700    }
701  }
702
703  /**
704   * Ensures the truth of an expression involving the state of the calling instance, but not
705   * involving any parameters to the calling method.
706   *
707   * <p>See {@link #checkState(boolean, String, Object...)} for details.
708   *
709   * @since 20.0 (varargs overload since 2.0)
710   */
711  public static void checkState(
712      boolean b, @NullableDecl String errorMessageTemplate, int p1, @NullableDecl Object p2) {
713    if (!b) {
714      throw new IllegalStateException(lenientFormat(errorMessageTemplate, p1, p2));
715    }
716  }
717
718  /**
719   * Ensures the truth of an expression involving the state of the calling instance, but not
720   * involving any parameters to the calling method.
721   *
722   * <p>See {@link #checkState(boolean, String, Object...)} for details.
723   *
724   * @since 20.0 (varargs overload since 2.0)
725   */
726  public static void checkState(
727      boolean b, @NullableDecl String errorMessageTemplate, long p1, char p2) {
728    if (!b) {
729      throw new IllegalStateException(lenientFormat(errorMessageTemplate, p1, p2));
730    }
731  }
732
733  /**
734   * Ensures the truth of an expression involving the state of the calling instance, but not
735   * involving any parameters to the calling method.
736   *
737   * <p>See {@link #checkState(boolean, String, Object...)} for details.
738   *
739   * @since 20.0 (varargs overload since 2.0)
740   */
741  public static void checkState(
742      boolean b, @NullableDecl String errorMessageTemplate, long p1, int p2) {
743    if (!b) {
744      throw new IllegalStateException(lenientFormat(errorMessageTemplate, p1, p2));
745    }
746  }
747
748  /**
749   * Ensures the truth of an expression involving the state of the calling instance, but not
750   * involving any parameters to the calling method.
751   *
752   * <p>See {@link #checkState(boolean, String, Object...)} for details.
753   *
754   * @since 20.0 (varargs overload since 2.0)
755   */
756  public static void checkState(
757      boolean b, @NullableDecl String errorMessageTemplate, long p1, long p2) {
758    if (!b) {
759      throw new IllegalStateException(lenientFormat(errorMessageTemplate, p1, p2));
760    }
761  }
762
763  /**
764   * Ensures the truth of an expression involving the state of the calling instance, but not
765   * involving any parameters to the calling method.
766   *
767   * <p>See {@link #checkState(boolean, String, Object...)} for details.
768   *
769   * @since 20.0 (varargs overload since 2.0)
770   */
771  public static void checkState(
772      boolean b, @NullableDecl String errorMessageTemplate, long p1, @NullableDecl Object p2) {
773    if (!b) {
774      throw new IllegalStateException(lenientFormat(errorMessageTemplate, p1, p2));
775    }
776  }
777
778  /**
779   * Ensures the truth of an expression involving the state of the calling instance, but not
780   * involving any parameters to the calling method.
781   *
782   * <p>See {@link #checkState(boolean, String, Object...)} for details.
783   *
784   * @since 20.0 (varargs overload since 2.0)
785   */
786  public static void checkState(
787      boolean b, @NullableDecl String errorMessageTemplate, @NullableDecl Object p1, char p2) {
788    if (!b) {
789      throw new IllegalStateException(lenientFormat(errorMessageTemplate, p1, p2));
790    }
791  }
792
793  /**
794   * Ensures the truth of an expression involving the state of the calling instance, but not
795   * involving any parameters to the calling method.
796   *
797   * <p>See {@link #checkState(boolean, String, Object...)} for details.
798   *
799   * @since 20.0 (varargs overload since 2.0)
800   */
801  public static void checkState(
802      boolean b, @NullableDecl String errorMessageTemplate, @NullableDecl Object p1, int p2) {
803    if (!b) {
804      throw new IllegalStateException(lenientFormat(errorMessageTemplate, p1, p2));
805    }
806  }
807
808  /**
809   * Ensures the truth of an expression involving the state of the calling instance, but not
810   * involving any parameters to the calling method.
811   *
812   * <p>See {@link #checkState(boolean, String, Object...)} for details.
813   *
814   * @since 20.0 (varargs overload since 2.0)
815   */
816  public static void checkState(
817      boolean b, @NullableDecl String errorMessageTemplate, @NullableDecl Object p1, long p2) {
818    if (!b) {
819      throw new IllegalStateException(lenientFormat(errorMessageTemplate, p1, p2));
820    }
821  }
822
823  /**
824   * Ensures the truth of an expression involving the state of the calling instance, but not
825   * involving any parameters to the calling method.
826   *
827   * <p>See {@link #checkState(boolean, String, Object...)} for details.
828   *
829   * @since 20.0 (varargs overload since 2.0)
830   */
831  public static void checkState(
832      boolean b,
833      @NullableDecl String errorMessageTemplate,
834      @NullableDecl Object p1,
835      @NullableDecl Object p2) {
836    if (!b) {
837      throw new IllegalStateException(lenientFormat(errorMessageTemplate, p1, p2));
838    }
839  }
840
841  /**
842   * Ensures the truth of an expression involving the state of the calling instance, but not
843   * involving any parameters to the calling method.
844   *
845   * <p>See {@link #checkState(boolean, String, Object...)} for details.
846   *
847   * @since 20.0 (varargs overload since 2.0)
848   */
849  public static void checkState(
850      boolean b,
851      @NullableDecl String errorMessageTemplate,
852      @NullableDecl Object p1,
853      @NullableDecl Object p2,
854      @NullableDecl Object p3) {
855    if (!b) {
856      throw new IllegalStateException(lenientFormat(errorMessageTemplate, p1, p2, p3));
857    }
858  }
859
860  /**
861   * Ensures the truth of an expression involving the state of the calling instance, but not
862   * involving any parameters to the calling method.
863   *
864   * <p>See {@link #checkState(boolean, String, Object...)} for details.
865   *
866   * @since 20.0 (varargs overload since 2.0)
867   */
868  public static void checkState(
869      boolean b,
870      @NullableDecl String errorMessageTemplate,
871      @NullableDecl Object p1,
872      @NullableDecl Object p2,
873      @NullableDecl Object p3,
874      @NullableDecl Object p4) {
875    if (!b) {
876      throw new IllegalStateException(lenientFormat(errorMessageTemplate, p1, p2, p3, p4));
877    }
878  }
879
880  /**
881   * Ensures that an object reference passed as a parameter to the calling method is not null.
882   *
883   * @param reference an object reference
884   * @return the non-null reference that was validated
885   * @throws NullPointerException if {@code reference} is null
886   * @see Verify#verifyNotNull Verify.verifyNotNull()
887   */
888  @CanIgnoreReturnValue
889  @NonNullDecl
890  public static <T extends Object> T checkNotNull(@NonNullDecl T reference) {
891    if (reference == null) {
892      throw new NullPointerException();
893    }
894    return reference;
895  }
896
897  /**
898   * Ensures that an object reference passed as a parameter to the calling method is not null.
899   *
900   * @param reference an object reference
901   * @param errorMessage the exception message to use if the check fails; will be converted to a
902   *     string using {@link String#valueOf(Object)}
903   * @return the non-null reference that was validated
904   * @throws NullPointerException if {@code reference} is null
905   * @see Verify#verifyNotNull Verify.verifyNotNull()
906   */
907  @CanIgnoreReturnValue
908  @NonNullDecl
909  public static <T extends Object> T checkNotNull(
910      @NonNullDecl T reference, @NullableDecl Object errorMessage) {
911    if (reference == null) {
912      throw new NullPointerException(String.valueOf(errorMessage));
913    }
914    return reference;
915  }
916
917  /**
918   * Ensures that an object reference passed as a parameter to the calling method is not null.
919   *
920   * @param reference an object reference
921   * @param errorMessageTemplate a template for the exception message should the check fail. The
922   *     message is formed by replacing each {@code %s} placeholder in the template with an
923   *     argument. These are matched by position - the first {@code %s} gets {@code
924   *     errorMessageArgs[0]}, etc. Unmatched arguments will be appended to the formatted message in
925   *     square braces. Unmatched placeholders will be left as-is.
926   * @param errorMessageArgs the arguments to be substituted into the message template. Arguments
927   *     are converted to strings using {@link String#valueOf(Object)}.
928   * @return the non-null reference that was validated
929   * @throws NullPointerException if {@code reference} is null
930   * @see Verify#verifyNotNull Verify.verifyNotNull()
931   */
932  @CanIgnoreReturnValue
933  @NonNullDecl
934  public static <T extends Object> T checkNotNull(
935      @NonNullDecl T reference,
936      @NullableDecl String errorMessageTemplate,
937      @NullableDecl Object... errorMessageArgs) {
938    if (reference == null) {
939      throw new NullPointerException(lenientFormat(errorMessageTemplate, errorMessageArgs));
940    }
941    return reference;
942  }
943
944  /**
945   * Ensures that an object reference passed as a parameter to the calling method is not null.
946   *
947   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
948   *
949   * @since 20.0 (varargs overload since 2.0)
950   */
951  @CanIgnoreReturnValue
952  @NonNullDecl
953  public static <T extends Object> T checkNotNull(
954      @NonNullDecl T obj, @NullableDecl String errorMessageTemplate, char p1) {
955    if (obj == null) {
956      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1));
957    }
958    return obj;
959  }
960
961  /**
962   * Ensures that an object reference passed as a parameter to the calling method is not null.
963   *
964   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
965   *
966   * @since 20.0 (varargs overload since 2.0)
967   */
968  @CanIgnoreReturnValue
969  @NonNullDecl
970  public static <T extends Object> T checkNotNull(
971      @NonNullDecl T obj, @NullableDecl String errorMessageTemplate, int p1) {
972    if (obj == null) {
973      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1));
974    }
975    return obj;
976  }
977
978  /**
979   * Ensures that an object reference passed as a parameter to the calling method is not null.
980   *
981   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
982   *
983   * @since 20.0 (varargs overload since 2.0)
984   */
985  @CanIgnoreReturnValue
986  @NonNullDecl
987  public static <T extends Object> T checkNotNull(
988      @NonNullDecl T obj, @NullableDecl String errorMessageTemplate, long p1) {
989    if (obj == null) {
990      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1));
991    }
992    return obj;
993  }
994
995  /**
996   * Ensures that an object reference passed as a parameter to the calling method is not null.
997   *
998   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
999   *
1000   * @since 20.0 (varargs overload since 2.0)
1001   */
1002  @CanIgnoreReturnValue
1003  @NonNullDecl
1004  public static <T extends Object> T checkNotNull(
1005      @NonNullDecl T obj, @NullableDecl String errorMessageTemplate, @NullableDecl Object p1) {
1006    if (obj == null) {
1007      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1));
1008    }
1009    return obj;
1010  }
1011
1012  /**
1013   * Ensures that an object reference passed as a parameter to the calling method is not null.
1014   *
1015   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1016   *
1017   * @since 20.0 (varargs overload since 2.0)
1018   */
1019  @CanIgnoreReturnValue
1020  @NonNullDecl
1021  public static <T extends Object> T checkNotNull(
1022      @NonNullDecl T obj, @NullableDecl String errorMessageTemplate, char p1, char p2) {
1023    if (obj == null) {
1024      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2));
1025    }
1026    return obj;
1027  }
1028
1029  /**
1030   * Ensures that an object reference passed as a parameter to the calling method is not null.
1031   *
1032   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1033   *
1034   * @since 20.0 (varargs overload since 2.0)
1035   */
1036  @CanIgnoreReturnValue
1037  @NonNullDecl
1038  public static <T extends Object> T checkNotNull(
1039      @NonNullDecl T obj, @NullableDecl String errorMessageTemplate, char p1, int p2) {
1040    if (obj == null) {
1041      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2));
1042    }
1043    return obj;
1044  }
1045
1046  /**
1047   * Ensures that an object reference passed as a parameter to the calling method is not null.
1048   *
1049   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1050   *
1051   * @since 20.0 (varargs overload since 2.0)
1052   */
1053  @CanIgnoreReturnValue
1054  @NonNullDecl
1055  public static <T extends Object> T checkNotNull(
1056      @NonNullDecl T obj, @NullableDecl String errorMessageTemplate, char p1, long p2) {
1057    if (obj == null) {
1058      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2));
1059    }
1060    return obj;
1061  }
1062
1063  /**
1064   * Ensures that an object reference passed as a parameter to the calling method is not null.
1065   *
1066   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1067   *
1068   * @since 20.0 (varargs overload since 2.0)
1069   */
1070  @CanIgnoreReturnValue
1071  @NonNullDecl
1072  public static <T extends Object> T checkNotNull(
1073      @NonNullDecl T obj,
1074      @NullableDecl String errorMessageTemplate,
1075      char p1,
1076      @NullableDecl Object p2) {
1077    if (obj == null) {
1078      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2));
1079    }
1080    return obj;
1081  }
1082
1083  /**
1084   * Ensures that an object reference passed as a parameter to the calling method is not null.
1085   *
1086   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1087   *
1088   * @since 20.0 (varargs overload since 2.0)
1089   */
1090  @CanIgnoreReturnValue
1091  @NonNullDecl
1092  public static <T extends Object> T checkNotNull(
1093      @NonNullDecl T obj, @NullableDecl String errorMessageTemplate, int p1, char p2) {
1094    if (obj == null) {
1095      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2));
1096    }
1097    return obj;
1098  }
1099
1100  /**
1101   * Ensures that an object reference passed as a parameter to the calling method is not null.
1102   *
1103   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1104   *
1105   * @since 20.0 (varargs overload since 2.0)
1106   */
1107  @CanIgnoreReturnValue
1108  @NonNullDecl
1109  public static <T extends Object> T checkNotNull(
1110      @NonNullDecl T obj, @NullableDecl String errorMessageTemplate, int p1, int p2) {
1111    if (obj == null) {
1112      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2));
1113    }
1114    return obj;
1115  }
1116
1117  /**
1118   * Ensures that an object reference passed as a parameter to the calling method is not null.
1119   *
1120   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1121   *
1122   * @since 20.0 (varargs overload since 2.0)
1123   */
1124  @CanIgnoreReturnValue
1125  @NonNullDecl
1126  public static <T extends Object> T checkNotNull(
1127      @NonNullDecl T obj, @NullableDecl String errorMessageTemplate, int p1, long p2) {
1128    if (obj == null) {
1129      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2));
1130    }
1131    return obj;
1132  }
1133
1134  /**
1135   * Ensures that an object reference passed as a parameter to the calling method is not null.
1136   *
1137   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1138   *
1139   * @since 20.0 (varargs overload since 2.0)
1140   */
1141  @CanIgnoreReturnValue
1142  @NonNullDecl
1143  public static <T extends Object> T checkNotNull(
1144      @NonNullDecl T obj,
1145      @NullableDecl String errorMessageTemplate,
1146      int p1,
1147      @NullableDecl Object p2) {
1148    if (obj == null) {
1149      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2));
1150    }
1151    return obj;
1152  }
1153
1154  /**
1155   * Ensures that an object reference passed as a parameter to the calling method is not null.
1156   *
1157   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1158   *
1159   * @since 20.0 (varargs overload since 2.0)
1160   */
1161  @CanIgnoreReturnValue
1162  @NonNullDecl
1163  public static <T extends Object> T checkNotNull(
1164      @NonNullDecl T obj, @NullableDecl String errorMessageTemplate, long p1, char p2) {
1165    if (obj == null) {
1166      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2));
1167    }
1168    return obj;
1169  }
1170
1171  /**
1172   * Ensures that an object reference passed as a parameter to the calling method is not null.
1173   *
1174   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1175   *
1176   * @since 20.0 (varargs overload since 2.0)
1177   */
1178  @CanIgnoreReturnValue
1179  @NonNullDecl
1180  public static <T extends Object> T checkNotNull(
1181      @NonNullDecl T obj, @NullableDecl String errorMessageTemplate, long p1, int p2) {
1182    if (obj == null) {
1183      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2));
1184    }
1185    return obj;
1186  }
1187
1188  /**
1189   * Ensures that an object reference passed as a parameter to the calling method is not null.
1190   *
1191   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1192   *
1193   * @since 20.0 (varargs overload since 2.0)
1194   */
1195  @CanIgnoreReturnValue
1196  @NonNullDecl
1197  public static <T extends Object> T checkNotNull(
1198      @NonNullDecl T obj, @NullableDecl String errorMessageTemplate, long p1, long p2) {
1199    if (obj == null) {
1200      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2));
1201    }
1202    return obj;
1203  }
1204
1205  /**
1206   * Ensures that an object reference passed as a parameter to the calling method is not null.
1207   *
1208   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1209   *
1210   * @since 20.0 (varargs overload since 2.0)
1211   */
1212  @CanIgnoreReturnValue
1213  @NonNullDecl
1214  public static <T extends Object> T checkNotNull(
1215      @NonNullDecl T obj,
1216      @NullableDecl String errorMessageTemplate,
1217      long p1,
1218      @NullableDecl Object p2) {
1219    if (obj == null) {
1220      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2));
1221    }
1222    return obj;
1223  }
1224
1225  /**
1226   * Ensures that an object reference passed as a parameter to the calling method is not null.
1227   *
1228   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1229   *
1230   * @since 20.0 (varargs overload since 2.0)
1231   */
1232  @CanIgnoreReturnValue
1233  @NonNullDecl
1234  public static <T extends Object> T checkNotNull(
1235      @NonNullDecl T obj,
1236      @NullableDecl String errorMessageTemplate,
1237      @NullableDecl Object p1,
1238      char p2) {
1239    if (obj == null) {
1240      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2));
1241    }
1242    return obj;
1243  }
1244
1245  /**
1246   * Ensures that an object reference passed as a parameter to the calling method is not null.
1247   *
1248   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1249   *
1250   * @since 20.0 (varargs overload since 2.0)
1251   */
1252  @CanIgnoreReturnValue
1253  @NonNullDecl
1254  public static <T extends Object> T checkNotNull(
1255      @NonNullDecl T obj,
1256      @NullableDecl String errorMessageTemplate,
1257      @NullableDecl Object p1,
1258      int p2) {
1259    if (obj == null) {
1260      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2));
1261    }
1262    return obj;
1263  }
1264
1265  /**
1266   * Ensures that an object reference passed as a parameter to the calling method is not null.
1267   *
1268   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1269   *
1270   * @since 20.0 (varargs overload since 2.0)
1271   */
1272  @CanIgnoreReturnValue
1273  @NonNullDecl
1274  public static <T extends Object> T checkNotNull(
1275      @NonNullDecl T obj,
1276      @NullableDecl String errorMessageTemplate,
1277      @NullableDecl Object p1,
1278      long p2) {
1279    if (obj == null) {
1280      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2));
1281    }
1282    return obj;
1283  }
1284
1285  /**
1286   * Ensures that an object reference passed as a parameter to the calling method is not null.
1287   *
1288   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1289   *
1290   * @since 20.0 (varargs overload since 2.0)
1291   */
1292  @CanIgnoreReturnValue
1293  @NonNullDecl
1294  public static <T extends Object> T checkNotNull(
1295      @NonNullDecl T obj,
1296      @NullableDecl String errorMessageTemplate,
1297      @NullableDecl Object p1,
1298      @NullableDecl Object p2) {
1299    if (obj == null) {
1300      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2));
1301    }
1302    return obj;
1303  }
1304
1305  /**
1306   * Ensures that an object reference passed as a parameter to the calling method is not null.
1307   *
1308   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1309   *
1310   * @since 20.0 (varargs overload since 2.0)
1311   */
1312  @CanIgnoreReturnValue
1313  @NonNullDecl
1314  public static <T extends Object> T checkNotNull(
1315      @NonNullDecl T obj,
1316      @NullableDecl String errorMessageTemplate,
1317      @NullableDecl Object p1,
1318      @NullableDecl Object p2,
1319      @NullableDecl Object p3) {
1320    if (obj == null) {
1321      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2, p3));
1322    }
1323    return obj;
1324  }
1325
1326  /**
1327   * Ensures that an object reference passed as a parameter to the calling method is not null.
1328   *
1329   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1330   *
1331   * @since 20.0 (varargs overload since 2.0)
1332   */
1333  @CanIgnoreReturnValue
1334  @NonNullDecl
1335  public static <T extends Object> T checkNotNull(
1336      @NonNullDecl T obj,
1337      @NullableDecl String errorMessageTemplate,
1338      @NullableDecl Object p1,
1339      @NullableDecl Object p2,
1340      @NullableDecl Object p3,
1341      @NullableDecl Object p4) {
1342    if (obj == null) {
1343      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2, p3, p4));
1344    }
1345    return obj;
1346  }
1347
1348  /*
1349   * All recent hotspots (as of 2009) *really* like to have the natural code
1350   *
1351   * if (guardExpression) {
1352   *    throw new BadException(messageExpression);
1353   * }
1354   *
1355   * refactored so that messageExpression is moved to a separate String-returning method.
1356   *
1357   * if (guardExpression) {
1358   *    throw new BadException(badMsg(...));
1359   * }
1360   *
1361   * The alternative natural refactorings into void or Exception-returning methods are much slower.
1362   * This is a big deal - we're talking factors of 2-8 in microbenchmarks, not just 10-20%. (This is
1363   * a hotspot optimizer bug, which should be fixed, but that's a separate, big project).
1364   *
1365   * The coding pattern above is heavily used in java.util, e.g. in ArrayList. There is a
1366   * RangeCheckMicroBenchmark in the JDK that was used to test this.
1367   *
1368   * But the methods in this class want to throw different exceptions, depending on the args, so it
1369   * appears that this pattern is not directly applicable. But we can use the ridiculous, devious
1370   * trick of throwing an exception in the middle of the construction of another exception. Hotspot
1371   * is fine with that.
1372   */
1373
1374  /**
1375   * Ensures that {@code index} specifies a valid <i>element</i> in an array, list or string of size
1376   * {@code size}. An element index may range from zero, inclusive, to {@code size}, exclusive.
1377   *
1378   * @param index a user-supplied index identifying an element of an array, list or string
1379   * @param size the size of that array, list or string
1380   * @return the value of {@code index}
1381   * @throws IndexOutOfBoundsException if {@code index} is negative or is not less than {@code size}
1382   * @throws IllegalArgumentException if {@code size} is negative
1383   */
1384  @CanIgnoreReturnValue
1385  public static int checkElementIndex(int index, int size) {
1386    return checkElementIndex(index, size, "index");
1387  }
1388
1389  /**
1390   * Ensures that {@code index} specifies a valid <i>element</i> in an array, list or string of size
1391   * {@code size}. An element index may range from zero, inclusive, to {@code size}, exclusive.
1392   *
1393   * @param index a user-supplied index identifying an element of an array, list or string
1394   * @param size the size of that array, list or string
1395   * @param desc the text to use to describe this index in an error message
1396   * @return the value of {@code index}
1397   * @throws IndexOutOfBoundsException if {@code index} is negative or is not less than {@code size}
1398   * @throws IllegalArgumentException if {@code size} is negative
1399   */
1400  @CanIgnoreReturnValue
1401  public static int checkElementIndex(int index, int size, @NullableDecl String desc) {
1402    // Carefully optimized for execution by hotspot (explanatory comment above)
1403    if (index < 0 || index >= size) {
1404      throw new IndexOutOfBoundsException(badElementIndex(index, size, desc));
1405    }
1406    return index;
1407  }
1408
1409  private static String badElementIndex(int index, int size, @NullableDecl String desc) {
1410    if (index < 0) {
1411      return lenientFormat("%s (%s) must not be negative", desc, index);
1412    } else if (size < 0) {
1413      throw new IllegalArgumentException("negative size: " + size);
1414    } else { // index >= size
1415      return lenientFormat("%s (%s) must be less than size (%s)", desc, index, size);
1416    }
1417  }
1418
1419  /**
1420   * Ensures that {@code index} specifies a valid <i>position</i> in an array, list or string of
1421   * size {@code size}. A position index may range from zero to {@code size}, inclusive.
1422   *
1423   * @param index a user-supplied index identifying a position in an array, list or string
1424   * @param size the size of that array, list or string
1425   * @return the value of {@code index}
1426   * @throws IndexOutOfBoundsException if {@code index} is negative or is greater than {@code size}
1427   * @throws IllegalArgumentException if {@code size} is negative
1428   */
1429  @CanIgnoreReturnValue
1430  public static int checkPositionIndex(int index, int size) {
1431    return checkPositionIndex(index, size, "index");
1432  }
1433
1434  /**
1435   * Ensures that {@code index} specifies a valid <i>position</i> in an array, list or string of
1436   * size {@code size}. A position index may range from zero to {@code size}, inclusive.
1437   *
1438   * @param index a user-supplied index identifying a position in an array, list or string
1439   * @param size the size of that array, list or string
1440   * @param desc the text to use to describe this index in an error message
1441   * @return the value of {@code index}
1442   * @throws IndexOutOfBoundsException if {@code index} is negative or is greater than {@code size}
1443   * @throws IllegalArgumentException if {@code size} is negative
1444   */
1445  @CanIgnoreReturnValue
1446  public static int checkPositionIndex(int index, int size, @NullableDecl String desc) {
1447    // Carefully optimized for execution by hotspot (explanatory comment above)
1448    if (index < 0 || index > size) {
1449      throw new IndexOutOfBoundsException(badPositionIndex(index, size, desc));
1450    }
1451    return index;
1452  }
1453
1454  private static String badPositionIndex(int index, int size, @NullableDecl String desc) {
1455    if (index < 0) {
1456      return lenientFormat("%s (%s) must not be negative", desc, index);
1457    } else if (size < 0) {
1458      throw new IllegalArgumentException("negative size: " + size);
1459    } else { // index > size
1460      return lenientFormat("%s (%s) must not be greater than size (%s)", desc, index, size);
1461    }
1462  }
1463
1464  /**
1465   * Ensures that {@code start} and {@code end} specify valid <i>positions</i> in an array, list or
1466   * string of size {@code size}, and are in order. A position index may range from zero to {@code
1467   * size}, inclusive.
1468   *
1469   * @param start a user-supplied index identifying a starting position in an array, list or string
1470   * @param end a user-supplied index identifying an ending position in an array, list or string
1471   * @param size the size of that array, list or string
1472   * @throws IndexOutOfBoundsException if either index is negative or is greater than {@code size},
1473   *     or if {@code end} is less than {@code start}
1474   * @throws IllegalArgumentException if {@code size} is negative
1475   */
1476  public static void checkPositionIndexes(int start, int end, int size) {
1477    // Carefully optimized for execution by hotspot (explanatory comment above)
1478    if (start < 0 || end < start || end > size) {
1479      throw new IndexOutOfBoundsException(badPositionIndexes(start, end, size));
1480    }
1481  }
1482
1483  private static String badPositionIndexes(int start, int end, int size) {
1484    if (start < 0 || start > size) {
1485      return badPositionIndex(start, size, "start index");
1486    }
1487    if (end < 0 || end > size) {
1488      return badPositionIndex(end, size, "end index");
1489    }
1490    // end < start
1491    return lenientFormat("end index (%s) must not be less than start index (%s)", end, start);
1492  }
1493
1494  static {
1495    try {
1496      Java8Usage.performCheck();
1497    } catch (Throwable underlying) {
1498      Exception toLog =
1499          new Exception(
1500              "Guava will drop support for Java 7 in 2021. Please let us know if this will cause"
1501                  + " you problems: https://github.com/google/guava/issues/5269",
1502              underlying);
1503      Logger.getLogger(Preconditions.class.getName())
1504          .log(
1505              WARNING,
1506              "Java 7 compatibility warning: See https://github.com/google/guava/issues/5269",
1507              toLog);
1508    }
1509  }
1510}