Module java.base

软件包 java.util

Class Objects

java.lang.Object

java.util.Objects

public final class Objects
extends Object

此类由static用于在对象上操作的实用方法或在操作之前检查某些条件。 这些实用程序包括用于计算对象的哈希码，返回对象的字符串，比较两个对象以及检查索引或子范围值是否超出范围的null或null - null方法。

API Note:

静态方法如checkIndex(int, int) ， checkFromToIndex(int, int, int) ，和checkFromIndexSize(int, int, int)提供了用于检查的方便，如果对应于索引和子范围值外的边界。 这些静态方法的变化支持定制运行时异常以及相应的异常详细消息，当值超出范围时抛出异常。 这种方法接受函数接口参数（ BiFunction实例），将外联值映射到运行时异常。 当使用这样的方法结合使用lambda表达式，方法引用或捕获值的类的参数时，应该小心。 在这种情况下，与功能接口分配相关的捕获成本可能会超过检查边界的成本。

从以下版本开始：

1.7

方法摘要

Modifier and Type	方法	描述
static int	checkFromIndexSize(int fromIndex, int size, int length)	检查是否在子范围从 fromIndex （含）至 fromIndex + size （不包括）是范围界限内 0 （包括）到 length （不包括）。
static int	checkFromToIndex(int fromIndex, int toIndex, int length)	检查是否在子范围从 fromIndex （含）至 toIndex （不包括）是范围界限内 0 （包括）到 length （不包括）。
static int	checkIndex(int index, int length)	检查 index是否在范围从 0 （含）到 length （排他）的范围内。
static <T> int	compare(T a, T b, Comparator<? super T> c)	如果参数相同，则返回0，否则返回 c.compare(a, b) 。
static boolean	deepEquals(Object a, Object b)	返回 true如果参数是深层相等，彼此 false否则。
static boolean	equals(Object a, Object b)	返回 true如果参数相等，彼此 false否则。
static int	hash(Object... values)	为输入值序列生成哈希码。
static int	hashCode(Object o)	返回非的哈希码 null参数，0为 null参数。
static boolean	isNull(Object obj)	返回 true如果提供的引用是 null否则返回 false 。
static boolean	nonNull(Object obj)	返回 true如果提供的参考是非 null否则返回 false 。
static <T> T	requireNonNull(T obj)	检查指定的对象引用不是 null 。
static <T> T	requireNonNull(T obj, String message)	检查指定的对象引用不是null并抛出自定义的NullPointerException（如果是）。
static <T> T	requireNonNull(T obj, Supplier<String> messageSupplier)	检查指定的对象引用不是null并抛出自定义的NullPointerException（如果是）。
static <T> T	requireNonNullElse(T obj, T defaultObj)	如果非 null返回第一个参数，否则返回非 null第二个参数。
static <T> T	requireNonNullElseGet(T obj, Supplier<? extends T> supplier)	如果它不是 null ，则返回第一个参数，否则返回非 null值为 supplier.get() 。
static String	toString(Object o)	返回非 null参数调用 toString的结果和 null参数的 "null"的 null 。
static String	toString(Object o, String nullDefault)	如果第一个参数不是 null ，则返回第一个参数上调用 toString的结果，否则返回第二个参数。

Methods inherited from class java.lang.Object

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

方法详细信息

equals

public static boolean equals(Object a,
                             Object b)

返回true如果参数相等，彼此false否则。 因此，如果这两个参数是null ， true返回，如果只有一个参数为null ， false返回。 否则，通过使用第一个参数的equals方法来确定相等性。

参数

a - 一个对象

b - 要与 a进行比较的对象

结果

true如果参数彼此相等，否则为 false

另请参见：

Object.equals(Object)

deepEquals

public static boolean deepEquals(Object a,
                                 Object b)

