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