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