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      @Nullable String errorMessageTemplate,
161      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 b, @Nullable String errorMessageTemplate, char p1) {
175    if (!b) {
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 b, @Nullable String errorMessageTemplate, int p1) {
188    if (!b) {
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 b, @Nullable String errorMessageTemplate, long p1) {
201    if (!b) {
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 b, @Nullable String errorMessageTemplate, @Nullable Object p1) {
215    if (!b) {
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 b, @Nullable String errorMessageTemplate, char p1, char p2) {
229    if (!b) {
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 b, @Nullable String errorMessageTemplate, char p1, int p2) {
243    if (!b) {
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 b, @Nullable String errorMessageTemplate, char p1, long p2) {
257    if (!b) {
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 b, @Nullable String errorMessageTemplate, char p1, @Nullable Object p2) {
271    if (!b) {
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 b, @Nullable String errorMessageTemplate, int p1, char p2) {
285    if (!b) {
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 b, @Nullable String errorMessageTemplate, int p1, int p2) {
299    if (!b) {
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 b, @Nullable String errorMessageTemplate, int p1, long p2) {
313    if (!b) {
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 b, @Nullable String errorMessageTemplate, int p1, @Nullable Object p2) {
327    if (!b) {
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 b, @Nullable String errorMessageTemplate, long p1, char p2) {
341    if (!b) {
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 b, @Nullable String errorMessageTemplate, long p1, int p2) {
355    if (!b) {
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 b, @Nullable String errorMessageTemplate, long p1, long p2) {
369    if (!b) {
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 b, @Nullable String errorMessageTemplate, long p1, @Nullable Object p2) {
383    if (!b) {
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 b, @Nullable String errorMessageTemplate, @Nullable Object p1, char p2) {
397    if (!b) {
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 b, @Nullable String errorMessageTemplate, @Nullable Object p1, int p2) {
411    if (!b) {
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 b, @Nullable String errorMessageTemplate, @Nullable Object p1, long p2) {
425    if (!b) {
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 b, @Nullable String errorMessageTemplate, @Nullable Object p1, @Nullable Object p2) {
439    if (!b) {
440      throw new IllegalArgumentException(lenientFormat(errorMessageTemplate, p1, p2));
441    }
442  }
443
444  /**
445   * Ensures the truth of an expression involving one or more parameters to the calling method.
446   *
447   * <p>See {@link #checkArgument(boolean, String, Object...)} for details.
448   *
449   * @since 20.0 (varargs overload since 2.0)
450   */
451  public static void checkArgument(
452      boolean b,
453      @Nullable String errorMessageTemplate,
454      @Nullable Object p1,
455      @Nullable Object p2,
456      @Nullable Object p3) {
457    if (!b) {
458      throw new IllegalArgumentException(lenientFormat(errorMessageTemplate, p1, p2, p3));
459    }
460  }
461
462  /**
463   * Ensures the truth of an expression involving one or more parameters to the calling method.
464   *
465   * <p>See {@link #checkArgument(boolean, String, Object...)} for details.
466   *
467   * @since 20.0 (varargs overload since 2.0)
468   */
469  public static void checkArgument(
470      boolean b,
471      @Nullable String errorMessageTemplate,
472      @Nullable Object p1,
473      @Nullable Object p2,
474      @Nullable Object p3,
475      @Nullable Object p4) {
476    if (!b) {
477      throw new IllegalArgumentException(lenientFormat(errorMessageTemplate, p1, p2, p3, p4));
478    }
479  }
480
481  /**
482   * Ensures the truth of an expression involving the state of the calling instance, but not
483   * involving any parameters to the calling method.
484   *
485   * @param expression a boolean expression
486   * @throws IllegalStateException if {@code expression} is false
487   * @see Verify#verify Verify.verify()
488   */
489  public static void checkState(boolean expression) {
490    if (!expression) {
491      throw new IllegalStateException();
492    }
493  }
494
495  /**
496   * Ensures the truth of an expression involving the state of the calling instance, but not
497   * involving any parameters to the calling method.
498   *
499   * @param expression a boolean expression
500   * @param errorMessage the exception message to use if the check fails; will be converted to a
501   *     string using {@link String#valueOf(Object)}
502   * @throws IllegalStateException if {@code expression} is false
503   * @see Verify#verify Verify.verify()
504   */
505  public static void checkState(boolean expression, @Nullable Object errorMessage) {
506    if (!expression) {
507      throw new IllegalStateException(String.valueOf(errorMessage));
508    }
509  }
510
511  /**
512   * Ensures the truth of an expression involving the state of the calling instance, but not
513   * involving any parameters to the calling method.
514   *
515   * @param expression a boolean expression
516   * @param errorMessageTemplate a template for the exception message should the check fail. The
517   *     message is formed by replacing each {@code %s} placeholder in the template with an
518   *     argument. These are matched by position - the first {@code %s} gets {@code
519   *     errorMessageArgs[0]}, etc. Unmatched arguments will be appended to the formatted message in
520   *     square braces. Unmatched placeholders will be left as-is.
521   * @param errorMessageArgs the arguments to be substituted into the message template. Arguments
522   *     are converted to strings using {@link String#valueOf(Object)}.
523   * @throws IllegalStateException if {@code expression} is false
524   * @see Verify#verify Verify.verify()
525   */
526  public static void checkState(
527      boolean expression,
528      @Nullable String errorMessageTemplate,
529      @Nullable Object @Nullable... errorMessageArgs) {
530    if (!expression) {
531      throw new IllegalStateException(lenientFormat(errorMessageTemplate, errorMessageArgs));
532    }
533  }
534
535  /**
536   * Ensures the truth of an expression involving the state of the calling instance, but not
537   * involving any parameters to the calling method.
538   *
539   * <p>See {@link #checkState(boolean, String, Object...)} for details.
540   *
541   * @since 20.0 (varargs overload since 2.0)
542   */
543  public static void checkState(boolean b, @Nullable String errorMessageTemplate, char p1) {
544    if (!b) {
545      throw new IllegalStateException(lenientFormat(errorMessageTemplate, p1));
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 b, @Nullable String errorMessageTemplate, int p1) {
558    if (!b) {
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 b, @Nullable String errorMessageTemplate, long p1) {
572    if (!b) {
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(
586      boolean b, @Nullable String errorMessageTemplate, @Nullable Object p1) {
587    if (!b) {
588      throw new IllegalStateException(lenientFormat(errorMessageTemplate, p1));
589    }
590  }
591
592  /**
593   * Ensures the truth of an expression involving the state of the calling instance, but not
594   * involving any parameters to the calling method.
595   *
596   * <p>See {@link #checkState(boolean, String, Object...)} for details.
597   *
598   * @since 20.0 (varargs overload since 2.0)
599   */
600  public static void checkState(
601      boolean b, @Nullable String errorMessageTemplate, char p1, char p2) {
602    if (!b) {
603      throw new IllegalStateException(lenientFormat(errorMessageTemplate, p1, p2));
604    }
605  }
606
607  /**
608   * Ensures the truth of an expression involving the state of the calling instance, but not
609   * involving any parameters to the calling method.
610   *
611   * <p>See {@link #checkState(boolean, String, Object...)} for details.
612   *
613   * @since 20.0 (varargs overload since 2.0)
614   */
615  public static void checkState(boolean b, @Nullable String errorMessageTemplate, char p1, int p2) {
616    if (!b) {
617      throw new IllegalStateException(lenientFormat(errorMessageTemplate, p1, p2));
618    }
619  }
620
621  /**
622   * Ensures the truth of an expression involving the state of the calling instance, but not
623   * involving any parameters to the calling method.
624   *
625   * <p>See {@link #checkState(boolean, String, Object...)} for details.
626   *
627   * @since 20.0 (varargs overload since 2.0)
628   */
629  public static void checkState(
630      boolean b, @Nullable String errorMessageTemplate, char p1, long p2) {
631    if (!b) {
632      throw new IllegalStateException(lenientFormat(errorMessageTemplate, p1, p2));
633    }
634  }
635
636  /**
637   * Ensures the truth of an expression involving the state of the calling instance, but not
638   * involving any parameters to the calling method.
639   *
640   * <p>See {@link #checkState(boolean, String, Object...)} for details.
641   *
642   * @since 20.0 (varargs overload since 2.0)
643   */
644  public static void checkState(
645      boolean b, @Nullable String errorMessageTemplate, char p1, @Nullable Object p2) {
646    if (!b) {
647      throw new IllegalStateException(lenientFormat(errorMessageTemplate, p1, p2));
648    }
649  }
650
651  /**
652   * Ensures the truth of an expression involving the state of the calling instance, but not
653   * involving any parameters to the calling method.
654   *
655   * <p>See {@link #checkState(boolean, String, Object...)} for details.
656   *
657   * @since 20.0 (varargs overload since 2.0)
658   */
659  public static void checkState(boolean b, @Nullable String errorMessageTemplate, int p1, char p2) {
660    if (!b) {
661      throw new IllegalStateException(lenientFormat(errorMessageTemplate, p1, p2));
662    }
663  }
664
665  /**
666   * Ensures the truth of an expression involving the state of the calling instance, but not
667   * involving any parameters to the calling method.
668   *
669   * <p>See {@link #checkState(boolean, String, Object...)} for details.
670   *
671   * @since 20.0 (varargs overload since 2.0)
672   */
673  public static void checkState(boolean b, @Nullable String errorMessageTemplate, int p1, int p2) {
674    if (!b) {
675      throw new IllegalStateException(lenientFormat(errorMessageTemplate, p1, p2));
676    }
677  }
678
679  /**
680   * Ensures the truth of an expression involving the state of the calling instance, but not
681   * involving any parameters to the calling method.
682   *
683   * <p>See {@link #checkState(boolean, String, Object...)} for details.
684   *
685   * @since 20.0 (varargs overload since 2.0)
686   */
687  public static void checkState(boolean b, @Nullable String errorMessageTemplate, int p1, long p2) {
688    if (!b) {
689      throw new IllegalStateException(lenientFormat(errorMessageTemplate, p1, p2));
690    }
691  }
692
693  /**
694   * Ensures the truth of an expression involving the state of the calling instance, but not
695   * involving any parameters to the calling method.
696   *
697   * <p>See {@link #checkState(boolean, String, Object...)} for details.
698   *
699   * @since 20.0 (varargs overload since 2.0)
700   */
701  public static void checkState(
702      boolean b, @Nullable String errorMessageTemplate, int p1, @Nullable Object p2) {
703    if (!b) {
704      throw new IllegalStateException(lenientFormat(errorMessageTemplate, p1, p2));
705    }
706  }
707
708  /**
709   * Ensures the truth of an expression involving the state of the calling instance, but not
710   * involving any parameters to the calling method.
711   *
712   * <p>See {@link #checkState(boolean, String, Object...)} for details.
713   *
714   * @since 20.0 (varargs overload since 2.0)
715   */
716  public static void checkState(
717      boolean b, @Nullable String errorMessageTemplate, long p1, char p2) {
718    if (!b) {
719      throw new IllegalStateException(lenientFormat(errorMessageTemplate, p1, p2));
720    }
721  }
722
723  /**
724   * Ensures the truth of an expression involving the state of the calling instance, but not
725   * involving any parameters to the calling method.
726   *
727   * <p>See {@link #checkState(boolean, String, Object...)} for details.
728   *
729   * @since 20.0 (varargs overload since 2.0)
730   */
731  public static void checkState(boolean b, @Nullable String errorMessageTemplate, long p1, int p2) {
732    if (!b) {
733      throw new IllegalStateException(lenientFormat(errorMessageTemplate, p1, p2));
734    }
735  }
736
737  /**
738   * Ensures the truth of an expression involving the state of the calling instance, but not
739   * involving any parameters to the calling method.
740   *
741   * <p>See {@link #checkState(boolean, String, Object...)} for details.
742   *
743   * @since 20.0 (varargs overload since 2.0)
744   */
745  public static void checkState(
746      boolean b, @Nullable String errorMessageTemplate, long p1, long p2) {
747    if (!b) {
748      throw new IllegalStateException(lenientFormat(errorMessageTemplate, p1, p2));
749    }
750  }
751
752  /**
753   * Ensures the truth of an expression involving the state of the calling instance, but not
754   * involving any parameters to the calling method.
755   *
756   * <p>See {@link #checkState(boolean, String, Object...)} for details.
757   *
758   * @since 20.0 (varargs overload since 2.0)
759   */
760  public static void checkState(
761      boolean b, @Nullable String errorMessageTemplate, long p1, @Nullable Object p2) {
762    if (!b) {
763      throw new IllegalStateException(lenientFormat(errorMessageTemplate, p1, p2));
764    }
765  }
766
767  /**
768   * Ensures the truth of an expression involving the state of the calling instance, but not
769   * involving any parameters to the calling method.
770   *
771   * <p>See {@link #checkState(boolean, String, Object...)} for details.
772   *
773   * @since 20.0 (varargs overload since 2.0)
774   */
775  public static void checkState(
776      boolean b, @Nullable String errorMessageTemplate, @Nullable Object p1, char p2) {
777    if (!b) {
778      throw new IllegalStateException(lenientFormat(errorMessageTemplate, p1, p2));
779    }
780  }
781
782  /**
783   * Ensures the truth of an expression involving the state of the calling instance, but not
784   * involving any parameters to the calling method.
785   *
786   * <p>See {@link #checkState(boolean, String, Object...)} for details.
787   *
788   * @since 20.0 (varargs overload since 2.0)
789   */
790  public static void checkState(
791      boolean b, @Nullable String errorMessageTemplate, @Nullable Object p1, int p2) {
792    if (!b) {
793      throw new IllegalStateException(lenientFormat(errorMessageTemplate, p1, p2));
794    }
795  }
796
797  /**
798   * Ensures the truth of an expression involving the state of the calling instance, but not
799   * involving any parameters to the calling method.
800   *
801   * <p>See {@link #checkState(boolean, String, Object...)} for details.
802   *
803   * @since 20.0 (varargs overload since 2.0)
804   */
805  public static void checkState(
806      boolean b, @Nullable String errorMessageTemplate, @Nullable Object p1, long p2) {
807    if (!b) {
808      throw new IllegalStateException(lenientFormat(errorMessageTemplate, p1, p2));
809    }
810  }
811
812  /**
813   * Ensures the truth of an expression involving the state of the calling instance, but not
814   * involving any parameters to the calling method.
815   *
816   * <p>See {@link #checkState(boolean, String, Object...)} for details.
817   *
818   * @since 20.0 (varargs overload since 2.0)
819   */
820  public static void checkState(
821      boolean b, @Nullable String errorMessageTemplate, @Nullable Object p1, @Nullable Object p2) {
822    if (!b) {
823      throw new IllegalStateException(lenientFormat(errorMessageTemplate, p1, p2));
824    }
825  }
826
827  /**
828   * Ensures the truth of an expression involving the state of the calling instance, but not
829   * involving any parameters to the calling method.
830   *
831   * <p>See {@link #checkState(boolean, String, Object...)} for details.
832   *
833   * @since 20.0 (varargs overload since 2.0)
834   */
835  public static void checkState(
836      boolean b,
837      @Nullable String errorMessageTemplate,
838      @Nullable Object p1,
839      @Nullable Object p2,
840      @Nullable Object p3) {
841    if (!b) {
842      throw new IllegalStateException(lenientFormat(errorMessageTemplate, p1, p2, p3));
843    }
844  }
845
846  /**
847   * Ensures the truth of an expression involving the state of the calling instance, but not
848   * involving any parameters to the calling method.
849   *
850   * <p>See {@link #checkState(boolean, String, Object...)} for details.
851   *
852   * @since 20.0 (varargs overload since 2.0)
853   */
854  public static void checkState(
855      boolean b,
856      @Nullable String errorMessageTemplate,
857      @Nullable Object p1,
858      @Nullable Object p2,
859      @Nullable Object p3,
860      @Nullable Object p4) {
861    if (!b) {
862      throw new IllegalStateException(lenientFormat(errorMessageTemplate, p1, p2, p3, p4));
863    }
864  }
865
866  /**
867   * Ensures that an object reference passed as a parameter to the calling method is not null.
868   *
869   * @param reference an object reference
870   * @return the non-null reference that was validated
871   * @throws NullPointerException if {@code reference} is null
872   * @see Verify#verifyNotNull Verify.verifyNotNull()
873   */
874  @CanIgnoreReturnValue
875  public static <T> T checkNotNull(T reference) {
876    if (reference == null) {
877      throw new NullPointerException();
878    }
879    return reference;
880  }
881
882  /**
883   * Ensures that an object reference passed as a parameter to the calling method is not null.
884   *
885   * @param reference an object reference
886   * @param errorMessage the exception message to use if the check fails; will be converted to a
887   *     string using {@link String#valueOf(Object)}
888   * @return the non-null reference that was validated
889   * @throws NullPointerException if {@code reference} is null
890   * @see Verify#verifyNotNull Verify.verifyNotNull()
891   */
892  @CanIgnoreReturnValue
893  public static <T> T checkNotNull(T reference, @Nullable Object errorMessage) {
894    if (reference == null) {
895      throw new NullPointerException(String.valueOf(errorMessage));
896    }
897    return reference;
898  }
899
900  /**
901   * Ensures that an object reference passed as a parameter to the calling method is not null.
902   *
903   * @param reference an object reference
904   * @param errorMessageTemplate a template for the exception message should the check fail. The
905   *     message is formed by replacing each {@code %s} placeholder in the template with an
906   *     argument. These are matched by position - the first {@code %s} gets {@code
907   *     errorMessageArgs[0]}, etc. Unmatched arguments will be appended to the formatted message in
908   *     square braces. Unmatched placeholders will be left as-is.
909   * @param errorMessageArgs the arguments to be substituted into the message template. Arguments
910   *     are converted to strings using {@link String#valueOf(Object)}.
911   * @return the non-null reference that was validated
912   * @throws NullPointerException if {@code reference} is null
913   * @see Verify#verifyNotNull Verify.verifyNotNull()
914   */
915  @CanIgnoreReturnValue
916  public static <T> T checkNotNull(
917      T reference, @Nullable String errorMessageTemplate, Object @Nullable... errorMessageArgs) {
918    if (reference == null) {
919      throw new NullPointerException(lenientFormat(errorMessageTemplate, errorMessageArgs));
920    }
921    return reference;
922  }
923
924  /**
925   * Ensures that an object reference passed as a parameter to the calling method is not null.
926   *
927   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
928   *
929   * @since 20.0 (varargs overload since 2.0)
930   */
931  @CanIgnoreReturnValue
932  public static <T> T checkNotNull(T obj, @Nullable String errorMessageTemplate, char p1) {
933    if (obj == null) {
934      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1));
935    }
936    return obj;
937  }
938
939  /**
940   * Ensures that an object reference passed as a parameter to the calling method is not null.
941   *
942   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
943   *
944   * @since 20.0 (varargs overload since 2.0)
945   */
946  @CanIgnoreReturnValue
947  public static <T> T checkNotNull(T obj, @Nullable String errorMessageTemplate, int p1) {
948    if (obj == null) {
949      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1));
950    }
951    return obj;
952  }
953
954  /**
955   * Ensures that an object reference passed as a parameter to the calling method is not null.
956   *
957   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
958   *
959   * @since 20.0 (varargs overload since 2.0)
960   */
961  @CanIgnoreReturnValue
962  public static <T> T checkNotNull(T obj, @Nullable String errorMessageTemplate, long p1) {
963    if (obj == null) {
964      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1));
965    }
966    return obj;
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(
978      T obj, @Nullable String errorMessageTemplate, @Nullable Object p1) {
979    if (obj == null) {
980      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1));
981    }
982    return obj;
983  }
984
985  /**
986   * Ensures that an object reference passed as a parameter to the calling method is not null.
987   *
988   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
989   *
990   * @since 20.0 (varargs overload since 2.0)
991   */
992  @CanIgnoreReturnValue
993  public static <T> T checkNotNull(T obj, @Nullable String errorMessageTemplate, char p1, char p2) {
994    if (obj == null) {
995      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2));
996    }
997    return obj;
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(T obj, @Nullable String errorMessageTemplate, char p1, int p2) {
1009    if (obj == null) {
1010      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2));
1011    }
1012    return obj;
1013  }
1014
1015  /**
1016   * Ensures that an object reference passed as a parameter to the calling method is not null.
1017   *
1018   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1019   *
1020   * @since 20.0 (varargs overload since 2.0)
1021   */
1022  @CanIgnoreReturnValue
1023  public static <T> T checkNotNull(T obj, @Nullable String errorMessageTemplate, char p1, long p2) {
1024    if (obj == null) {
1025      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2));
1026    }
1027    return obj;
1028  }
1029
1030  /**
1031   * Ensures that an object reference passed as a parameter to the calling method is not null.
1032   *
1033   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1034   *
1035   * @since 20.0 (varargs overload since 2.0)
1036   */
1037  @CanIgnoreReturnValue
1038  public static <T> T checkNotNull(
1039      T obj, @Nullable String errorMessageTemplate, char p1, @Nullable Object p2) {
1040    if (obj == null) {
1041      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2));
1042    }
1043    return obj;
1044  }
1045
1046  /**
1047   * Ensures that an object reference passed as a parameter to the calling method is not null.
1048   *
1049   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1050   *
1051   * @since 20.0 (varargs overload since 2.0)
1052   */
1053  @CanIgnoreReturnValue
1054  public static <T> T checkNotNull(T obj, @Nullable String errorMessageTemplate, int p1, char p2) {
1055    if (obj == null) {
1056      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2));
1057    }
1058    return obj;
1059  }
1060
1061  /**
1062   * Ensures that an object reference passed as a parameter to the calling method is not null.
1063   *
1064   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1065   *
1066   * @since 20.0 (varargs overload since 2.0)
1067   */
1068  @CanIgnoreReturnValue
1069  public static <T> T checkNotNull(T obj, @Nullable String errorMessageTemplate, int p1, int p2) {
1070    if (obj == null) {
1071      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2));
1072    }
1073    return obj;
1074  }
1075
1076  /**
1077   * Ensures that an object reference passed as a parameter to the calling method is not null.
1078   *
1079   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1080   *
1081   * @since 20.0 (varargs overload since 2.0)
1082   */
1083  @CanIgnoreReturnValue
1084  public static <T> T checkNotNull(T obj, @Nullable String errorMessageTemplate, int p1, long p2) {
1085    if (obj == null) {
1086      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2));
1087    }
1088    return obj;
1089  }
1090
1091  /**
1092   * Ensures that an object reference passed as a parameter to the calling method is not null.
1093   *
1094   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1095   *
1096   * @since 20.0 (varargs overload since 2.0)
1097   */
1098  @CanIgnoreReturnValue
1099  public static <T> T checkNotNull(
1100      T obj, @Nullable String errorMessageTemplate, int p1, @Nullable Object p2) {
1101    if (obj == null) {
1102      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2));
1103    }
1104    return obj;
1105  }
1106
1107  /**
1108   * Ensures that an object reference passed as a parameter to the calling method is not null.
1109   *
1110   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1111   *
1112   * @since 20.0 (varargs overload since 2.0)
1113   */
1114  @CanIgnoreReturnValue
1115  public static <T> T checkNotNull(T obj, @Nullable String errorMessageTemplate, long p1, char p2) {
1116    if (obj == null) {
1117      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2));
1118    }
1119    return obj;
1120  }
1121
1122  /**
1123   * Ensures that an object reference passed as a parameter to the calling method is not null.
1124   *
1125   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1126   *
1127   * @since 20.0 (varargs overload since 2.0)
1128   */
1129  @CanIgnoreReturnValue
1130  public static <T> T checkNotNull(T obj, @Nullable String errorMessageTemplate, long p1, int p2) {
1131    if (obj == null) {
1132      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2));
1133    }
1134    return obj;
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(T obj, @Nullable String errorMessageTemplate, long p1, long p2) {
1146    if (obj == null) {
1147      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2));
1148    }
1149    return obj;
1150  }
1151
1152  /**
1153   * Ensures that an object reference passed as a parameter to the calling method is not null.
1154   *
1155   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1156   *
1157   * @since 20.0 (varargs overload since 2.0)
1158   */
1159  @CanIgnoreReturnValue
1160  public static <T> T checkNotNull(
1161      T obj, @Nullable String errorMessageTemplate, long p1, @Nullable Object p2) {
1162    if (obj == null) {
1163      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2));
1164    }
1165    return obj;
1166  }
1167
1168  /**
1169   * Ensures that an object reference passed as a parameter to the calling method is not null.
1170   *
1171   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1172   *
1173   * @since 20.0 (varargs overload since 2.0)
1174   */
1175  @CanIgnoreReturnValue
1176  public static <T> T checkNotNull(
1177      T obj, @Nullable String errorMessageTemplate, @Nullable Object p1, char p2) {
1178    if (obj == null) {
1179      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2));
1180    }
1181    return obj;
1182  }
1183
1184  /**
1185   * Ensures that an object reference passed as a parameter to the calling method is not null.
1186   *
1187   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1188   *
1189   * @since 20.0 (varargs overload since 2.0)
1190   */
1191  @CanIgnoreReturnValue
1192  public static <T> T checkNotNull(
1193      T obj, @Nullable String errorMessageTemplate, @Nullable Object p1, int p2) {
1194    if (obj == null) {
1195      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2));
1196    }
1197    return obj;
1198  }
1199
1200  /**
1201   * Ensures that an object reference passed as a parameter to the calling method is not null.
1202   *
1203   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1204   *
1205   * @since 20.0 (varargs overload since 2.0)
1206   */
1207  @CanIgnoreReturnValue
1208  public static <T> T checkNotNull(
1209      T obj, @Nullable String errorMessageTemplate, @Nullable Object p1, long p2) {
1210    if (obj == null) {
1211      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2));
1212    }
1213    return obj;
1214  }
1215
1216  /**
1217   * Ensures that an object reference passed as a parameter to the calling method is not null.
1218   *
1219   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1220   *
1221   * @since 20.0 (varargs overload since 2.0)
1222   */
1223  @CanIgnoreReturnValue
1224  public static <T> T checkNotNull(
1225      T obj, @Nullable String errorMessageTemplate, @Nullable Object p1, @Nullable Object p2) {
1226    if (obj == null) {
1227      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2));
1228    }
1229    return obj;
1230  }
1231
1232  /**
1233   * Ensures that an object reference passed as a parameter to the calling method is not null.
1234   *
1235   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1236   *
1237   * @since 20.0 (varargs overload since 2.0)
1238   */
1239  @CanIgnoreReturnValue
1240  public static <T> T checkNotNull(
1241      T obj,
1242      @Nullable String errorMessageTemplate,
1243      @Nullable Object p1,
1244      @Nullable Object p2,
1245      @Nullable Object p3) {
1246    if (obj == null) {
1247      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2, p3));
1248    }
1249    return obj;
1250  }
1251
1252  /**
1253   * Ensures that an object reference passed as a parameter to the calling method is not null.
1254   *
1255   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1256   *
1257   * @since 20.0 (varargs overload since 2.0)
1258   */
1259  @CanIgnoreReturnValue
1260  public static <T> T checkNotNull(
1261      T obj,
1262      @Nullable String errorMessageTemplate,
1263      @Nullable Object p1,
1264      @Nullable Object p2,
1265      @Nullable Object p3,
1266      @Nullable Object p4) {
1267    if (obj == null) {
1268      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2, p3, p4));
1269    }
1270    return obj;
1271  }
1272
1273  /*
1274   * All recent hotspots (as of 2009) *really* like to have the natural code
1275   *
1276   * if (guardExpression) {
1277   *    throw new BadException(messageExpression);
1278   * }
1279   *
1280   * refactored so that messageExpression is moved to a separate String-returning method.
1281   *
1282   * if (guardExpression) {
1283   *    throw new BadException(badMsg(...));
1284   * }
1285   *
1286   * The alternative natural refactorings into void or Exception-returning methods are much slower.
1287   * This is a big deal - we're talking factors of 2-8 in microbenchmarks, not just 10-20%. (This is
1288   * a hotspot optimizer bug, which should be fixed, but that's a separate, big project).
1289   *
1290   * The coding pattern above is heavily used in java.util, e.g. in ArrayList. There is a
1291   * RangeCheckMicroBenchmark in the JDK that was used to test this.
1292   *
1293   * But the methods in this class want to throw different exceptions, depending on the args, so it
1294   * appears that this pattern is not directly applicable. But we can use the ridiculous, devious
1295   * trick of throwing an exception in the middle of the construction of another exception. Hotspot
1296   * is fine with that.
1297   */
1298
1299  /**
1300   * Ensures that {@code index} specifies a valid <i>element</i> in an array, list or string of size
1301   * {@code size}. An element index may range from zero, inclusive, to {@code size}, exclusive.
1302   *
1303   * @param index a user-supplied index identifying an element of an array, list or string
1304   * @param size the size of that array, list or string
1305   * @return the value of {@code index}
1306   * @throws IndexOutOfBoundsException if {@code index} is negative or is not less than {@code size}
1307   * @throws IllegalArgumentException if {@code size} is negative
1308   */
1309  @CanIgnoreReturnValue
1310  public static int checkElementIndex(int index, int size) {
1311    return checkElementIndex(index, size, "index");
1312  }
1313
1314  /**
1315   * Ensures that {@code index} specifies a valid <i>element</i> in an array, list or string of size
1316   * {@code size}. An element index may range from zero, inclusive, to {@code size}, exclusive.
1317   *
1318   * @param index a user-supplied index identifying an element of an array, list or string
1319   * @param size the size of that array, list or string
1320   * @param desc the text to use to describe this index in an error message
1321   * @return the value of {@code index}
1322   * @throws IndexOutOfBoundsException if {@code index} is negative or is not less than {@code size}
1323   * @throws IllegalArgumentException if {@code size} is negative
1324   */
1325  @CanIgnoreReturnValue
1326  public static int checkElementIndex(int index, int size, @Nullable String desc) {
1327    // Carefully optimized for execution by hotspot (explanatory comment above)
1328    if (index < 0 || index >= size) {
1329      throw new IndexOutOfBoundsException(badElementIndex(index, size, desc));
1330    }
1331    return index;
1332  }
1333
1334  private static String badElementIndex(int index, int size, @Nullable String desc) {
1335    if (index < 0) {
1336      return lenientFormat("%s (%s) must not be negative", desc, index);
1337    } else if (size < 0) {
1338      throw new IllegalArgumentException("negative size: " + size);
1339    } else { // index >= size
1340      return lenientFormat("%s (%s) must be less than size (%s)", desc, index, size);
1341    }
1342  }
1343
1344  /**
1345   * Ensures that {@code index} specifies a valid <i>position</i> in an array, list or string of
1346   * size {@code size}. A position index may range from zero to {@code size}, inclusive.
1347   *
1348   * @param index a user-supplied index identifying a position in an array, list or string
1349   * @param size the size of that array, list or string
1350   * @return the value of {@code index}
1351   * @throws IndexOutOfBoundsException if {@code index} is negative or is greater than {@code size}
1352   * @throws IllegalArgumentException if {@code size} is negative
1353   */
1354  @CanIgnoreReturnValue
1355  public static int checkPositionIndex(int index, int size) {
1356    return checkPositionIndex(index, size, "index");
1357  }
1358
1359  /**
1360   * Ensures that {@code index} specifies a valid <i>position</i> in an array, list or string of
1361   * size {@code size}. A position index may range from zero to {@code size}, inclusive.
1362   *
1363   * @param index a user-supplied index identifying a position in an array, list or string
1364   * @param size the size of that array, list or string
1365   * @param desc the text to use to describe this index in an error message
1366   * @return the value of {@code index}
1367   * @throws IndexOutOfBoundsException if {@code index} is negative or is greater than {@code size}
1368   * @throws IllegalArgumentException if {@code size} is negative
1369   */
1370  @CanIgnoreReturnValue
1371  public static int checkPositionIndex(int index, int size, @Nullable String desc) {
1372    // Carefully optimized for execution by hotspot (explanatory comment above)
1373    if (index < 0 || index > size) {
1374      throw new IndexOutOfBoundsException(badPositionIndex(index, size, desc));
1375    }
1376    return index;
1377  }
1378
1379  private static String badPositionIndex(int index, int size, @Nullable String desc) {
1380    if (index < 0) {
1381      return lenientFormat("%s (%s) must not be negative", desc, index);
1382    } else if (size < 0) {
1383      throw new IllegalArgumentException("negative size: " + size);
1384    } else { // index > size
1385      return lenientFormat("%s (%s) must not be greater than size (%s)", desc, index, size);
1386    }
1387  }
1388
1389  /**
1390   * Ensures that {@code start} and {@code end} specify a valid <i>positions</i> in an array, list
1391   * or string of size {@code size}, and are in order. A position index may range from zero to
1392   * {@code size}, inclusive.
1393   *
1394   * @param start a user-supplied index identifying a starting position in an array, list or string
1395   * @param end a user-supplied index identifying a ending position in an array, list or string
1396   * @param size the size of that array, list or string
1397   * @throws IndexOutOfBoundsException if either index is negative or is greater than {@code size},
1398   *     or if {@code end} is less than {@code start}
1399   * @throws IllegalArgumentException if {@code size} is negative
1400   */
1401  public static void checkPositionIndexes(int start, int end, int size) {
1402    // Carefully optimized for execution by hotspot (explanatory comment above)
1403    if (start < 0 || end < start || end > size) {
1404      throw new IndexOutOfBoundsException(badPositionIndexes(start, end, size));
1405    }
1406  }
1407
1408  private static String badPositionIndexes(int start, int end, int size) {
1409    if (start < 0 || start > size) {
1410      return badPositionIndex(start, size, "start index");
1411    }
1412    if (end < 0 || end > size) {
1413      return badPositionIndex(end, size, "end index");
1414    }
1415    // end < start
1416    return lenientFormat("end index (%s) must not be less than start index (%s)", end, start);
1417  }
1418}