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