1 /*
2 * Copyright (C) 2007 The Guava Authors
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
5 * in compliance with the License. You may obtain a copy of the License at
6 *
7 * http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software distributed under the License
10 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
11 * or implied. See the License for the specific language governing permissions and limitations under
12 * the License.
13 */
14
15 package com.google.common.base;
16
17 import static com.google.common.base.Strings.lenientFormat;
18
19 import com.google.common.annotations.GwtCompatible;
20 import com.google.errorprone.annotations.CanIgnoreReturnValue;
21 import javax.annotation.CheckForNull;
22 import org.checkerframework.checker.nullness.qual.Nullable;
23
24 /**
25 * Static convenience methods that help a method or constructor check whether it was invoked
26 * correctly (that is, whether its <i>preconditions</i> were met).
27 *
28 * <p>If the precondition is not met, the {@code Preconditions} method throws an unchecked exception
29 * of a specified type, which helps the method in which the exception was thrown communicate that
30 * its caller has made a mistake. This allows constructs such as
31 *
32 * <pre>{@code
33 * public static double sqrt(double value) {
34 * if (value < 0) {
35 * throw new IllegalArgumentException("input is negative: " + value);
36 * }
37 * // calculate square root
38 * }
39 * }</pre>
40 *
41 * <p>to be replaced with the more compact
42 *
43 * <pre>{@code
44 * public static double sqrt(double value) {
45 * checkArgument(value >= 0, "input is negative: %s", value);
46 * // calculate square root
47 * }
48 * }</pre>
49 *
50 * <p>so that a hypothetical bad caller of this method, such as:
51 *
52 * <pre>{@code
53 * void exampleBadCaller() {
54 * double d = sqrt(-1.0);
55 * }
56 * }</pre>
57 *
58 * <p>would be flagged as having called {@code sqrt()} with an illegal argument.
59 *
60 * <h3>Performance</h3>
61 *
62 * <p>Avoid passing message arguments that are expensive to compute; your code will always compute
63 * them, even though they usually won't be needed. If you have such arguments, use the conventional
64 * if/throw idiom instead.
65 *
66 * <p>Depending on your message arguments, memory may be allocated for boxing and varargs array
67 * creation. However, the methods of this class have a large number of overloads that prevent such
68 * allocations in many common cases.
69 *
70 * <p>The message string is not formatted unless the exception will be thrown, so the cost of the
71 * string formatting itself should not be a concern.
72 *
73 * <p>As with any performance concerns, you should consider profiling your code (in a production
74 * environment if possible) before spending a lot of effort on tweaking a particular element.
75 *
76 * <h3>Other types of preconditions</h3>
77 *
78 * <p>Not every type of precondition failure is supported by these methods. Continue to throw
79 * standard JDK exceptions such as {@link java.util.NoSuchElementException} or {@link
80 * UnsupportedOperationException} in the situations they are intended for.
81 *
82 * <h3>Non-preconditions</h3>
83 *
84 * <p>It is of course possible to use the methods of this class to check for invalid conditions
85 * which are <i>not the caller's fault</i>. Doing so is <b>not recommended</b> because it is
86 * misleading to future readers of the code and of stack traces. See <a
87 * href="https://github.com/google/guava/wiki/ConditionalFailuresExplained">Conditional failures
88 * explained</a> in the Guava User Guide for more advice. Notably, {@link Verify} offers assertions
89 * similar to those in this class for non-precondition checks.
90 *
91 * <h3>{@code java.util.Objects.requireNonNull()}</h3>
92 *
93 * <p>Projects which use {@code com.google.common} should generally avoid the use of {@link
94 * java.util.Objects#requireNonNull(Object)}. Instead, use whichever of {@link
95 * #checkNotNull(Object)} or {@link Verify#verifyNotNull(Object)} is appropriate to the situation.
96 * (The same goes for the message-accepting overloads.)
97 *
98 * <h3>Only {@code %s} is supported</h3>
99 *
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
118 public 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 }