返回true如果参数是深层相等，彼此false否则。 两个null值相当。 如果两个参数都是数组，则使用Arrays.deepEquals中的算法来确定相等。 否则，使用第一个参数的equals方法确定相等性。

参数

a - 一个对象

b - 要与深度相等的 a进行比较的对象

结果

true如果参数彼此深深相等，否则为 false

另请参见：

Arrays.deepEquals(Object[], Object[]) ， equals(Object, Object)

hashCode

public static int hashCode(Object o)

返回非的哈希码 null参数，0为 null参数。

参数

o - 一个对象

结果

非的哈希码 null参数，0为 null参数

另请参见：

Object.hashCode()

hash

public static int hash(Object... values)

为输入值序列生成哈希码。 生成哈希码，就好像将所有输入值都放入数组一样，并且该数组通过调用Arrays.hashCode(Object[])进行哈希处理 。

该方法对于包含多个字段的对象实现Object.hashCode()很有用。 例如，如果有三个字段，对象x ， y ，以及z ，一个可以这样写：

 @Override public int hashCode() {
     return Objects.hash(x, y, z);
 }
 

警告：当提供单个对象引用时，返回的值不等于该对象引用的哈希码。 该值可以通过调用hashCode(Object)来计算。

参数

values - 要散列的值

结果

输入值序列的哈希值

另请参见：

Arrays.hashCode(Object[]) ， List.hashCode()

toString

public static String toString(Object o)

返回调用的结果 toString的非 null参数， "null"为 null的说法。

参数

o - 一个对象

结果

调用 toString非 null参数和 "null"为 null参数的结果

另请参见：

Object.toString() ， String.valueOf(Object)

toString

public static String toString(Object o,
                              String nullDefault)

如果第一个参数不是 null ，则返回第一个参数中调用 toString的结果，否则返回第二个参数。

参数

o - 一个对象

nullDefault - 如果第一个参数是 null ，则返回的字符串

结果

调用 toString对第一个参数的结果，如果不是 null ，否则为第二个参数。

另请参见：

toString(Object)

compare

public static <T> int compare(T a,
                              T b,
                              Comparator<? super T> c)

如果参数相同，则返回0，否则返回c.compare(a, b) 。 因此，如果两个参数都为null则返回0。

请注意，如果其中一个参数为null ， NullPointerException可能会抛出null ，或者可能不会抛出null ，具体取决于Comparator选择具有null值的订购策略（如果有）。

参数类型

T - 正在比较的对象的类型

参数

a - 一个对象

b - 要与 a进行比较的对象

c - Comparator比较前两个参数

结果

如果参数相同， c.compare(a, b) 0，否则为 c.compare(a, b) 。

另请参见：

Comparable ， Comparator

requireNonNull

public static <T> T requireNonNull(T obj)

检查指定的对象引用不是null 。 该方法主要用于在方法和构造函数中进行参数验证，如下所示：

 public Foo(Bar bar) {
     this.bar = Objects.requireNonNull(bar);
 }
 

参数类型

T - 参考的类型

参数

obj - 检查无效的对象引用

结果

obj如果不是 null

异常

NullPointerException - 如果 obj是 null

requireNonNull

public static <T> T requireNonNull(T obj,
                                   String message)

检查指定的对象引用不是null并抛出自定义的NullPointerException（如果是）。 该方法主要用于在具有多个参数的方法和构造函数中进行参数验证，如下所示：

 public Foo(Bar bar, Baz baz) {
     this.bar = Objects.requireNonNull(bar, "bar must not be null");
     this.baz = Objects.requireNonNull(baz, "baz must not be null");
 }
 

参数类型

T - 参考的类型

参数

obj - 检查无效的对象引用

message - 在抛出 NullPointerException的情况下使用的详细消息

结果

obj如果不是 null

异常

NullPointerException - 如果 obj是 null

isNull

public static boolean isNull(Object obj)

返回 true如果提供的参考是 null ，否则返回 false 。

API Note:

