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