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
51 * class that capture values. In such cases the cost of capture, related to
52 * functional interface allocation, may exceed the cost of checking bounds.
53 *
54 * @since 1.7
55 */
56 public final class Objects {
57 private Objects() {
58 throw new AssertionError("No java.util.Objects instances for you!");
59 }
60
61 /**
62 * Returns {@code true} if the arguments are equal to each other
63 * and {@code false} otherwise.
64 * Consequently, if both arguments are {@code null}, {@code true}
65 * is returned and if exactly one argument is {@code null}, {@code
66 * false} is returned. Otherwise, equality is determined by using
67 * the {@link Object#equals equals} method of the first
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 == null ?
347 null : messageSupplier.get());
348 return obj;
349 }
350
351 /**
352 * Checks if the {@code index} is within the bounds of the range from
353 * {@code 0} (inclusive) to {@code length} (exclusive).
354 *
355 * <p>The {@code index} is defined to be out-of-bounds if any of the
356 * following inequalities is true:
357 * <ul>
358 * <li>{@code index < 0}</li>
359 * <li>{@code index >= length}</li>
360 * <li>{@code length < 0}, which is implied from the former inequalities</li>
361 * </ul>
362 *
363 * @param index the index
364 * @param length the upper-bound (exclusive) of the range
365 * @return {@code index} if it is within bounds of the range
366 * @throws IndexOutOfBoundsException if the {@code index} is out-of-bounds
367 * @since 9
368 */
369 @ForceInline
370 public static
371 int checkIndex(int index, int length) {
372 return Preconditions.checkIndex(index, length, null);
373 }
374
375 /**
376 * Checks if the sub-range from {@code fromIndex} (inclusive) to
377 * {@code toIndex} (exclusive) is within the bounds of range from {@code 0}
378 * (inclusive) to {@code length} (exclusive).
379 *
380 * <p>The sub-range is defined to be out-of-bounds if any of the following
381 * inequalities is true:
382 * <ul>
383 * <li>{@code fromIndex < 0}</li>
384 * <li>{@code fromIndex > toIndex}</li>
385 * <li>{@code toIndex > length}</li>
386 * <li>{@code length < 0}, which is implied from the former inequalities</li>
387 * </ul>
388 *
389 * @param fromIndex the lower-bound (inclusive) of the sub-range
390 * @param toIndex the upper-bound (exclusive) of the sub-range
391 * @param length the upper-bound (exclusive) the range
392 * @return {@code fromIndex} if the sub-range within bounds of the range
393 * @throws IndexOutOfBoundsException if the sub-range is out-of-bounds
394 * @since 9
395 */
396 public static
397 int checkFromToIndex(int fromIndex, int toIndex, int length) {
398 return Preconditions.checkFromToIndex(fromIndex, toIndex, length, null);
399 }
400
401 /**
402 * Checks if the sub-range from {@code fromIndex} (inclusive) to
403 * {@code fromIndex + size} (exclusive) is within the bounds of range from
404 * {@code 0} (inclusive) to {@code length} (exclusive).
405 *
406 * <p>The sub-range is defined to be out-of-bounds if any of the following
407 * inequalities is true:
408 * <ul>
409 * <li>{@code fromIndex < 0}</li>
410 * <li>{@code size < 0}</li>
411 * <li>{@code fromIndex + size > length}, taking into account integer overflow</li>
412 * <li>{@code length < 0}, which is implied from the former inequalities</li>
413 * </ul>
414 *
415 * @param fromIndex the lower-bound (inclusive) of the sub-interval
416 * @param size the size of the sub-range
417 * @param length the upper-bound (exclusive) of the range
418 * @return {@code fromIndex} if the sub-range within bounds of the range
419 * @throws IndexOutOfBoundsException if the sub-range is out-of-bounds
420 * @since 9
421 */
422 public static
423 int checkFromIndexSize(int fromIndex, int size, int length) {
424 return Preconditions.checkFromIndexSize(fromIndex, size, length, null);
425 }
426
427 }
|
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
51 * class that capture values. In such cases the cost of capture, related to
52 * functional interface allocation, may exceed the cost of checking bounds.
53 *
54 * @since 1.7
55 */
56 public final class Objects {
57 private Objects() {
58 throw new AssertionError("No java.util.Objects instances for you!");
59 }
60
61 /**
62 * Returns {@code true} if the arguments are equal to each other
63 * and {@code false} otherwise.
64 * Consequently, if both arguments are {@code null}, {@code true}
65 * is returned and if exactly one argument is {@code null}, {@code
66 * false} is returned. Otherwise, equality is determined by using
67 * the {@link Object#equals equals} method of the first
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 == null ?
347 null : messageSupplier.get());
348 return obj;
349 }
350
351 /**
352 * Checks if the {@code index} is within the bounds of the range from
353 * {@code 0} (inclusive) to {@code length} (exclusive).
354 *
355 * <p>The {@code index} is defined to be out of bounds if any of the
356 * following inequalities is true:
357 * <ul>
358 * <li>{@code index < 0}</li>
359 * <li>{@code index >= length}</li>
360 * <li>{@code length < 0}, which is implied from the former inequalities</li>
361 * </ul>
362 *
363 * @param index the index
364 * @param length the upper-bound (exclusive) of the range
365 * @return {@code index} if it is within bounds of the range
366 * @throws IndexOutOfBoundsException if the {@code index} is out of bounds
367 * @since 9
368 */
369 @ForceInline
370 public static
371 int checkIndex(int index, int length) {
372 return Preconditions.checkIndex(index, length, null);
373 }
374
375 /**
376 * Checks if the sub-range from {@code fromIndex} (inclusive) to
377 * {@code toIndex} (exclusive) is within the bounds of range from {@code 0}
378 * (inclusive) to {@code length} (exclusive).
379 *
380 * <p>The sub-range is defined to be out of bounds if any of the following
381 * inequalities is true:
382 * <ul>
383 * <li>{@code fromIndex < 0}</li>
384 * <li>{@code fromIndex > toIndex}</li>
385 * <li>{@code toIndex > length}</li>
386 * <li>{@code length < 0}, which is implied from the former inequalities</li>
387 * </ul>
388 *
389 * @param fromIndex the lower-bound (inclusive) of the sub-range
390 * @param toIndex the upper-bound (exclusive) of the sub-range
391 * @param length the upper-bound (exclusive) the range
392 * @return {@code fromIndex} if the sub-range within bounds of the range
393 * @throws IndexOutOfBoundsException if the sub-range is out of bounds
394 * @since 9
395 */
396 public static
397 int checkFromToIndex(int fromIndex, int toIndex, int length) {
398 return Preconditions.checkFromToIndex(fromIndex, toIndex, length, null);
399 }
400
401 /**
402 * Checks if the sub-range from {@code fromIndex} (inclusive) to
403 * {@code fromIndex + size} (exclusive) is within the bounds of range from
404 * {@code 0} (inclusive) to {@code length} (exclusive).
405 *
406 * <p>The sub-range is defined to be out of bounds if any of the following
407 * inequalities is true:
408 * <ul>
409 * <li>{@code fromIndex < 0}</li>
410 * <li>{@code size < 0}</li>
411 * <li>{@code fromIndex + size > length}, taking into account integer overflow</li>
412 * <li>{@code length < 0}, which is implied from the former inequalities</li>
413 * </ul>
414 *
415 * @param fromIndex the lower-bound (inclusive) of the sub-interval
416 * @param size the size of the sub-range
417 * @param length the upper-bound (exclusive) of the range
418 * @return {@code fromIndex} if the sub-range within bounds of the range
419 * @throws IndexOutOfBoundsException if the sub-range is out of bounds
420 * @since 9
421 */
422 public static
423 int checkFromIndexSize(int fromIndex, int size, int length) {
424 return Preconditions.checkFromIndexSize(fromIndex, size, length, null);
425 }
426
427 }
|