这种方法存在着用作Predicate ， filter(Objects::isNull)

参数

obj - 对 null进行检查的参考

结果

true如果提供的参考是 null否则 false

从以下版本开始：

1.8

另请参见：

Predicate

nonNull

public static boolean nonNull(Object obj)

返回 true如果提供的引用是非 null否则返回 false 。

API Note:

这种方法存在着用作Predicate ， filter(Objects::nonNull)

参数

obj - 要针对 null进行检查的引用

结果

true如果提供的参考是非 null否则 false

从以下版本开始：

1.8

另请参见：

Predicate

requireNonNullElse

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

如果非 null返回第一个参数，否则返回非 null第二个参数。

参数类型

T - 参考的类型

参数

obj - 一个对象

defaultObj - 如果第一个参数是 null ，则返回一个非 null对象

结果

第一个参数，如果它是非 null否则第二个参数，如果它是非 null

异常

NullPointerException - 如果 obj为空，而 defaultObj为 null

从以下版本开始：

9

requireNonNullElseGet

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

如果非 null ，则返回第一个参数，否则返回非 null值为 supplier.get() 。

参数类型

T - 第一个参数和返回类型的类型

参数

obj - 一个对象

supplier - 如果第一个参数是 null ，则返回一个非 null对象

结果

第一个参数如果是非 null ，否则从 supplier.get()的值是非 null

异常

NullPointerException - 如果 obj为空，而 supplier为 null或 supplier.get()为 null

从以下版本开始：

9

requireNonNull

public static <T> T requireNonNull(T obj,
                                   Supplier<String> messageSupplier)

检查指定的对象引用不是null并抛出自定义的NullPointerException（如果是）。

与方法requireNonNull(Object, String)不同，该方法允许创建要延迟的消息，直到进行空检查为止。 虽然这可能在非空情况下赋予性能优势，但在决定调用此方法时，应注意创建消息提供者的成本低于直接创建字符串消息的成本。

参数类型

T - 参考的类型

参数

obj - 检查无效的对象引用

messageSupplier - 在抛出 NullPointerException情况下使用的详细消息的供应商

结果

obj如果不是 null

异常

NullPointerException - 如果 obj是 null

从以下版本开始：

1.8

checkIndex

public static int checkIndex(int index,
                             int length)

检查index是否在范围从0 （含）到length （独占）范围内。

如果以下任何不等式为真，则index被定义为超出界限：

• index < 0
• index >= length
• length < 0 ，这是前不平等所暗示的

参数

index - 索引

length - 范围的上限（排他）

结果

index如果它在范围的范围内

异常

IndexOutOfBoundsException - 如果 index是超出范围

从以下版本开始：

9

checkFromToIndex

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

检查是否在子范围从fromIndex （含）至toIndex （不包括）是范围界限内0 （包括）到length （不包括）。

如果以下任何不等式为真，则子范围被定义为超出范围：

• fromIndex < 0
• fromIndex > toIndex
• toIndex > length
• length < 0 ，这是前不平等所暗示的

参数

fromIndex - 子范围的下限（含）

toIndex - 子范围的上限（排他）

length - 上限（排除）范围

结果

fromIndex如果子范围内的范围内

异常

IndexOutOfBoundsException - 如果子范围超出范围

从以下版本开始：

9

checkFromIndexSize

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

检查是否在子范围从fromIndex （含）至fromIndex + size （不包括）是范围界限内0 （包括）到length （不包括）。

如果以下任何不等式为真，则子范围被定义为超出范围：

• fromIndex < 0
• size < 0
• fromIndex + size > length ，考虑到整数溢出
• length < 0 ，这是前不平等所暗示的

参数

fromIndex - 子间隔的下限（含）

size - 子范围的大小

length - 范围的上限（排除）

结果

fromIndex如果子范围内的范围内

异常

IndexOutOfBoundsException - 如果子范围超出范围

从以下版本开始：

9