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      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, @Nullable String errorMessageTemplate, Object @Nullable ... errorMessageArgs) {
920    if (reference == null) {
921      throw new NullPointerException(lenientFormat(errorMessageTemplate, errorMessageArgs));
922    }
923    return reference;
924  }
925
926  /**
927   * Ensures that an object reference passed as a parameter to the calling method is not null.
928   *
929   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
930   *
931   * @since 20.0 (varargs overload since 2.0)
932   */
933  @CanIgnoreReturnValue
934  public static <T extends @NonNull Object> T checkNotNull(
935      T obj, @Nullable String errorMessageTemplate, char p1) {
936    if (obj == null) {
937      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1));
938    }
939    return obj;
940  }
941
942  /**
943   * Ensures that an object reference passed as a parameter to the calling method is not null.
944   *
945   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
946   *
947   * @since 20.0 (varargs overload since 2.0)
948   */
949  @CanIgnoreReturnValue
950  public static <T extends @NonNull Object> T checkNotNull(
951      T obj, @Nullable String errorMessageTemplate, int p1) {
952    if (obj == null) {
953      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1));
954    }
955    return obj;
956  }
957
958  /**
959   * Ensures that an object reference passed as a parameter to the calling method is not null.
960   *
961   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
962   *
963   * @since 20.0 (varargs overload since 2.0)
964   */
965  @CanIgnoreReturnValue
966  public static <T extends @NonNull Object> T checkNotNull(
967      T obj, @Nullable String errorMessageTemplate, long p1) {
968    if (obj == null) {
969      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1));
970    }
971    return obj;
972  }
973
974  /**
975   * Ensures that an object reference passed as a parameter to the calling method is not null.
976   *
977   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
978   *
979   * @since 20.0 (varargs overload since 2.0)
980   */
981  @CanIgnoreReturnValue
982  public static <T extends @NonNull Object> T checkNotNull(
983      T obj, @Nullable String errorMessageTemplate, @Nullable Object p1) {
984    if (obj == null) {
985      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1));
986    }
987    return obj;
988  }
989
990  /**
991   * Ensures that an object reference passed as a parameter to the calling method is not null.
992   *
993   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
994   *
995   * @since 20.0 (varargs overload since 2.0)
996   */
997  @CanIgnoreReturnValue
998  public static <T extends @NonNull Object> T checkNotNull(
999      T obj, @Nullable String errorMessageTemplate, char p1, char p2) {
1000    if (obj == null) {
1001      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2));
1002    }
1003    return obj;
1004  }
1005
1006  /**
1007   * Ensures that an object reference passed as a parameter to the calling method is not null.
1008   *
1009   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1010   *
1011   * @since 20.0 (varargs overload since 2.0)
1012   */
1013  @CanIgnoreReturnValue
1014  public static <T extends @NonNull Object> T checkNotNull(
1015      T obj, @Nullable String errorMessageTemplate, char p1, int p2) {
1016    if (obj == null) {
1017      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2));
1018    }
1019    return obj;
1020  }
1021
1022  /**
1023   * Ensures that an object reference passed as a parameter to the calling method is not null.
1024   *
1025   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1026   *
1027   * @since 20.0 (varargs overload since 2.0)
1028   */
1029  @CanIgnoreReturnValue
1030  public static <T extends @NonNull Object> T checkNotNull(
1031      T obj, @Nullable String errorMessageTemplate, char p1, long p2) {
1032    if (obj == null) {
1033      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2));
1034    }
1035    return obj;
1036  }
1037
1038  /**
1039   * Ensures that an object reference passed as a parameter to the calling method is not null.
1040   *
1041   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1042   *
1043   * @since 20.0 (varargs overload since 2.0)
1044   */
1045  @CanIgnoreReturnValue
1046  public static <T extends @NonNull Object> T checkNotNull(
1047      T obj, @Nullable String errorMessageTemplate, char p1, @Nullable Object p2) {
1048    if (obj == null) {
1049      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2));
1050    }
1051    return obj;
1052  }
1053
1054  /**
1055   * Ensures that an object reference passed as a parameter to the calling method is not null.
1056   *
1057   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1058   *
1059   * @since 20.0 (varargs overload since 2.0)
1060   */
1061  @CanIgnoreReturnValue
1062  public static <T extends @NonNull Object> T checkNotNull(
1063      T obj, @Nullable String errorMessageTemplate, int p1, char p2) {
1064    if (obj == null) {
1065      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2));
1066    }
1067    return obj;
1068  }
1069
1070  /**
1071   * Ensures that an object reference passed as a parameter to the calling method is not null.
1072   *
1073   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1074   *
1075   * @since 20.0 (varargs overload since 2.0)
1076   */
1077  @CanIgnoreReturnValue
1078  public static <T extends @NonNull Object> T checkNotNull(
1079      T obj, @Nullable String errorMessageTemplate, int p1, int p2) {
1080    if (obj == null) {
1081      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2));
1082    }
1083    return obj;
1084  }
1085
1086  /**
1087   * Ensures that an object reference passed as a parameter to the calling method is not null.
1088   *
1089   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1090   *
1091   * @since 20.0 (varargs overload since 2.0)
1092   */
1093  @CanIgnoreReturnValue
1094  public static <T extends @NonNull Object> T checkNotNull(
1095      T obj, @Nullable String errorMessageTemplate, int p1, long p2) {
1096    if (obj == null) {
1097      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2));
1098    }
1099    return obj;
1100  }
1101
1102  /**
1103   * Ensures that an object reference passed as a parameter to the calling method is not null.
1104   *
1105   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1106   *
1107   * @since 20.0 (varargs overload since 2.0)
1108   */
1109  @CanIgnoreReturnValue
1110  public static <T extends @NonNull Object> T checkNotNull(
1111      T obj, @Nullable String errorMessageTemplate, int p1, @Nullable Object p2) {
1112    if (obj == null) {
1113      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2));
1114    }
1115    return obj;
1116  }
1117
1118  /**
1119   * Ensures that an object reference passed as a parameter to the calling method is not null.
1120   *
1121   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1122   *
1123   * @since 20.0 (varargs overload since 2.0)
1124   */
1125  @CanIgnoreReturnValue
1126  public static <T extends @NonNull Object> T checkNotNull(
1127      T obj, @Nullable String errorMessageTemplate, long p1, char p2) {
1128    if (obj == null) {
1129      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2));
1130    }
1131    return obj;
1132  }
1133
1134  /**
1135   * Ensures that an object reference passed as a parameter to the calling method is not null.
1136   *
1137   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1138   *
1139   * @since 20.0 (varargs overload since 2.0)
1140   */
1141  @CanIgnoreReturnValue
1142  public static <T extends @NonNull Object> T checkNotNull(
1143      T obj, @Nullable String errorMessageTemplate, long p1, int p2) {
1144    if (obj == null) {
1145      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2));
1146    }
1147    return obj;
1148  }
1149
1150  /**
1151   * Ensures that an object reference passed as a parameter to the calling method is not null.
1152   *
1153   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1154   *
1155   * @since 20.0 (varargs overload since 2.0)
1156   */
1157  @CanIgnoreReturnValue
1158  public static <T extends @NonNull Object> T checkNotNull(
1159      T obj, @Nullable String errorMessageTemplate, long p1, long p2) {
1160    if (obj == null) {
1161      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2));
1162    }
1163    return obj;
1164  }
1165
1166  /**
1167   * Ensures that an object reference passed as a parameter to the calling method is not null.
1168   *
1169   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1170   *
1171   * @since 20.0 (varargs overload since 2.0)
1172   */
1173  @CanIgnoreReturnValue
1174  public static <T extends @NonNull Object> T checkNotNull(
1175      T obj, @Nullable String errorMessageTemplate, long p1, @Nullable Object p2) {
1176    if (obj == null) {
1177      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2));
1178    }
1179    return obj;
1180  }
1181
1182  /**
1183   * Ensures that an object reference passed as a parameter to the calling method is not null.
1184   *
1185   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1186   *
1187   * @since 20.0 (varargs overload since 2.0)
1188   */
1189  @CanIgnoreReturnValue
1190  public static <T extends @NonNull Object> T checkNotNull(
1191      T obj, @Nullable String errorMessageTemplate, @Nullable Object p1, char p2) {
1192    if (obj == null) {
1193      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2));
1194    }
1195    return obj;
1196  }
1197
1198  /**
1199   * Ensures that an object reference passed as a parameter to the calling method is not null.
1200   *
1201   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1202   *
1203   * @since 20.0 (varargs overload since 2.0)
1204   */
1205  @CanIgnoreReturnValue
1206  public static <T extends @NonNull Object> T checkNotNull(
1207      T obj, @Nullable String errorMessageTemplate, @Nullable Object p1, int p2) {
1208    if (obj == null) {
1209      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2));
1210    }
1211    return obj;
1212  }
1213
1214  /**
1215   * Ensures that an object reference passed as a parameter to the calling method is not null.
1216   *
1217   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1218   *
1219   * @since 20.0 (varargs overload since 2.0)
1220   */
1221  @CanIgnoreReturnValue
1222  public static <T extends @NonNull Object> T checkNotNull(
1223      T obj, @Nullable String errorMessageTemplate, @Nullable Object p1, long p2) {
1224    if (obj == null) {
1225      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2));
1226    }
1227    return obj;
1228  }
1229
1230  /**
1231   * Ensures that an object reference passed as a parameter to the calling method is not null.
1232   *
1233   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1234   *
1235   * @since 20.0 (varargs overload since 2.0)
1236   */
1237  @CanIgnoreReturnValue
1238  public static <T extends @NonNull Object> T checkNotNull(
1239      T obj, @Nullable String errorMessageTemplate, @Nullable Object p1, @Nullable Object p2) {
1240    if (obj == null) {
1241      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2));
1242    }
1243    return obj;
1244  }
1245
1246  /**
1247   * Ensures that an object reference passed as a parameter to the calling method is not null.
1248   *
1249   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1250   *
1251   * @since 20.0 (varargs overload since 2.0)
1252   */
1253  @CanIgnoreReturnValue
1254  public static <T extends @NonNull Object> T checkNotNull(
1255      T obj,
1256      @Nullable String errorMessageTemplate,
1257      @Nullable Object p1,
1258      @Nullable Object p2,
1259      @Nullable Object p3) {
1260    if (obj == null) {
1261      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2, p3));
1262    }
1263    return obj;
1264  }
1265
1266  /**
1267   * Ensures that an object reference passed as a parameter to the calling method is not null.
1268   *
1269   * <p>See {@link #checkNotNull(Object, String, Object...)} for details.
1270   *
1271   * @since 20.0 (varargs overload since 2.0)
1272   */
1273  @CanIgnoreReturnValue
1274  public static <T extends @NonNull Object> T checkNotNull(
1275      T obj,
1276      @Nullable String errorMessageTemplate,
1277      @Nullable Object p1,
1278      @Nullable Object p2,
1279      @Nullable Object p3,
1280      @Nullable Object p4) {
1281    if (obj == null) {
1282      throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2, p3, p4));
1283    }
1284    return obj;
1285  }
1286
1287  /*
1288   * All recent hotspots (as of 2009) *really* like to have the natural code
1289   *
1290   * if (guardExpression) {
1291   *    throw new BadException(messageExpression);
1292   * }
1293   *
1294   * refactored so that messageExpression is moved to a separate String-returning method.
1295   *
1296   * if (guardExpression) {
1297   *    throw new BadException(badMsg(...));
1298   * }
1299   *
1300   * The alternative natural refactorings into void or Exception-returning methods are much slower.
1301   * This is a big deal - we're talking factors of 2-8 in microbenchmarks, not just 10-20%. (This is
1302   * a hotspot optimizer bug, which should be fixed, but that's a separate, big project).
1303   *
1304   * The coding pattern above is heavily used in java.util, e.g. in ArrayList. There is a
1305   * RangeCheckMicroBenchmark in the JDK that was used to test this.
1306   *
1307   * But the methods in this class want to throw different exceptions, depending on the args, so it
1308   * appears that this pattern is not directly applicable. But we can use the ridiculous, devious
1309   * trick of throwing an exception in the middle of the construction of another exception. Hotspot
1310   * is fine with that.
1311   */
1312
1313  /**
1314   * Ensures that {@code index} specifies a valid <i>element</i> in an array, list or string of size
1315   * {@code size}. An element index may range from zero, inclusive, to {@code size}, exclusive.
1316   *
1317   * @param index a user-supplied index identifying an element of an array, list or string
1318   * @param size the size of that array, list or string
1319   * @return the value of {@code index}
1320   * @throws IndexOutOfBoundsException if {@code index} is negative or is not less than {@code size}
1321   * @throws IllegalArgumentException if {@code size} is negative
1322   */
1323  @CanIgnoreReturnValue
1324  public static int checkElementIndex(int index, int size) {
1325    return checkElementIndex(index, size, "index");
1326  }
1327
1328  /**
1329   * Ensures that {@code index} specifies a valid <i>element</i> in an array, list or string of size
1330   * {@code size}. An element index may range from zero, inclusive, to {@code size}, exclusive.
1331   *
1332   * @param index a user-supplied index identifying an element of an array, list or string
1333   * @param size the size of that array, list or string
1334   * @param desc the text to use to describe this index in an error message
1335   * @return the value of {@code index}
1336   * @throws IndexOutOfBoundsException if {@code index} is negative or is not less than {@code size}
1337   * @throws IllegalArgumentException if {@code size} is negative
1338   */
1339  @CanIgnoreReturnValue
1340  public static int checkElementIndex(int index, int size, @Nullable String desc) {
1341    // Carefully optimized for execution by hotspot (explanatory comment above)
1342    if (index < 0 || index >= size) {
1343      throw new IndexOutOfBoundsException(badElementIndex(index, size, desc));
1344    }
1345    return index;
1346  }
1347
1348  private static String badElementIndex(int index, int size, @Nullable String desc) {
1349    if (index < 0) {
1350      return lenientFormat("%s (%s) must not be negative", desc, index);
1351    } else if (size < 0) {
1352      throw new IllegalArgumentException("negative size: " + size);
1353    } else { // index >= size
1354      return lenientFormat("%s (%s) must be less than size (%s)", desc, index, size);
1355    }
1356  }
1357
1358  /**
1359   * Ensures that {@code index} specifies a valid <i>position</i> in an array, list or string of
1360   * size {@code size}. A position index may range from zero to {@code size}, inclusive.
1361   *
1362   * @param index a user-supplied index identifying a position in an array, list or string
1363   * @param size the size of that array, list or string
1364   * @return the value of {@code index}
1365   * @throws IndexOutOfBoundsException if {@code index} is negative or is greater than {@code size}
1366   * @throws IllegalArgumentException if {@code size} is negative
1367   */
1368  @CanIgnoreReturnValue
1369  public static int checkPositionIndex(int index, int size) {
1370    return checkPositionIndex(index, size, "index");
1371  }
1372
1373  /**
1374   * Ensures that {@code index} specifies a valid <i>position</i> in an array, list or string of
1375   * size {@code size}. A position index may range from zero to {@code size}, inclusive.
1376   *
1377   * @param index a user-supplied index identifying a position in an array, list or string
1378   * @param size the size of that array, list or string
1379   * @param desc the text to use to describe this index in an error message
1380   * @return the value of {@code index}
1381   * @throws IndexOutOfBoundsException if {@code index} is negative or is greater than {@code size}
1382   * @throws IllegalArgumentException if {@code size} is negative
1383   */
1384  @CanIgnoreReturnValue
1385  public static int checkPositionIndex(int index, int size, @Nullable String desc) {
1386    // Carefully optimized for execution by hotspot (explanatory comment above)
1387    if (index < 0 || index > size) {
1388      throw new IndexOutOfBoundsException(badPositionIndex(index, size, desc));
1389    }
1390    return index;
1391  }
1392
1393  private static String badPositionIndex(int index, int size, @Nullable String desc) {
1394    if (index < 0) {
1395      return lenientFormat("%s (%s) must not be negative", desc, index);
1396    } else if (size < 0) {
1397      throw new IllegalArgumentException("negative size: " + size);
1398    } else { // index > size
1399      return lenientFormat("%s (%s) must not be greater than size (%s)", desc, index, size);
1400    }
1401  }
1402
1403  /**
1404   * Ensures that {@code start} and {@code end} specify a valid <i>positions</i> in an array, list
1405   * or string of size {@code size}, and are in order. A position index may range from zero to
1406   * {@code size}, inclusive.
1407   *
1408   * @param start a user-supplied index identifying a starting position in an array, list or string
1409   * @param end a user-supplied index identifying a ending position in an array, list or string
1410   * @param size the size of that array, list or string
1411   * @throws IndexOutOfBoundsException if either index is negative or is greater than {@code size},
1412   *     or if {@code end} is less than {@code start}
1413   * @throws IllegalArgumentException if {@code size} is negative
1414   */
1415  public static void checkPositionIndexes(int start, int end, int size) {
1416    // Carefully optimized for execution by hotspot (explanatory comment above)
1417    if (start < 0 || end < start || end > size) {
1418      throw new IndexOutOfBoundsException(badPositionIndexes(start, end, size));
1419    }
1420  }
1421
1422  private static String badPositionIndexes(int start, int end, int size) {
1423    if (start < 0 || start > size) {
1424      return badPositionIndex(start, size, "start index");
1425    }
1426    if (end < 0 || end > size) {
1427      return badPositionIndex(end, size, "end index");
1428    }
1429    // end < start
1430    return lenientFormat("end index (%s) must not be less than start index (%s)", end, start);
1431  }
1432}