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