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