java9.util

Class Objects

java.lang.Object

java9.util.Objects

public final class Objects
extends Object

This class consists of static utility methods for operating on objects, or checking certain conditions before operation. These utilities include null-safe or null-tolerant methods and methods for checking if indexes or sub-range values are out-of-bounds.

API Note:
Static methods such as checkIndex(int, int), checkFromToIndex(int, int, int), and checkFromIndexSize(int, int, int) are provided for the convenience of checking if values corresponding to indexes and sub-ranges are out-of-bounds.

Since:

9

Method Summary

Modifier and Type	Method and Description
static int	checkFromIndexSize(int fromIndex, int size, int length) Checks if the sub-range from fromIndex (inclusive) to fromIndex + size (exclusive) is within the bounds of range from 0 (inclusive) to length (exclusive).
static long	checkFromIndexSize(long fromIndex, long size, long length) Checks if the sub-range from fromIndex (inclusive) to fromIndex + size (exclusive) is within the bounds of range from 0 (inclusive) to length (exclusive).
static int	checkFromToIndex(int fromIndex, int toIndex, int length) Checks if the sub-range from fromIndex (inclusive) to toIndex (exclusive) is within the bounds of range from 0 (inclusive) to length (exclusive).
static long	checkFromToIndex(long fromIndex, long toIndex, long length) Checks if the sub-range from fromIndex (inclusive) to toIndex (exclusive) is within the bounds of range from 0 (inclusive) to length (exclusive).
static int	checkIndex(int index, int length) Checks if the index is within the bounds of the range from 0 (inclusive) to length (exclusive).
static long	checkIndex(long index, long length) Checks if the index is within the bounds of the range from 0 (inclusive) to length (exclusive).
static <T> T	requireNonNullElse(T obj, T defaultObj) Returns the first argument if it is non-null and otherwise returns the non-null second argument.
static <T> T	requireNonNullElseGet(T obj, Supplier<? extends T> supplier) Returns the first argument if it is non-null and otherwise returns the non-null value of supplier.get().

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

requireNonNullElse

public static <T> T requireNonNullElse(T obj,
                                       T defaultObj)

Returns the first argument if it is non-null and otherwise returns the non-null second argument.

Type Parameters:

T - the type of the reference

Parameters:

obj - an object

defaultObj - a non-null object to return if the first argument is null

Returns:

the first argument if it is non-null and otherwise the second argument if it is non-null

Throws:

NullPointerException - if both obj is null and defaultObj is null

Since:

9

requireNonNullElseGet

public static <T> T requireNonNullElseGet(T obj,
                                          Supplier<? extends T> supplier)

Returns the first argument if it is non-null and otherwise returns the non-null value of supplier.get().

Type Parameters:

T - the type of the first argument and return type

Parameters:

obj - an object

supplier - of a non-null object to return if the first argument is null

Returns:

the first argument if it is non-null and otherwise the value from supplier.get() if it is non-null

Throws:

NullPointerException - if both obj is null and either the supplier is null or the supplier.get() value is null

Since:

9

checkIndex

public static int checkIndex(int index,
                             int length)

Checks if the index is within the bounds of the range from 0 (inclusive) to length (exclusive).

The index is defined to be out-of-bounds if any of the following inequalities is true:

• index < 0
• index >= length
• length < 0, which is implied from the former inequalities

Parameters:

index - the index

length - the upper-bound (exclusive) of the range

Returns:

index if it is within bounds of the range

Throws:

IndexOutOfBoundsException - if the index is out-of-bounds

Since:

9

checkFromToIndex

public static int checkFromToIndex(int fromIndex,
                                   int toIndex,
                                   int length)

Checks if the sub-range from fromIndex (inclusive) to toIndex (exclusive) is within the bounds of range from 0 (inclusive) to length (exclusive).

The sub-range is defined to be out-of-bounds if any of the following inequalities is true:

• fromIndex < 0
• fromIndex > toIndex
• toIndex > length
• length < 0, which is implied from the former inequalities

Parameters:

fromIndex - the lower-bound (inclusive) of the sub-range

toIndex - the upper-bound (exclusive) of the sub-range

length - the upper-bound (exclusive) the range

Returns:

fromIndex if the sub-range is within bounds of the range

Throws:

IndexOutOfBoundsException - if the sub-range is out-of-bounds

Since:

9

checkFromIndexSize

public static int checkFromIndexSize(int fromIndex,
                                     int size,
                                     int length)

Checks if the sub-range from fromIndex (inclusive) to fromIndex + size (exclusive) is within the bounds of range from 0 (inclusive) to length (exclusive).

The sub-range is defined to be out-of-bounds if any of the following inequalities is true:

• fromIndex < 0
• size < 0
• fromIndex + size > length, taking into account integer overflow
• length < 0, which is implied from the former inequalities

Parameters:

fromIndex - the lower-bound (inclusive) of the sub-interval

size - the size of the sub-range

length - the upper-bound (exclusive) of the range

Returns:

fromIndex if the sub-range is within bounds of the range

Throws:

IndexOutOfBoundsException - if the sub-range is out-of-bounds

Since:

9

checkIndex

public static long checkIndex(long index,
                              long length)

Checks if the index is within the bounds of the range from 0 (inclusive) to length (exclusive).

The index is defined to be out of bounds if any of the following inequalities is true:

• index < 0
• index >= length
• length < 0, which is implied from the former inequalities

Parameters:

index - the index

length - the upper-bound (exclusive) of the range

Returns:

index if it is within bounds of the range

Throws:

IndexOutOfBoundsException - if the index is out of bounds

Since:

16

checkFromToIndex

public static long checkFromToIndex(long fromIndex,
                                    long toIndex,
                                    long length)

Checks if the sub-range from fromIndex (inclusive) to toIndex (exclusive) is within the bounds of range from 0 (inclusive) to length (exclusive).

The sub-range is defined to be out of bounds if any of the following inequalities is true:

• fromIndex < 0
• fromIndex > toIndex
• toIndex > length
• length < 0, which is implied from the former inequalities

Parameters:

fromIndex - the lower-bound (inclusive) of the sub-range

toIndex - the upper-bound (exclusive) of the sub-range

length - the upper-bound (exclusive) the range

Returns:

fromIndex if the sub-range within bounds of the range

Throws:

IndexOutOfBoundsException - if the sub-range is out of bounds

Since:

16

checkFromIndexSize

public static long checkFromIndexSize(long fromIndex,
                                      long size,
                                      long length)

Checks if the sub-range from fromIndex (inclusive) to fromIndex + size (exclusive) is within the bounds of range from 0 (inclusive) to length (exclusive).

The sub-range is defined to be out of bounds if any of the following inequalities is true:

• fromIndex < 0
• size < 0
• fromIndex + size > length, taking into account integer overflow
• length < 0, which is implied from the former inequalities

Parameters:

fromIndex - the lower-bound (inclusive) of the sub-interval

size - the size of the sub-range

length - the upper-bound (exclusive) of the range

Returns:

fromIndex if the sub-range within bounds of the range

Throws:

IndexOutOfBoundsException - if the sub-range is out of bounds

Since:

16