# Objects

public final class **Objects** extends [Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html)  
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 for computing the
hash code of an object, returning a string for an object, comparing two
objects, and checking if indexes or sub-range values are out-of-bounds.

### Public Method Summary

|---|---|
| static \<T\> int | [compare](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Objects.html#compare(T,%20T,%20java.util.Comparator<?%20super%20T>))(T a, T b, [Comparator](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Comparator.html)\<? super T\> c) Returns 0 if the arguments are identical and `c.compare(a, b)` otherwise. |
| static boolean | [deepEquals](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Objects.html#deepEquals(java.lang.Object,%20java.lang.Object))([Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html) a, [Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html) b) Returns `true` if the arguments are deeply equal to each other and `false` otherwise. |
| static boolean | [equals](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Objects.html#equals(java.lang.Object,%20java.lang.Object))([Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html) a, [Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html) b) Returns `true` if the arguments are equal to each other and `false` otherwise. |
| static int | [hash](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Objects.html#hash(java.lang.Object...))([Object...](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html) values) Generates a hash code for a sequence of input values. |
| static int | [hashCode](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Objects.html#hashCode(java.lang.Object))([Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html) o) Returns the hash code of a non-`null` argument and 0 for a `null` argument. |
| static boolean | [isNull](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Objects.html#isNull(java.lang.Object))([Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html) obj) Returns `true` if the provided reference is `null` otherwise returns `false`. |
| static boolean | [nonNull](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Objects.html#nonNull(java.lang.Object))([Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html) obj) Returns `true` if the provided reference is non-`null` otherwise returns `false`. |
| static \<T\> T | [requireNonNull](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Objects.html#requireNonNull(T,%20java.lang.String))(T obj, [String](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html) message) Checks that the specified object reference is not `null` and throws a customized `https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/NullPointerException.html` if it is. |
| static \<T\> T | [requireNonNull](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Objects.html#requireNonNull(T,%20java.util.function.Supplier<java.lang.String>))(T obj, [Supplier](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/function/Supplier.html)\<[String](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html)\> messageSupplier) Checks that the specified object reference is not `null` and throws a customized `https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/NullPointerException.html` if it is. |
| static \<T\> T | [requireNonNull](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Objects.html#requireNonNull(T))(T obj) Checks that the specified object reference is not `null`. |
| static \<T\> T | [requireNonNullElse](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Objects.html#requireNonNullElse(T,%20T))(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](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Objects.html#requireNonNullElseGet(T,%20java.util.function.Supplier<?%20extends%20T>))(T obj, [Supplier](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/function/Supplier.html)\<? extends T\> supplier) Returns the first argument if it is non-`null` and otherwise returns the non-`null` value of `supplier.get()`. |
| static [String](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html) | [toString](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Objects.html#toString(java.lang.Object))([Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html) o) Returns the result of calling `toString` for a non-`null` argument and `"null"` for a `null` argument. |
| static [String](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html) | [toString](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Objects.html#toString(java.lang.Object,%20java.lang.String))([Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html) o, [String](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html) nullDefault) Returns the result of calling `toString` on the first argument if the first argument is not `null` and returns the second argument otherwise. |

### Inherited Method Summary

From class [java.lang.Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html)

|---|---|
| [Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html) | [clone](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#clone())() Creates and returns a copy of this `Object`. |
| boolean | [equals](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#equals(java.lang.Object))([Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html) obj) Compares this instance with the specified object and indicates if they are equal. |
| void | [finalize](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#finalize())() Invoked when the garbage collector has detected that this instance is no longer reachable. |
| final [Class](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Class.html)\<?\> | [getClass](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#getClass())() Returns the unique instance of `https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Class.html` that represents this object's class. |
| int | [hashCode](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#hashCode())() Returns an integer hash code for this object. |
| final void | [notify](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#notify())() Causes a thread which is waiting on this object's monitor (by means of calling one of the `wait()` methods) to be woken up. |
| final void | [notifyAll](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#notifyAll())() Causes all threads which are waiting on this object's monitor (by means of calling one of the `wait()` methods) to be woken up. |
| [String](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html) | [toString](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#toString())() Returns a string containing a concise, human-readable description of this object. |
| final void | [wait](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#wait(long,%20int))(long timeout, int nanos) Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object or until the specified timeout expires. |
| final void | [wait](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#wait(long))(long timeout) Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object or until the specified timeout expires. |
| final void | [wait](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#wait())() Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object. |

## Public Methods

#### public static int
**compare**
(T a, T b, [Comparator](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Comparator.html)\<? super T\> c)

Returns 0 if the arguments are identical and `c.compare(a, b)` otherwise.
Consequently, if both arguments are `null` 0
is returned.

Note that if one of the arguments is `null`, a `NullPointerException` may or may not be thrown depending on
what ordering policy, if any, the `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Comparator.html`
chooses to have for `null` values.

##### Parameters

| a | an object |
| b | an object to be compared with `a` |
| c | the `Comparator` to compare the first two arguments |
|---|---|

##### Returns

- 0 if the arguments are identical and `c.compare(a, b)` otherwise.

##### See Also

- `https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Comparable.html`
- `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Comparator.html`

#### public static boolean
**deepEquals**
([Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html) a, [Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html) b)

Returns `true` if the arguments are deeply equal to each other
and `false` otherwise.

Two `null` values are deeply equal. If both arguments are
arrays, the algorithm in `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Arrays.html#deepEquals(java.lang.Object[],%20java.lang.Object[])` is used to determine equality.
Otherwise, equality is determined by using the `https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#equals(java.lang.Object)` method of the first argument.

##### Parameters

| a | an object |
| b | an object to be compared with `a` for deep equality |
|---|---|

##### Returns

- `true` if the arguments are deeply equal to each other and `false` otherwise

##### See Also

- `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Arrays.html#deepEquals(java.lang.Object[],%20java.lang.Object[])`
- `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Objects.html#equals(java.lang.Object,%20java.lang.Object)`

#### public static boolean
**equals**
([Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html) a, [Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html) b)

Returns `true` if the arguments are equal to each other
and `false` otherwise.
Consequently, if both arguments are `null`, `true`
is returned and if exactly one argument is `null`, `false` is returned. Otherwise, equality is determined by using
the `https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#equals(java.lang.Object)` method of the first
argument.

##### Parameters

| a | an object |
| b | an object to be compared with `a` for equality |
|---|---|

##### Returns

- `true` if the arguments are equal to each other and `false` otherwise

##### See Also

- `https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#equals(java.lang.Object)`

#### public static int
**hash**
([Object...](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html) values)

Generates a hash code for a sequence of input values. The hash
code is generated as if all the input values were placed into an
array, and that array were hashed by calling `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Arrays.html#hashCode(java.lang.Object[])`.

This method is useful for implementing `https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#hashCode()` on objects containing multiple fields. For
example, if an object that has three fields, `x`, `y`, and `z`, one could write:

> ```
>  @Override public int hashCode() {
>      return Objects.hash(x, y, z);
>  }
>  
> ```
**Warning: When a single object reference is supplied, the returned
value does not equal the hash code of that object reference.** This value can be computed by calling `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Objects.html#hashCode(java.lang.Object)`.

<br />

##### Parameters

| values | the values to be hashed |
|---|---|

##### Returns

- a hash value of the sequence of input values

##### See Also

- `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Arrays.html#hashCode(java.lang.Object[])`
- `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/List.html#hashCode()`

#### public static int
**hashCode**
([Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html) o)

Returns the hash code of a non-`null` argument and 0 for
a `null` argument.

##### Parameters

| o | an object |
|---|---|

##### Returns

- the hash code of a non-`null` argument and 0 for a `null` argument

##### See Also

- `https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#hashCode()`

#### public static boolean
**isNull**
([Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html) obj)

Returns `true` if the provided reference is `null` otherwise
returns `false`.

##### Parameters

| obj | a reference to be checked against `null` |
|---|---|

##### Returns

- `true` if the provided reference is `null` otherwise `false`

##### See Also

- `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/function/Predicate.html`

#### public static boolean
**nonNull**
([Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html) obj)

Returns `true` if the provided reference is non-`null`
otherwise returns `false`.

##### Parameters

| obj | a reference to be checked against `null` |
|---|---|

##### Returns

- `true` if the provided reference is non-`null` otherwise `false`

##### See Also

- `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/function/Predicate.html`

#### public static T
**requireNonNull**
(T obj, [String](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html) message)

Checks that the specified object reference is not `null` and
throws a customized `https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/NullPointerException.html` if it is. This method
is designed primarily for doing parameter validation in methods and
constructors with multiple parameters, as demonstrated below:
>
> ```
>  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");
>  }
>  
> ```

<br />

##### Parameters

| obj | the object reference to check for nullity |
| message | detail message to be used in the event that a `NullPointerException` is thrown |
|---|---|

##### Returns

- `obj` if not `null`

##### Throws

| [NullPointerException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/NullPointerException.html) | if `obj` is `null` |
|---|---|

#### public static T
**requireNonNull**
(T obj, [Supplier](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/function/Supplier.html)\<[String](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html)\> messageSupplier)

Checks that the specified object reference is not `null` and
throws a customized `https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/NullPointerException.html` if it is.

Unlike the method `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Objects.html#requireNonNull(T,%20java.lang.String)`,
this method allows creation of the message to be deferred until
after the null check is made. While this may confer a
performance advantage in the non-null case, when deciding to
call this method care should be taken that the costs of
creating the message supplier are less than the cost of just
creating the string message directly.

##### Parameters

| obj | the object reference to check for nullity |
| messageSupplier | supplier of the detail message to be used in the event that a `NullPointerException` is thrown |
|---|---|

##### Returns

- `obj` if not `null`

##### Throws

| [NullPointerException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/NullPointerException.html) | if `obj` is `null` |
|---|---|

#### public static T
**requireNonNull**
(T obj)

Checks that the specified object reference is not `null`. This
method is designed primarily for doing parameter validation in methods
and constructors, as demonstrated below:
>
> ```
>  public Foo(Bar bar) {
>      this.bar = Objects.requireNonNull(bar);
>  }
>  
> ```

<br />

##### Parameters

| obj | the object reference to check for nullity |
|---|---|

##### Returns

- `obj` if not `null`

##### Throws

| [NullPointerException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/NullPointerException.html) | if `obj` is `null` |
|---|---|

#### public static T
**requireNonNullElse**
(T obj, T defaultObj)

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

##### 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](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/NullPointerException.html) | if both `obj` is null and `defaultObj` is `null` |
|---|---|

#### public static T
**requireNonNullElseGet**
(T obj, [Supplier](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/function/Supplier.html)\<? extends T\> supplier)

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

##### 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](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/NullPointerException.html) | if both `obj` is null and either the `supplier` is `null` or the `supplier.get()` value is `null` |
|---|---|

#### public static [String](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html)
**toString**
([Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html) o)

Returns the result of calling `toString` for a non-`null` argument and `"null"` for a `null` argument.

##### Parameters

| o | an object |
|---|---|

##### Returns

- the result of calling `toString` for a non-`null` argument and `"null"` for a `null` argument

##### See Also

- `https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#toString()`
- `https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html#valueOf(java.lang.Object)`

#### public static [String](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html)
**toString**
([Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html) o, [String](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html) nullDefault)

Returns the result of calling `toString` on the first
argument if the first argument is not `null` and returns
the second argument otherwise.

##### Parameters

| o | an object |
| nullDefault | string to return if the first argument is `null` |
|---|---|

##### Returns

- the result of calling `toString` on the first argument if it is not `null` and the second argument otherwise.

##### See Also

- `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Objects.html#toString(java.lang.Object)`