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