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 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, @Nullable String errorMessageTemplate, Object @Nullable ... errorMessageArgs) { 920 if (reference == null) { 921 throw new NullPointerException(lenientFormat(errorMessageTemplate, errorMessageArgs)); 922 } 923 return reference; 924 } 925 926 /** 927 * Ensures that an object reference passed as a parameter to the calling method is not null. 928 * 929 * <p>See {@link #checkNotNull(Object, String, Object...)} for details. 930 * 931 * @since 20.0 (varargs overload since 2.0) 932 */ 933 @CanIgnoreReturnValue 934 public static <T extends @NonNull Object> T checkNotNull( 935 T obj, @Nullable String errorMessageTemplate, char p1) { 936 if (obj == null) { 937 throw new NullPointerException(lenientFormat(errorMessageTemplate, p1)); 938 } 939 return obj; 940 } 941 942 /** 943 * Ensures that an object reference passed as a parameter to the calling method is not null. 944 * 945 * <p>See {@link #checkNotNull(Object, String, Object...)} for details. 946 * 947 * @since 20.0 (varargs overload since 2.0) 948 */ 949 @CanIgnoreReturnValue 950 public static <T extends @NonNull Object> T checkNotNull( 951 T obj, @Nullable String errorMessageTemplate, int p1) { 952 if (obj == null) { 953 throw new NullPointerException(lenientFormat(errorMessageTemplate, p1)); 954 } 955 return obj; 956 } 957 958 /** 959 * Ensures that an object reference passed as a parameter to the calling method is not null. 960 * 961 * <p>See {@link #checkNotNull(Object, String, Object...)} for details. 962 * 963 * @since 20.0 (varargs overload since 2.0) 964 */ 965 @CanIgnoreReturnValue 966 public static <T extends @NonNull Object> T checkNotNull( 967 T obj, @Nullable String errorMessageTemplate, long p1) { 968 if (obj == null) { 969 throw new NullPointerException(lenientFormat(errorMessageTemplate, p1)); 970 } 971 return obj; 972 } 973 974 /** 975 * Ensures that an object reference passed as a parameter to the calling method is not null. 976 * 977 * <p>See {@link #checkNotNull(Object, String, Object...)} for details. 978 * 979 * @since 20.0 (varargs overload since 2.0) 980 */ 981 @CanIgnoreReturnValue 982 public static <T extends @NonNull Object> T checkNotNull( 983 T obj, @Nullable String errorMessageTemplate, @Nullable Object p1) { 984 if (obj == null) { 985 throw new NullPointerException(lenientFormat(errorMessageTemplate, p1)); 986 } 987 return obj; 988 } 989 990 /** 991 * Ensures that an object reference passed as a parameter to the calling method is not null. 992 * 993 * <p>See {@link #checkNotNull(Object, String, Object...)} for details. 994 * 995 * @since 20.0 (varargs overload since 2.0) 996 */ 997 @CanIgnoreReturnValue 998 public static <T extends @NonNull Object> T checkNotNull( 999 T obj, @Nullable String errorMessageTemplate, char p1, char p2) { 1000 if (obj == null) { 1001 throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2)); 1002 } 1003 return obj; 1004 } 1005 1006 /** 1007 * Ensures that an object reference passed as a parameter to the calling method is not null. 1008 * 1009 * <p>See {@link #checkNotNull(Object, String, Object...)} for details. 1010 * 1011 * @since 20.0 (varargs overload since 2.0) 1012 */ 1013 @CanIgnoreReturnValue 1014 public static <T extends @NonNull Object> T checkNotNull( 1015 T obj, @Nullable String errorMessageTemplate, char p1, int p2) { 1016 if (obj == null) { 1017 throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2)); 1018 } 1019 return obj; 1020 } 1021 1022 /** 1023 * Ensures that an object reference passed as a parameter to the calling method is not null. 1024 * 1025 * <p>See {@link #checkNotNull(Object, String, Object...)} for details. 1026 * 1027 * @since 20.0 (varargs overload since 2.0) 1028 */ 1029 @CanIgnoreReturnValue 1030 public static <T extends @NonNull Object> T checkNotNull( 1031 T obj, @Nullable String errorMessageTemplate, char p1, long p2) { 1032 if (obj == null) { 1033 throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2)); 1034 } 1035 return obj; 1036 } 1037 1038 /** 1039 * Ensures that an object reference passed as a parameter to the calling method is not null. 1040 * 1041 * <p>See {@link #checkNotNull(Object, String, Object...)} for details. 1042 * 1043 * @since 20.0 (varargs overload since 2.0) 1044 */ 1045 @CanIgnoreReturnValue 1046 public static <T extends @NonNull Object> T checkNotNull( 1047 T obj, @Nullable String errorMessageTemplate, char p1, @Nullable Object p2) { 1048 if (obj == null) { 1049 throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2)); 1050 } 1051 return obj; 1052 } 1053 1054 /** 1055 * Ensures that an object reference passed as a parameter to the calling method is not null. 1056 * 1057 * <p>See {@link #checkNotNull(Object, String, Object...)} for details. 1058 * 1059 * @since 20.0 (varargs overload since 2.0) 1060 */ 1061 @CanIgnoreReturnValue 1062 public static <T extends @NonNull Object> T checkNotNull( 1063 T obj, @Nullable String errorMessageTemplate, int p1, char p2) { 1064 if (obj == null) { 1065 throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2)); 1066 } 1067 return obj; 1068 } 1069 1070 /** 1071 * Ensures that an object reference passed as a parameter to the calling method is not null. 1072 * 1073 * <p>See {@link #checkNotNull(Object, String, Object...)} for details. 1074 * 1075 * @since 20.0 (varargs overload since 2.0) 1076 */ 1077 @CanIgnoreReturnValue 1078 public static <T extends @NonNull Object> T checkNotNull( 1079 T obj, @Nullable String errorMessageTemplate, int p1, int p2) { 1080 if (obj == null) { 1081 throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2)); 1082 } 1083 return obj; 1084 } 1085 1086 /** 1087 * Ensures that an object reference passed as a parameter to the calling method is not null. 1088 * 1089 * <p>See {@link #checkNotNull(Object, String, Object...)} for details. 1090 * 1091 * @since 20.0 (varargs overload since 2.0) 1092 */ 1093 @CanIgnoreReturnValue 1094 public static <T extends @NonNull Object> T checkNotNull( 1095 T obj, @Nullable String errorMessageTemplate, int p1, long p2) { 1096 if (obj == null) { 1097 throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2)); 1098 } 1099 return obj; 1100 } 1101 1102 /** 1103 * Ensures that an object reference passed as a parameter to the calling method is not null. 1104 * 1105 * <p>See {@link #checkNotNull(Object, String, Object...)} for details. 1106 * 1107 * @since 20.0 (varargs overload since 2.0) 1108 */ 1109 @CanIgnoreReturnValue 1110 public static <T extends @NonNull Object> T checkNotNull( 1111 T obj, @Nullable String errorMessageTemplate, int p1, @Nullable Object p2) { 1112 if (obj == null) { 1113 throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2)); 1114 } 1115 return obj; 1116 } 1117 1118 /** 1119 * Ensures that an object reference passed as a parameter to the calling method is not null. 1120 * 1121 * <p>See {@link #checkNotNull(Object, String, Object...)} for details. 1122 * 1123 * @since 20.0 (varargs overload since 2.0) 1124 */ 1125 @CanIgnoreReturnValue 1126 public static <T extends @NonNull Object> T checkNotNull( 1127 T obj, @Nullable String errorMessageTemplate, long p1, char p2) { 1128 if (obj == null) { 1129 throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2)); 1130 } 1131 return obj; 1132 } 1133 1134 /** 1135 * Ensures that an object reference passed as a parameter to the calling method is not null. 1136 * 1137 * <p>See {@link #checkNotNull(Object, String, Object...)} for details. 1138 * 1139 * @since 20.0 (varargs overload since 2.0) 1140 */ 1141 @CanIgnoreReturnValue 1142 public static <T extends @NonNull Object> T checkNotNull( 1143 T obj, @Nullable String errorMessageTemplate, long p1, int p2) { 1144 if (obj == null) { 1145 throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2)); 1146 } 1147 return obj; 1148 } 1149 1150 /** 1151 * Ensures that an object reference passed as a parameter to the calling method is not null. 1152 * 1153 * <p>See {@link #checkNotNull(Object, String, Object...)} for details. 1154 * 1155 * @since 20.0 (varargs overload since 2.0) 1156 */ 1157 @CanIgnoreReturnValue 1158 public static <T extends @NonNull Object> T checkNotNull( 1159 T obj, @Nullable String errorMessageTemplate, long p1, long p2) { 1160 if (obj == null) { 1161 throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2)); 1162 } 1163 return obj; 1164 } 1165 1166 /** 1167 * Ensures that an object reference passed as a parameter to the calling method is not null. 1168 * 1169 * <p>See {@link #checkNotNull(Object, String, Object...)} for details. 1170 * 1171 * @since 20.0 (varargs overload since 2.0) 1172 */ 1173 @CanIgnoreReturnValue 1174 public static <T extends @NonNull Object> T checkNotNull( 1175 T obj, @Nullable String errorMessageTemplate, long p1, @Nullable Object p2) { 1176 if (obj == null) { 1177 throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2)); 1178 } 1179 return obj; 1180 } 1181 1182 /** 1183 * Ensures that an object reference passed as a parameter to the calling method is not null. 1184 * 1185 * <p>See {@link #checkNotNull(Object, String, Object...)} for details. 1186 * 1187 * @since 20.0 (varargs overload since 2.0) 1188 */ 1189 @CanIgnoreReturnValue 1190 public static <T extends @NonNull Object> T checkNotNull( 1191 T obj, @Nullable String errorMessageTemplate, @Nullable Object p1, char p2) { 1192 if (obj == null) { 1193 throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2)); 1194 } 1195 return obj; 1196 } 1197 1198 /** 1199 * Ensures that an object reference passed as a parameter to the calling method is not null. 1200 * 1201 * <p>See {@link #checkNotNull(Object, String, Object...)} for details. 1202 * 1203 * @since 20.0 (varargs overload since 2.0) 1204 */ 1205 @CanIgnoreReturnValue 1206 public static <T extends @NonNull Object> T checkNotNull( 1207 T obj, @Nullable String errorMessageTemplate, @Nullable Object p1, int p2) { 1208 if (obj == null) { 1209 throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2)); 1210 } 1211 return obj; 1212 } 1213 1214 /** 1215 * Ensures that an object reference passed as a parameter to the calling method is not null. 1216 * 1217 * <p>See {@link #checkNotNull(Object, String, Object...)} for details. 1218 * 1219 * @since 20.0 (varargs overload since 2.0) 1220 */ 1221 @CanIgnoreReturnValue 1222 public static <T extends @NonNull Object> T checkNotNull( 1223 T obj, @Nullable String errorMessageTemplate, @Nullable Object p1, long p2) { 1224 if (obj == null) { 1225 throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2)); 1226 } 1227 return obj; 1228 } 1229 1230 /** 1231 * Ensures that an object reference passed as a parameter to the calling method is not null. 1232 * 1233 * <p>See {@link #checkNotNull(Object, String, Object...)} for details. 1234 * 1235 * @since 20.0 (varargs overload since 2.0) 1236 */ 1237 @CanIgnoreReturnValue 1238 public static <T extends @NonNull Object> T checkNotNull( 1239 T obj, @Nullable String errorMessageTemplate, @Nullable Object p1, @Nullable Object p2) { 1240 if (obj == null) { 1241 throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2)); 1242 } 1243 return obj; 1244 } 1245 1246 /** 1247 * Ensures that an object reference passed as a parameter to the calling method is not null. 1248 * 1249 * <p>See {@link #checkNotNull(Object, String, Object...)} for details. 1250 * 1251 * @since 20.0 (varargs overload since 2.0) 1252 */ 1253 @CanIgnoreReturnValue 1254 public static <T extends @NonNull Object> T checkNotNull( 1255 T obj, 1256 @Nullable String errorMessageTemplate, 1257 @Nullable Object p1, 1258 @Nullable Object p2, 1259 @Nullable Object p3) { 1260 if (obj == null) { 1261 throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2, p3)); 1262 } 1263 return obj; 1264 } 1265 1266 /** 1267 * Ensures that an object reference passed as a parameter to the calling method is not null. 1268 * 1269 * <p>See {@link #checkNotNull(Object, String, Object...)} for details. 1270 * 1271 * @since 20.0 (varargs overload since 2.0) 1272 */ 1273 @CanIgnoreReturnValue 1274 public static <T extends @NonNull Object> T checkNotNull( 1275 T obj, 1276 @Nullable String errorMessageTemplate, 1277 @Nullable Object p1, 1278 @Nullable Object p2, 1279 @Nullable Object p3, 1280 @Nullable Object p4) { 1281 if (obj == null) { 1282 throw new NullPointerException(lenientFormat(errorMessageTemplate, p1, p2, p3, p4)); 1283 } 1284 return obj; 1285 } 1286 1287 /* 1288 * All recent hotspots (as of 2009) *really* like to have the natural code 1289 * 1290 * if (guardExpression) { 1291 * throw new BadException(messageExpression); 1292 * } 1293 * 1294 * refactored so that messageExpression is moved to a separate String-returning method. 1295 * 1296 * if (guardExpression) { 1297 * throw new BadException(badMsg(...)); 1298 * } 1299 * 1300 * The alternative natural refactorings into void or Exception-returning methods are much slower. 1301 * This is a big deal - we're talking factors of 2-8 in microbenchmarks, not just 10-20%. (This is 1302 * a hotspot optimizer bug, which should be fixed, but that's a separate, big project). 1303 * 1304 * The coding pattern above is heavily used in java.util, e.g. in ArrayList. There is a 1305 * RangeCheckMicroBenchmark in the JDK that was used to test this. 1306 * 1307 * But the methods in this class want to throw different exceptions, depending on the args, so it 1308 * appears that this pattern is not directly applicable. But we can use the ridiculous, devious 1309 * trick of throwing an exception in the middle of the construction of another exception. Hotspot 1310 * is fine with that. 1311 */ 1312 1313 /** 1314 * Ensures that {@code index} specifies a valid <i>element</i> in an array, list or string of size 1315 * {@code size}. An element index may range from zero, inclusive, to {@code size}, exclusive. 1316 * 1317 * @param index a user-supplied index identifying an element of an array, list or string 1318 * @param size the size of that array, list or string 1319 * @return the value of {@code index} 1320 * @throws IndexOutOfBoundsException if {@code index} is negative or is not less than {@code size} 1321 * @throws IllegalArgumentException if {@code size} is negative 1322 */ 1323 @CanIgnoreReturnValue 1324 public static int checkElementIndex(int index, int size) { 1325 return checkElementIndex(index, size, "index"); 1326 } 1327 1328 /** 1329 * Ensures that {@code index} specifies a valid <i>element</i> in an array, list or string of size 1330 * {@code size}. An element index may range from zero, inclusive, to {@code size}, exclusive. 1331 * 1332 * @param index a user-supplied index identifying an element of an array, list or string 1333 * @param size the size of that array, list or string 1334 * @param desc the text to use to describe this index in an error message 1335 * @return the value of {@code index} 1336 * @throws IndexOutOfBoundsException if {@code index} is negative or is not less than {@code size} 1337 * @throws IllegalArgumentException if {@code size} is negative 1338 */ 1339 @CanIgnoreReturnValue 1340 public static int checkElementIndex(int index, int size, @Nullable String desc) { 1341 // Carefully optimized for execution by hotspot (explanatory comment above) 1342 if (index < 0 || index >= size) { 1343 throw new IndexOutOfBoundsException(badElementIndex(index, size, desc)); 1344 } 1345 return index; 1346 } 1347 1348 private static String badElementIndex(int index, int size, @Nullable String desc) { 1349 if (index < 0) { 1350 return lenientFormat("%s (%s) must not be negative", desc, index); 1351 } else if (size < 0) { 1352 throw new IllegalArgumentException("negative size: " + size); 1353 } else { // index >= size 1354 return lenientFormat("%s (%s) must be less than size (%s)", desc, index, size); 1355 } 1356 } 1357 1358 /** 1359 * Ensures that {@code index} specifies a valid <i>position</i> in an array, list or string of 1360 * size {@code size}. A position index may range from zero to {@code size}, inclusive. 1361 * 1362 * @param index a user-supplied index identifying a position in an array, list or string 1363 * @param size the size of that array, list or string 1364 * @return the value of {@code index} 1365 * @throws IndexOutOfBoundsException if {@code index} is negative or is greater than {@code size} 1366 * @throws IllegalArgumentException if {@code size} is negative 1367 */ 1368 @CanIgnoreReturnValue 1369 public static int checkPositionIndex(int index, int size) { 1370 return checkPositionIndex(index, size, "index"); 1371 } 1372 1373 /** 1374 * Ensures that {@code index} specifies a valid <i>position</i> in an array, list or string of 1375 * size {@code size}. A position index may range from zero to {@code size}, inclusive. 1376 * 1377 * @param index a user-supplied index identifying a position in an array, list or string 1378 * @param size the size of that array, list or string 1379 * @param desc the text to use to describe this index in an error message 1380 * @return the value of {@code index} 1381 * @throws IndexOutOfBoundsException if {@code index} is negative or is greater than {@code size} 1382 * @throws IllegalArgumentException if {@code size} is negative 1383 */ 1384 @CanIgnoreReturnValue 1385 public static int checkPositionIndex(int index, int size, @Nullable String desc) { 1386 // Carefully optimized for execution by hotspot (explanatory comment above) 1387 if (index < 0 || index > size) { 1388 throw new IndexOutOfBoundsException(badPositionIndex(index, size, desc)); 1389 } 1390 return index; 1391 } 1392 1393 private static String badPositionIndex(int index, int size, @Nullable String desc) { 1394 if (index < 0) { 1395 return lenientFormat("%s (%s) must not be negative", desc, index); 1396 } else if (size < 0) { 1397 throw new IllegalArgumentException("negative size: " + size); 1398 } else { // index > size 1399 return lenientFormat("%s (%s) must not be greater than size (%s)", desc, index, size); 1400 } 1401 } 1402 1403 /** 1404 * Ensures that {@code start} and {@code end} specify a valid <i>positions</i> in an array, list 1405 * or string of size {@code size}, and are in order. A position index may range from zero to 1406 * {@code size}, inclusive. 1407 * 1408 * @param start a user-supplied index identifying a starting position in an array, list or string 1409 * @param end a user-supplied index identifying a ending position in an array, list or string 1410 * @param size the size of that array, list or string 1411 * @throws IndexOutOfBoundsException if either index is negative or is greater than {@code size}, 1412 * or if {@code end} is less than {@code start} 1413 * @throws IllegalArgumentException if {@code size} is negative 1414 */ 1415 public static void checkPositionIndexes(int start, int end, int size) { 1416 // Carefully optimized for execution by hotspot (explanatory comment above) 1417 if (start < 0 || end < start || end > size) { 1418 throw new IndexOutOfBoundsException(badPositionIndexes(start, end, size)); 1419 } 1420 } 1421 1422 private static String badPositionIndexes(int start, int end, int size) { 1423 if (start < 0 || start > size) { 1424 return badPositionIndex(start, size, "start index"); 1425 } 1426 if (end < 0 || end > size) { 1427 return badPositionIndex(end, size, "end index"); 1428 } 1429 // end < start 1430 return lenientFormat("end index (%s) must not be less than start index (%s)", end, start); 1431 } 1432}