8255150: Add utility methods to check long indexes and ranges

Co-authored-by: Paul Sandoz <psandoz@openjdk.org>
Reviewed-by: jvernee, dlong, vlivanov

src/java.base/share/classes/java/lang/IndexOutOfBoundsException.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1995, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1995, 2020, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -68,4 +68,18 @@ public class IndexOutOfBoundsException extends RuntimeException {
     public IndexOutOfBoundsException(int index) {
         super("Index out of range: " + index);
     }
+
+    /**
+     * Constructs a new {@code IndexOutOfBoundsException} class with an
+     * argument indicating the illegal index.
+     *
+     * <p>The index is included in this exception's detail message.  The
+     * exact presentation format of the detail message is unspecified.
+     *
+     * @param index the illegal index.
+     * @since 16
+     */
+    public IndexOutOfBoundsException(long index) {
+        super("Index out of range: " + index);
+    }
 }

src/java.base/share/classes/java/lang/invoke/VarHandle.java

@@ -2146,7 +2146,7 @@ public abstract class VarHandle implements Constable {
         UNSAFE.fullFence();
     }
 
-    static final BiFunction<String, List<Integer>, ArrayIndexOutOfBoundsException>
+    static final BiFunction<String, List<Number>, ArrayIndexOutOfBoundsException>
             AIOOBE_SUPPLIER = Preconditions.outOfBoundsExceptionFormatter(
             new Function<String, ArrayIndexOutOfBoundsException>() {
                 @Override

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

@@ -411,4 +411,79 @@ public final class Objects {
         return Preconditions.checkFromIndexSize(fromIndex, size, length, null);
     }
 
+    /**
+     * Checks if the {@code index} is within the bounds of the range from
+     * {@code 0} (inclusive) to {@code length} (exclusive).
+     *
+     * <p>The {@code index} is defined to be out of bounds if any of the
+     * following inequalities is true:
+     * <ul>
+     *  <li>{@code index < 0}</li>
+     *  <li>{@code index >= length}</li>
+     *  <li>{@code length < 0}, which is implied from the former inequalities</li>
+     * </ul>
+     *
+     * @param index the index
+     * @param length the upper-bound (exclusive) of the range
+     * @return {@code index} if it is within bounds of the range
+     * @throws IndexOutOfBoundsException if the {@code index} is out of bounds
+     * @since 16
+     */
+    @ForceInline
+    public static
+    long checkIndex(long index, long length) {
+        return Preconditions.checkIndex(index, length, null);
+    }
+
+    /**
+     * Checks if the sub-range from {@code fromIndex} (inclusive) to
+     * {@code toIndex} (exclusive) is within the bounds of range from {@code 0}
+     * (inclusive) to {@code length} (exclusive).
+     *
+     * <p>The sub-range is defined to be out of bounds if any of the following
+     * inequalities is true:
+     * <ul>
+     *  <li>{@code fromIndex < 0}</li>
+     *  <li>{@code fromIndex > toIndex}</li>
+     *  <li>{@code toIndex > length}</li>
+     *  <li>{@code length < 0}, which is implied from the former inequalities</li>
+     * </ul>
+     *
+     * @param fromIndex the lower-bound (inclusive) of the sub-range
+     * @param toIndex the upper-bound (exclusive) of the sub-range
+     * @param length the upper-bound (exclusive) the range
+     * @return {@code fromIndex} if the sub-range within bounds of the range
+     * @throws IndexOutOfBoundsException if the sub-range is out of bounds
+     * @since 16
+     */
+    public static
+    long checkFromToIndex(long fromIndex, long toIndex, long length) {
+        return Preconditions.checkFromToIndex(fromIndex, toIndex, length, null);
+    }
+
+    /**
+     * Checks if the sub-range from {@code fromIndex} (inclusive) to
+     * {@code fromIndex + size} (exclusive) is within the bounds of range from
+     * {@code 0} (inclusive) to {@code length} (exclusive).
+     *
+     * <p>The sub-range is defined to be out of bounds if any of the following
+     * inequalities is true:
+     * <ul>
+     *  <li>{@code fromIndex < 0}</li>
+     *  <li>{@code size < 0}</li>
+     *  <li>{@code fromIndex + size > length}, taking into account integer overflow</li>
+     *  <li>{@code length < 0}, which is implied from the former inequalities</li>
+     * </ul>
+     *
+     * @param fromIndex the lower-bound (inclusive) of the sub-interval
+     * @param size the size of the sub-range
+     * @param length the upper-bound (exclusive) of the range
+     * @return {@code fromIndex} if the sub-range within bounds of the range
+     * @throws IndexOutOfBoundsException if the sub-range is out of bounds
+     * @since 16
+     */
+    public static
+    long checkFromIndexSize(long fromIndex, long size, long length) {
+        return Preconditions.checkFromIndexSize(fromIndex, size, length, null);
+    }
 }