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