模块 java.base

软件包 java.util

Class Objects

java.lang.Object

java.util.Objects

public final class Objects
extends Object

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

API Note:

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

从以下版本开始：

1.7

方法摘要

变量和类型	方法	描述
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)	返回调用的结果 toString对于非 null参数， "null"为 null的说法。
static String	toString(Object o, String nullDefault)	如果第一个参数不是 null ，则返回在第一个参数上调用 toString的结果，否则返回第二个参数。

声明方法的类 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 ，则返回的字符串

结果

如果它不是 null ，则在第一个参数上调用 toString ，否则调用第二个参数。

另请参见：

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 ，具体取决于订购策略（如果有）， 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