< prev index next >

src/java.base/share/classes/java/util/Objects.java

Print this page
rev 14354 : 8155794: Move Objects.checkIndex BiFunction accepting methods to an internal package
Reviewed-by:
   1 /*
   2  * Copyright (c) 2009, 2015, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.util;
  27 
  28 import jdk.internal.HotSpotIntrinsicCandidate;

  29 
  30 import java.util.function.BiFunction;
  31 import java.util.function.Function;
  32 import java.util.function.Supplier;
  33 
  34 /**
  35  * This class consists of {@code static} utility methods for operating
  36  * on objects, or checking certain conditions before operation.  These utilities
  37  * include {@code null}-safe or {@code null}-tolerant methods for computing the
  38  * hash code of an object, returning a string for an object, comparing two
  39  * objects, and checking if indexes or sub-range values are out-of-bounds.
  40  *
  41  * @apiNote
  42  * Static methods such as {@link Objects#checkIndex},
  43  * {@link Objects#checkFromToIndex}, and {@link Objects#checkFromIndexSize} are
  44  * provided for the convenience of checking if values corresponding to indexes
  45  * and sub-ranges are out-of-bounds.
  46  * Variations of these static methods support customization of the runtime
  47  * exception, and corresponding exception detail message, that is thrown when
  48  * values are out-of-bounds.  Such methods accept a functional interface
  49  * argument, instances of {@code BiFunction}, that maps out-of-bound values to a
  50  * runtime exception.  Care should be taken when using such methods in
  51  * combination with an argument that is a lambda expression, method reference or


 332      * performance advantage in the non-null case, when deciding to
 333      * call this method care should be taken that the costs of
 334      * creating the message supplier are less than the cost of just
 335      * creating the string message directly.
 336      *
 337      * @param obj     the object reference to check for nullity
 338      * @param messageSupplier supplier of the detail message to be
 339      * used in the event that a {@code NullPointerException} is thrown
 340      * @param <T> the type of the reference
 341      * @return {@code obj} if not {@code null}
 342      * @throws NullPointerException if {@code obj} is {@code null}
 343      * @since 1.8
 344      */
 345     public static <T> T requireNonNull(T obj, Supplier<String> messageSupplier) {
 346         if (obj == null)
 347             throw new NullPointerException(messageSupplier.get());
 348         return obj;
 349     }
 350 
 351     /**
 352      * Maps out-of-bounds values to a runtime exception.
 353      *
 354      * @param checkKind the kind of bounds check, whose name may correspond
 355      *        to the name of one of the range check methods, checkIndex,
 356      *        checkFromToIndex, checkFromIndexSize
 357      * @param args the out-of-bounds arguments that failed the range check.
 358      *        If the checkKind corresponds a the name of a range check method
 359      *        then the bounds arguments are those that can be passed in order
 360      *        to the method.
 361      * @param oobef the exception formatter that when applied with a checkKind
 362      *        and a list out-of-bounds arguments returns a runtime exception.
 363      *        If {@code null} then, it is as if an exception formatter was
 364      *        supplied that returns {@link IndexOutOfBoundsException} for any
 365      *        given arguments.
 366      * @return the runtime exception
 367      */
 368     private static RuntimeException outOfBounds(
 369             BiFunction<String, List<Integer>, ? extends RuntimeException> oobef,
 370             String checkKind,
 371             Integer... args) {
 372         List<Integer> largs = List.of(args);
 373         RuntimeException e = oobef == null
 374                              ? null : oobef.apply(checkKind, largs);
 375         return e == null
 376                ? new IndexOutOfBoundsException(outOfBoundsMessage(checkKind, largs)) : e;
 377     }
 378 
 379     // Specific out-of-bounds exception producing methods that avoid
 380     // the varargs-based code in the critical methods there by reducing their
 381     // the byte code size, and therefore less likely to peturb inlining
 382 
 383     private static RuntimeException outOfBoundsCheckIndex(
 384             BiFunction<String, List<Integer>, ? extends RuntimeException> oobe,
 385             int index, int length) {
 386         return outOfBounds(oobe, "checkIndex", index, length);
 387     }
 388 
 389     private static RuntimeException outOfBoundsCheckFromToIndex(
 390             BiFunction<String, List<Integer>, ? extends RuntimeException> oobe,
 391             int fromIndex, int toIndex, int length) {
 392         return outOfBounds(oobe, "checkFromToIndex", fromIndex, toIndex, length);
 393     }
 394 
 395     private static RuntimeException outOfBoundsCheckFromIndexSize(
 396             BiFunction<String, List<Integer>, ? extends RuntimeException> oobe,
 397             int fromIndex, int size, int length) {
 398         return outOfBounds(oobe, "checkFromIndexSize", fromIndex, size, length);
 399     }
 400 
 401     /**
 402      * Returns an out-of-bounds exception formatter from an given exception
 403      * factory.  The exception formatter is a function that formats an
 404      * out-of-bounds message from its arguments and applies that message to the
 405      * given exception factory to produce and relay an exception.
 406      *
 407      * <p>The exception formatter accepts two arguments: a {@code String}
 408      * describing the out-of-bounds range check that failed, referred to as the
 409      * <em>check kind</em>; and a {@code List<Integer>} containing the
 410      * out-of-bound integer values that failed the check.  The list of
 411      * out-of-bound values is not modified.
 412      *
 413      * <p>Three check kinds are supported {@code checkIndex},
 414      * {@code checkFromToIndex} and {@code checkFromIndexSize} corresponding
 415      * respectively to the specified application of an exception formatter as an
 416      * argument to the out-of-bounds range check methods
 417      * {@link #checkIndex(int, int, BiFunction) checkIndex},
 418      * {@link #checkFromToIndex(int, int, int, BiFunction) checkFromToIndex}, and
 419      * {@link #checkFromIndexSize(int, int, int, BiFunction) checkFromIndexSize}.
 420      * Thus a supported check kind corresponds to a method name and the
 421      * out-of-bound integer values correspond to method argument values, in
 422      * order, preceding the exception formatter argument (similar in many
 423      * respects to the form of arguments required for a reflective invocation of
 424      * such a range check method).
 425      *
 426      * <p>Formatter arguments conforming to such supported check kinds will
 427      * produce specific exception messages describing failed out-of-bounds
 428      * checks.  Otherwise, more generic exception messages will be produced in
 429      * any of the following cases: the check kind is supported but fewer
 430      * or more out-of-bounds values are supplied, the check kind is not
 431      * supported, the check kind is {@code null}, or the list of out-of-bound
 432      * values is {@code null}.
 433      *
 434      * @apiNote
 435      * This method produces an out-of-bounds exception formatter that can be
 436      * passed as an argument to any of the supported out-of-bounds range check
 437      * methods declared by {@code Objects}.  For example, a formatter producing
 438      * an {@code ArrayIndexOutOfBoundsException} may be produced and stored on a
 439      * {@code static final} field as follows:
 440      * <pre>{@code
 441      * static final
 442      * BiFunction<String, List<Integer>, ArrayIndexOutOfBoundsException> AIOOBEF =
 443      *     outOfBoundsExceptionFormatter(ArrayIndexOutOfBoundsException::new);
 444      * }</pre>
 445      * The formatter instance {@code AIOOBEF} may be passed as an argument to an
 446      * out-of-bounds range check method, such as checking if an {@code index}
 447      * is within the bounds of a {@code limit}:
 448      * <pre>{@code
 449      * checkIndex(index, limit, AIOOBEF);
 450      * }</pre>
 451      * If the bounds check fails then the range check method will throw an
 452      * {@code ArrayIndexOutOfBoundsException} with an appropriate exception
 453      * message that is a produced from {@code AIOOBEF} as follows:
 454      * <pre>{@code
 455      * AIOOBEF.apply("checkIndex", List.of(index, limit));
 456      * }</pre>
 457      *
 458      * @param f the exception factory, that produces an exception from a message
 459      *        where the message is produced and formatted by the returned
 460      *        exception formatter.  If this factory is stateless and side-effect
 461      *        free then so is the returned formatter.
 462      *        Exceptions thrown by the factory are relayed to the caller
 463      *        of the returned formatter.
 464      * @param <X> the type of runtime exception to be returned by the given
 465      *        exception factory and relayed by the exception formatter
 466      * @return the out-of-bounds exception formatter
 467      */
 468     public static <X extends RuntimeException>
 469     BiFunction<String, List<Integer>, X> outOfBoundsExceptionFormatter(Function<String, X> f) {
 470         // Use anonymous class to avoid bootstrap issues if this method is
 471         // used early in startup
 472         return new BiFunction<String, List<Integer>, X>() {
 473             @Override
 474             public X apply(String checkKind, List<Integer> args) {
 475                 return f.apply(outOfBoundsMessage(checkKind, args));
 476             }
 477         };
 478     }
 479 
 480     private static String outOfBoundsMessage(String checkKind, List<Integer> args) {
 481         if (checkKind == null && args == null) {
 482             return String.format("Range check failed");
 483         } else if (checkKind == null) {
 484             return String.format("Range check failed: %s", args);
 485         } else if (args == null) {
 486             return String.format("Range check failed: %s", checkKind);
 487         }
 488 
 489         int argSize = 0;
 490         switch (checkKind) {
 491             case "checkIndex":
 492                 argSize = 2;
 493                 break;
 494             case "checkFromToIndex":
 495             case "checkFromIndexSize":
 496                 argSize = 3;
 497                 break;
 498             default:
 499         }
 500 
 501         // Switch to default if fewer or more arguments than required are supplied
 502         switch ((args.size() != argSize) ? "" : checkKind) {
 503             case "checkIndex":
 504                 return String.format("Index %d out-of-bounds for length %d",
 505                                      args.get(0), args.get(1));
 506             case "checkFromToIndex":
 507                 return String.format("Range [%d, %d) out-of-bounds for length %d",
 508                                      args.get(0), args.get(1), args.get(2));
 509             case "checkFromIndexSize":
 510                 return String.format("Range [%d, %<d + %d) out-of-bounds for length %d",
 511                                      args.get(0), args.get(1), args.get(2));
 512             default:
 513                 return String.format("Range check failed: %s %s", checkKind, args);
 514         }
 515     }
 516 
 517     /**
 518      * Checks if the {@code index} is within the bounds of the range from
 519      * {@code 0} (inclusive) to {@code length} (exclusive).
 520      *
 521      * <p>The {@code index} is defined to be out-of-bounds if any of the
 522      * following inequalities is true:
 523      * <ul>
 524      *  <li>{@code index < 0}</li>
 525      *  <li>{@code index >= length}</li>
 526      *  <li>{@code length < 0}, which is implied from the former inequalities</li>
 527      * </ul>
 528      *
 529      * <p>This method behaves as if {@link #checkIndex(int, int, BiFunction)}
 530      * was called with same out-of-bounds arguments and an exception formatter
 531      * argument produced from an invocation of
 532      * {@code outOfBoundsExceptionFormatter(IndexOutOfBounds::new)} (though it may
 533      * be more efficient).
 534      *
 535      * @param index the index
 536      * @param length the upper-bound (exclusive) of the range
 537      * @return {@code index} if it is within bounds of the range
 538      * @throws IndexOutOfBoundsException if the {@code index} is out-of-bounds
 539      * @since 9
 540      */

 541     public static
 542     int checkIndex(int index, int length) {
 543         return checkIndex(index, length, null);
 544     }
 545 
 546     /**
 547      * Checks if the {@code index} is within the bounds of the range from
 548      * {@code 0} (inclusive) to {@code length} (exclusive).
 549      *
 550      * <p>The {@code index} is defined to be out-of-bounds if any of the
 551      * following inequalities is true:
 552      * <ul>
 553      *  <li>{@code index < 0}</li>
 554      *  <li>{@code index >= length}</li>
 555      *  <li>{@code length < 0}, which is implied from the former inequalities</li>
 556      * </ul>
 557      *
 558      * <p>If the {@code index} is out-of-bounds, then a runtime exception is
 559      * thrown that is the result of applying the following arguments to the
 560      * exception formatter: the name of this method, {@code checkIndex};
 561      * and an unmodifiable list integers whose values are, in order, the
 562      * out-of-bounds arguments {@code index} and {@code length}.
 563      *
 564      * @param <X> the type of runtime exception to throw if the arguments are
 565      *        out-of-bounds
 566      * @param index the index
 567      * @param length the upper-bound (exclusive) of the range
 568      * @param oobef the exception formatter that when applied with this
 569      *        method name and out-of-bounds arguments returns a runtime
 570      *        exception.  If {@code null} or returns {@code null} then, it is as
 571      *        if an exception formatter produced from an invocation of
 572      *        {@code outOfBoundsExceptionFormatter(IndexOutOfBounds::new)} is used
 573      *        instead (though it may be more efficient).
 574      *        Exceptions thrown by the formatter are relayed to the caller.
 575      * @return {@code index} if it is within bounds of the range
 576      * @throws X if the {@code index} is out-of-bounds and the exception
 577      *         formatter is non-{@code null}
 578      * @throws IndexOutOfBoundsException if the {@code index} is out-of-bounds
 579      *         and the exception formatter is {@code null}
 580      * @since 9
 581      *
 582      * @implNote
 583      * This method is made intrinsic in optimizing compilers to guide them to
 584      * perform unsigned comparisons of the index and length when it is known the
 585      * length is a non-negative value (such as that of an array length or from
 586      * the upper bound of a loop)
 587     */
 588     @HotSpotIntrinsicCandidate
 589     public static <X extends RuntimeException>
 590     int checkIndex(int index, int length,
 591                    BiFunction<String, List<Integer>, X> oobef) {
 592         if (index < 0 || index >= length)
 593             throw outOfBoundsCheckIndex(oobef, index, length);
 594         return index;
 595     }
 596 
 597     /**
 598      * Checks if the sub-range from {@code fromIndex} (inclusive) to
 599      * {@code toIndex} (exclusive) is within the bounds of range from {@code 0}
 600      * (inclusive) to {@code length} (exclusive).
 601      *
 602      * <p>The sub-range is defined to be out-of-bounds if any of the following
 603      * inequalities is true:
 604      * <ul>
 605      *  <li>{@code fromIndex < 0}</li>
 606      *  <li>{@code fromIndex > toIndex}</li>
 607      *  <li>{@code toIndex > length}</li>
 608      *  <li>{@code length < 0}, which is implied from the former inequalities</li>
 609      * </ul>
 610      *
 611      * <p>This method behaves as if {@link #checkFromToIndex(int, int, int, BiFunction)}
 612      * was called with same out-of-bounds arguments and an exception formatter
 613      * argument produced from an invocation of
 614      * {@code outOfBoundsExceptionFormatter(IndexOutOfBounds::new)} (though it may
 615      * be more efficient).
 616      *
 617      * @param fromIndex the lower-bound (inclusive) of the sub-range
 618      * @param toIndex the upper-bound (exclusive) of the sub-range
 619      * @param length the upper-bound (exclusive) the range
 620      * @return {@code fromIndex} if the sub-range within bounds of the range
 621      * @throws IndexOutOfBoundsException if the sub-range is out-of-bounds
 622      * @since 9
 623      */
 624     public static
 625     int checkFromToIndex(int fromIndex, int toIndex, int length) {
 626         return checkFromToIndex(fromIndex, toIndex, length, null);
 627     }
 628 
 629     /**
 630      * Checks if the sub-range from {@code fromIndex} (inclusive) to
 631      * {@code toIndex} (exclusive) is within the bounds of range from {@code 0}
 632      * (inclusive) to {@code length} (exclusive).
 633      *
 634      * <p>The sub-range is defined to be out-of-bounds if any of the following
 635      * inequalities is true:
 636      * <ul>
 637      *  <li>{@code fromIndex < 0}</li>
 638      *  <li>{@code fromIndex > toIndex}</li>
 639      *  <li>{@code toIndex > length}</li>
 640      *  <li>{@code length < 0}, which is implied from the former inequalities</li>
 641      * </ul>
 642      *
 643      * <p>If the sub-range  is out-of-bounds, then a runtime exception is
 644      * thrown that is the result of applying the following arguments to the
 645      * exception formatter: the name of this method, {@code checkFromToIndex};
 646      * and an unmodifiable list integers whose values are, in order, the
 647      * out-of-bounds arguments {@code fromIndex}, {@code toIndex}, and {@code length}.
 648      *
 649      * @param <X> the type of runtime exception to throw if the arguments are
 650      *        out-of-bounds
 651      * @param fromIndex the lower-bound (inclusive) of the sub-range
 652      * @param toIndex the upper-bound (exclusive) of the sub-range
 653      * @param length the upper-bound (exclusive) the range
 654      * @param oobef the exception formatter that when applied with this
 655      *        method name and out-of-bounds arguments returns a runtime
 656      *        exception.  If {@code null} or returns {@code null} then, it is as
 657      *        if an exception formatter produced from an invocation of
 658      *        {@code outOfBoundsExceptionFormatter(IndexOutOfBounds::new)} is used
 659      *        instead (though it may be more efficient).
 660      *        Exceptions thrown by the formatter are relayed to the caller.
 661      * @return {@code fromIndex} if the sub-range within bounds of the range
 662      * @throws X if the sub-range is out-of-bounds and the exception factory
 663      *         function is non-{@code null}
 664      * @throws IndexOutOfBoundsException if the sub-range is out-of-bounds and
 665      *         the exception factory function is {@code null}
 666      * @since 9
 667      */
 668     public static <X extends RuntimeException>
 669     int checkFromToIndex(int fromIndex, int toIndex, int length,
 670                          BiFunction<String, List<Integer>, X> oobef) {
 671         if (fromIndex < 0 || fromIndex > toIndex || toIndex > length)
 672             throw outOfBoundsCheckFromToIndex(oobef, fromIndex, toIndex, length);
 673         return fromIndex;
 674     }
 675 
 676     /**
 677      * Checks if the sub-range from {@code fromIndex} (inclusive) to
 678      * {@code fromIndex + size} (exclusive) is within the bounds of range from
 679      * {@code 0} (inclusive) to {@code length} (exclusive).
 680      *
 681      * <p>The sub-range is defined to be out-of-bounds if any of the following
 682      * inequalities is true:
 683      * <ul>
 684      *  <li>{@code fromIndex < 0}</li>
 685      *  <li>{@code size < 0}</li>
 686      *  <li>{@code fromIndex + size > length}, taking into account integer overflow</li>
 687      *  <li>{@code length < 0}, which is implied from the former inequalities</li>
 688      * </ul>
 689      *
 690      * <p>This method behaves as if {@link #checkFromIndexSize(int, int, int, BiFunction)}
 691      * was called with same out-of-bounds arguments and an exception formatter
 692      * argument produced from an invocation of
 693      * {@code outOfBoundsExceptionFormatter(IndexOutOfBounds::new)} (though it may
 694      * be more efficient).
 695      *
 696      * @param fromIndex the lower-bound (inclusive) of the sub-interval
 697      * @param size the size of the sub-range
 698      * @param length the upper-bound (exclusive) of the range
 699      * @return {@code fromIndex} if the sub-range within bounds of the range
 700      * @throws IndexOutOfBoundsException if the sub-range is out-of-bounds
 701      * @since 9
 702      */
 703     public static
 704     int checkFromIndexSize(int fromIndex, int size, int length) {
 705         return checkFromIndexSize(fromIndex, size, length, null);
 706     }
 707 
 708     /**
 709      * Checks if the sub-range from {@code fromIndex} (inclusive) to
 710      * {@code fromIndex + size} (exclusive) is within the bounds of range from
 711      * {@code 0} (inclusive) to {@code length} (exclusive).
 712      *
 713      * <p>The sub-range is defined to be out-of-bounds if any of the following
 714      * inequalities is true:
 715      * <ul>
 716      *  <li>{@code fromIndex < 0}</li>
 717      *  <li>{@code size < 0}</li>
 718      *  <li>{@code fromIndex + size > length}, taking into account integer overflow</li>
 719      *  <li>{@code length < 0}, which is implied from the former inequalities</li>
 720      * </ul>
 721      *
 722      * <p>If the sub-range  is out-of-bounds, then a runtime exception is
 723      * thrown that is the result of applying the following arguments to the
 724      * exception formatter: the name of this method, {@code checkFromIndexSize};
 725      * and an unmodifiable list integers whose values are, in order, the
 726      * out-of-bounds arguments {@code fromIndex}, {@code size}, and
 727      * {@code length}.
 728      *
 729      * @param <X> the type of runtime exception to throw if the arguments are
 730      *        out-of-bounds
 731      * @param fromIndex the lower-bound (inclusive) of the sub-interval
 732      * @param size the size of the sub-range
 733      * @param length the upper-bound (exclusive) of the range
 734      * @param oobef the exception formatter that when applied with this
 735      *        method name and out-of-bounds arguments returns a runtime
 736      *        exception.  If {@code null} or returns {@code null} then, it is as
 737      *        if an exception formatter produced from an invocation of
 738      *        {@code outOfBoundsExceptionFormatter(IndexOutOfBounds::new)} is used
 739      *        instead (though it may be more efficient).
 740      *        Exceptions thrown by the formatter are relayed to the caller.
 741      * @return {@code fromIndex} if the sub-range within bounds of the range
 742      * @throws X if the sub-range is out-of-bounds and the exception factory
 743      *         function is non-{@code null}
 744      * @throws IndexOutOfBoundsException if the sub-range is out-of-bounds and
 745      *         the exception factory function is {@code null}
 746      * @since 9
 747      */
 748     public static <X extends RuntimeException>
 749     int checkFromIndexSize(int fromIndex, int size, int length,
 750                            BiFunction<String, List<Integer>, X> oobef) {
 751         if ((length | fromIndex | size) < 0 || size > length - fromIndex)
 752             throw outOfBoundsCheckFromIndexSize(oobef, fromIndex, size, length);
 753         return fromIndex;
 754     }
 755 }
   1 /*
   2  * Copyright (c) 2009, 2016, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.util;
  27 
  28 import jdk.internal.util.Preconditions;
  29 import jdk.internal.vm.annotation.ForceInline;
  30 


  31 import java.util.function.Supplier;
  32 
  33 /**
  34  * This class consists of {@code static} utility methods for operating
  35  * on objects, or checking certain conditions before operation.  These utilities
  36  * include {@code null}-safe or {@code null}-tolerant methods for computing the
  37  * hash code of an object, returning a string for an object, comparing two
  38  * objects, and checking if indexes or sub-range values are out-of-bounds.
  39  *
  40  * @apiNote
  41  * Static methods such as {@link Objects#checkIndex},
  42  * {@link Objects#checkFromToIndex}, and {@link Objects#checkFromIndexSize} are
  43  * provided for the convenience of checking if values corresponding to indexes
  44  * and sub-ranges are out-of-bounds.
  45  * Variations of these static methods support customization of the runtime
  46  * exception, and corresponding exception detail message, that is thrown when
  47  * values are out-of-bounds.  Such methods accept a functional interface
  48  * argument, instances of {@code BiFunction}, that maps out-of-bound values to a
  49  * runtime exception.  Care should be taken when using such methods in
  50  * combination with an argument that is a lambda expression, method reference or


 331      * performance advantage in the non-null case, when deciding to
 332      * call this method care should be taken that the costs of
 333      * creating the message supplier are less than the cost of just
 334      * creating the string message directly.
 335      *
 336      * @param obj     the object reference to check for nullity
 337      * @param messageSupplier supplier of the detail message to be
 338      * used in the event that a {@code NullPointerException} is thrown
 339      * @param <T> the type of the reference
 340      * @return {@code obj} if not {@code null}
 341      * @throws NullPointerException if {@code obj} is {@code null}
 342      * @since 1.8
 343      */
 344     public static <T> T requireNonNull(T obj, Supplier<String> messageSupplier) {
 345         if (obj == null)
 346             throw new NullPointerException(messageSupplier.get());
 347         return obj;
 348     }
 349 
 350     /**






































































































































































 351      * Checks if the {@code index} is within the bounds of the range from
 352      * {@code 0} (inclusive) to {@code length} (exclusive).
 353      *
 354      * <p>The {@code index} is defined to be out-of-bounds if any of the
 355      * following inequalities is true:
 356      * <ul>
 357      *  <li>{@code index < 0}</li>
 358      *  <li>{@code index >= length}</li>
 359      *  <li>{@code length < 0}, which is implied from the former inequalities</li>
 360      * </ul>
 361      *






 362      * @param index the index
 363      * @param length the upper-bound (exclusive) of the range
 364      * @return {@code index} if it is within bounds of the range
 365      * @throws IndexOutOfBoundsException if the {@code index} is out-of-bounds
 366      * @since 9
 367      */
 368     @ForceInline
 369     public static
 370     int checkIndex(int index, int length) {
 371         return Preconditions.checkIndex(index, length, null);



















































 372     }
 373 
 374     /**
 375      * Checks if the sub-range from {@code fromIndex} (inclusive) to
 376      * {@code toIndex} (exclusive) is within the bounds of range from {@code 0}
 377      * (inclusive) to {@code length} (exclusive).
 378      *
 379      * <p>The sub-range is defined to be out-of-bounds if any of the following
 380      * inequalities is true:
 381      * <ul>
 382      *  <li>{@code fromIndex < 0}</li>
 383      *  <li>{@code fromIndex > toIndex}</li>
 384      *  <li>{@code toIndex > length}</li>
 385      *  <li>{@code length < 0}, which is implied from the former inequalities</li>
 386      * </ul>
 387      *






 388      * @param fromIndex the lower-bound (inclusive) of the sub-range
 389      * @param toIndex the upper-bound (exclusive) of the sub-range
 390      * @param length the upper-bound (exclusive) the range
 391      * @return {@code fromIndex} if the sub-range within bounds of the range
 392      * @throws IndexOutOfBoundsException if the sub-range is out-of-bounds
 393      * @since 9
 394      */
 395     public static
 396     int checkFromToIndex(int fromIndex, int toIndex, int length) {
 397         return Preconditions.checkFromToIndex(fromIndex, toIndex, length, null);















































 398     }
 399 
 400     /**
 401      * Checks if the sub-range from {@code fromIndex} (inclusive) to
 402      * {@code fromIndex + size} (exclusive) is within the bounds of range from
 403      * {@code 0} (inclusive) to {@code length} (exclusive).
 404      *
 405      * <p>The sub-range is defined to be out-of-bounds if any of the following
 406      * inequalities is true:
 407      * <ul>
 408      *  <li>{@code fromIndex < 0}</li>
 409      *  <li>{@code size < 0}</li>
 410      *  <li>{@code fromIndex + size > length}, taking into account integer overflow</li>
 411      *  <li>{@code length < 0}, which is implied from the former inequalities</li>
 412      * </ul>
 413      *






 414      * @param fromIndex the lower-bound (inclusive) of the sub-interval
 415      * @param size the size of the sub-range
 416      * @param length the upper-bound (exclusive) of the range
 417      * @return {@code fromIndex} if the sub-range within bounds of the range
 418      * @throws IndexOutOfBoundsException if the sub-range is out-of-bounds
 419      * @since 9
 420      */
 421     public static
 422     int checkFromIndexSize(int fromIndex, int size, int length) {
 423         return Preconditions.checkFromIndexSize(fromIndex, size, length, null);
 424     }
 425 















































 426 }
< prev index next >