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