jdk/src/java.base/share/classes/java/util/Objects.java
author mchung
Fri, 22 May 2015 16:43:39 -0700
changeset 30789 9eca83469588
parent 25859 3317bb8137f4
child 32929 7e1bb9268b8a
permissions -rw-r--r--
8074431: Remove native2ascii tool Reviewed-by: erikj, alanb, okutsu, mfang, naoto
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
4038
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
     1
/*
17465
6ea0e148a562 8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents: 17431
diff changeset
     2
 * Copyright (c) 2009, 2013, Oracle and/or its affiliates. All rights reserved.
4038
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
     3
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
     4
 *
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
     5
 * This code is free software; you can redistribute it and/or modify it
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
     6
 * under the terms of the GNU General Public License version 2 only, as
5506
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 4504
diff changeset
     7
 * published by the Free Software Foundation.  Oracle designates this
4038
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
     8
 * particular file as subject to the "Classpath" exception as provided
5506
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 4504
diff changeset
     9
 * by Oracle in the LICENSE file that accompanied this code.
4038
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    10
 *
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    11
 * This code is distributed in the hope that it will be useful, but WITHOUT
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    12
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    13
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    14
 * version 2 for more details (a copy is included in the LICENSE file that
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    15
 * accompanied this code).
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    16
 *
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    17
 * You should have received a copy of the GNU General Public License version
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    18
 * 2 along with this work; if not, write to the Free Software Foundation,
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    19
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    20
 *
5506
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 4504
diff changeset
    21
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 4504
diff changeset
    22
 * or visit www.oracle.com if you need additional information or have any
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 4504
diff changeset
    23
 * questions.
4038
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    24
 */
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    25
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    26
package java.util;
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    27
17465
6ea0e148a562 8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents: 17431
diff changeset
    28
import java.util.function.Supplier;
6ea0e148a562 8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents: 17431
diff changeset
    29
4038
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    30
/**
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    31
 * This class consists of {@code static} utility methods for operating
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    32
 * on objects.  These utilities include {@code null}-safe or {@code
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    33
 * null}-tolerant methods for computing the hash code of an object,
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    34
 * returning a string for an object, and comparing two objects.
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    35
 *
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    36
 * @since 1.7
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    37
 */
4165
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
    38
public final class Objects {
4038
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    39
    private Objects() {
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    40
        throw new AssertionError("No java.util.Objects instances for you!");
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    41
    }
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    42
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    43
    /**
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    44
     * Returns {@code true} if the arguments are equal to each other
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    45
     * and {@code false} otherwise.
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    46
     * Consequently, if both arguments are {@code null}, {@code true}
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    47
     * is returned and if exactly one argument is {@code null}, {@code
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    48
     * false} is returned.  Otherwise, equality is determined by using
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    49
     * the {@link Object#equals equals} method of the first
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    50
     * argument.
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    51
     *
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    52
     * @param a an object
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    53
     * @param b an object to be compared with {@code a} for equality
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    54
     * @return {@code true} if the arguments are equal to each other
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    55
     * and {@code false} otherwise
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    56
     * @see Object#equals(Object)
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    57
     */
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    58
    public static boolean equals(Object a, Object b) {
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    59
        return (a == b) || (a != null && a.equals(b));
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    60
    }
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    61
4165
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
    62
   /**
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
    63
    * Returns {@code true} if the arguments are deeply equal to each other
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
    64
    * and {@code false} otherwise.
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
    65
    *
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
    66
    * Two {@code null} values are deeply equal.  If both arguments are
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
    67
    * arrays, the algorithm in {@link Arrays#deepEquals(Object[],
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
    68
    * Object[]) Arrays.deepEquals} is used to determine equality.
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
    69
    * Otherwise, equality is determined by using the {@link
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
    70
    * Object#equals equals} method of the first argument.
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
    71
    *
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
    72
    * @param a an object
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
    73
    * @param b an object to be compared with {@code a} for deep equality
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
    74
    * @return {@code true} if the arguments are deeply equal to each other
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
    75
    * and {@code false} otherwise
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
    76
    * @see Arrays#deepEquals(Object[], Object[])
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
    77
    * @see Objects#equals(Object, Object)
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
    78
    */
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
    79
    public static boolean deepEquals(Object a, Object b) {
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
    80
        if (a == b)
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
    81
            return true;
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
    82
        else if (a == null || b == null)
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
    83
            return false;
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
    84
        else
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
    85
            return Arrays.deepEquals0(a, b);
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
    86
    }
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
    87
4038
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    88
    /**
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    89
     * Returns the hash code of a non-{@code null} argument and 0 for
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    90
     * a {@code null} argument.
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    91
     *
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    92
     * @param o an object
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    93
     * @return the hash code of a non-{@code null} argument and 0 for
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    94
     * a {@code null} argument
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    95
     * @see Object#hashCode
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    96
     */
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    97
    public static int hashCode(Object o) {
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    98
        return o != null ? o.hashCode() : 0;
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
    99
    }
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
   100
4165
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
   101
   /**
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
   102
    * Generates a hash code for a sequence of input values. The hash
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
   103
    * code is generated as if all the input values were placed into an
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
   104
    * array, and that array were hashed by calling {@link
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
   105
    * Arrays#hashCode(Object[])}.
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
   106
    *
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
   107
    * <p>This method is useful for implementing {@link
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
   108
    * Object#hashCode()} on objects containing multiple fields. For
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
   109
    * example, if an object that has three fields, {@code x}, {@code
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
   110
    * y}, and {@code z}, one could write:
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
   111
    *
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
   112
    * <blockquote><pre>
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
   113
    * &#064;Override public int hashCode() {
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
   114
    *     return Objects.hash(x, y, z);
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
   115
    * }
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
   116
    * </pre></blockquote>
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
   117
    *
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
   118
    * <b>Warning: When a single object reference is supplied, the returned
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
   119
    * value does not equal the hash code of that object reference.</b> This
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
   120
    * value can be computed by calling {@link #hashCode(Object)}.
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
   121
    *
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
   122
    * @param values the values to be hashed
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
   123
    * @return a hash value of the sequence of input values
4504
0a031ee3f7a4 6909057: @see Arrays#hashCode missing particular method specification in j.u.Objects.hash
darcy
parents: 4165
diff changeset
   124
    * @see Arrays#hashCode(Object[])
4165
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
   125
    * @see List#hashCode
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
   126
    */
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
   127
    public static int hash(Object... values) {
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
   128
        return Arrays.hashCode(values);
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
   129
    }
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
   130
4038
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
   131
    /**
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
   132
     * Returns the result of calling {@code toString} for a non-{@code
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
   133
     * null} argument and {@code "null"} for a {@code null} argument.
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
   134
     *
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
   135
     * @param o an object
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
   136
     * @return the result of calling {@code toString} for a non-{@code
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
   137
     * null} argument and {@code "null"} for a {@code null} argument
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
   138
     * @see Object#toString
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
   139
     * @see String#valueOf(Object)
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
   140
     */
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
   141
    public static String toString(Object o) {
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
   142
        return String.valueOf(o);
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
   143
    }
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
   144
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
   145
    /**
4165
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
   146
     * Returns the result of calling {@code toString} on the first
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
   147
     * argument if the first argument is not {@code null} and returns
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
   148
     * the second argument otherwise.
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
   149
     *
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
   150
     * @param o an object
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
   151
     * @param nullDefault string to return if the first argument is
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
   152
     *        {@code null}
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
   153
     * @return the result of calling {@code toString} on the first
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
   154
     * argument if it is not {@code null} and the second argument
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
   155
     * otherwise.
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
   156
     * @see Objects#toString(Object)
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
   157
     */
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
   158
    public static String toString(Object o, String nullDefault) {
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
   159
        return (o != null) ? o.toString() : nullDefault;
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
   160
    }
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
   161
7cd799c224da 6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents: 4061
diff changeset
   162
    /**
4038
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
   163
     * Returns 0 if the arguments are identical and {@code
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
   164
     * c.compare(a, b)} otherwise.
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
   165
     * Consequently, if both arguments are {@code null} 0
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
   166
     * is returned.
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
   167
     *
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
   168
     * <p>Note that if one of the arguments is {@code null}, a {@code
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
   169
     * NullPointerException} may or may not be thrown depending on
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
   170
     * what ordering policy, if any, the {@link Comparator Comparator}
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
   171
     * chooses to have for {@code null} values.
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
   172
     *
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
   173
     * @param <T> the type of the objects being compared
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
   174
     * @param a an object
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
   175
     * @param b an object to be compared with {@code a}
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
   176
     * @param c the {@code Comparator} to compare the first two arguments
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
   177
     * @return 0 if the arguments are identical and {@code
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
   178
     * c.compare(a, b)} otherwise.
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
   179
     * @see Comparable
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
   180
     * @see Comparator
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
   181
     */
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
   182
    public static <T> int compare(T a, T b, Comparator<? super T> c) {
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
   183
        return (a == b) ? 0 :  c.compare(a, b);
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
   184
    }
4061
35a627ad2443 6889858: Add nonNull methods to java.util.Objects
darcy
parents: 4038
diff changeset
   185
35a627ad2443 6889858: Add nonNull methods to java.util.Objects
darcy
parents: 4038
diff changeset
   186
    /**
35a627ad2443 6889858: Add nonNull methods to java.util.Objects
darcy
parents: 4038
diff changeset
   187
     * Checks that the specified object reference is not {@code null}. This
35a627ad2443 6889858: Add nonNull methods to java.util.Objects
darcy
parents: 4038
diff changeset
   188
     * method is designed primarily for doing parameter validation in methods
35a627ad2443 6889858: Add nonNull methods to java.util.Objects
darcy
parents: 4038
diff changeset
   189
     * and constructors, as demonstrated below:
35a627ad2443 6889858: Add nonNull methods to java.util.Objects
darcy
parents: 4038
diff changeset
   190
     * <blockquote><pre>
35a627ad2443 6889858: Add nonNull methods to java.util.Objects
darcy
parents: 4038
diff changeset
   191
     * public Foo(Bar bar) {
8166
13423c0952ad 7012540: java.util.Objects.nonNull() incorrectly named
briangoetz
parents: 5506
diff changeset
   192
     *     this.bar = Objects.requireNonNull(bar);
4061
35a627ad2443 6889858: Add nonNull methods to java.util.Objects
darcy
parents: 4038
diff changeset
   193
     * }
35a627ad2443 6889858: Add nonNull methods to java.util.Objects
darcy
parents: 4038
diff changeset
   194
     * </pre></blockquote>
35a627ad2443 6889858: Add nonNull methods to java.util.Objects
darcy
parents: 4038
diff changeset
   195
     *
35a627ad2443 6889858: Add nonNull methods to java.util.Objects
darcy
parents: 4038
diff changeset
   196
     * @param obj the object reference to check for nullity
35a627ad2443 6889858: Add nonNull methods to java.util.Objects
darcy
parents: 4038
diff changeset
   197
     * @param <T> the type of the reference
35a627ad2443 6889858: Add nonNull methods to java.util.Objects
darcy
parents: 4038
diff changeset
   198
     * @return {@code obj} if not {@code null}
35a627ad2443 6889858: Add nonNull methods to java.util.Objects
darcy
parents: 4038
diff changeset
   199
     * @throws NullPointerException if {@code obj} is {@code null}
35a627ad2443 6889858: Add nonNull methods to java.util.Objects
darcy
parents: 4038
diff changeset
   200
     */
8166
13423c0952ad 7012540: java.util.Objects.nonNull() incorrectly named
briangoetz
parents: 5506
diff changeset
   201
    public static <T> T requireNonNull(T obj) {
4061
35a627ad2443 6889858: Add nonNull methods to java.util.Objects
darcy
parents: 4038
diff changeset
   202
        if (obj == null)
35a627ad2443 6889858: Add nonNull methods to java.util.Objects
darcy
parents: 4038
diff changeset
   203
            throw new NullPointerException();
35a627ad2443 6889858: Add nonNull methods to java.util.Objects
darcy
parents: 4038
diff changeset
   204
        return obj;
35a627ad2443 6889858: Add nonNull methods to java.util.Objects
darcy
parents: 4038
diff changeset
   205
    }
35a627ad2443 6889858: Add nonNull methods to java.util.Objects
darcy
parents: 4038
diff changeset
   206
35a627ad2443 6889858: Add nonNull methods to java.util.Objects
darcy
parents: 4038
diff changeset
   207
    /**
35a627ad2443 6889858: Add nonNull methods to java.util.Objects
darcy
parents: 4038
diff changeset
   208
     * Checks that the specified object reference is not {@code null} and
35a627ad2443 6889858: Add nonNull methods to java.util.Objects
darcy
parents: 4038
diff changeset
   209
     * throws a customized {@link NullPointerException} if it is. This method
35a627ad2443 6889858: Add nonNull methods to java.util.Objects
darcy
parents: 4038
diff changeset
   210
     * is designed primarily for doing parameter validation in methods and
35a627ad2443 6889858: Add nonNull methods to java.util.Objects
darcy
parents: 4038
diff changeset
   211
     * constructors with multiple parameters, as demonstrated below:
35a627ad2443 6889858: Add nonNull methods to java.util.Objects
darcy
parents: 4038
diff changeset
   212
     * <blockquote><pre>
35a627ad2443 6889858: Add nonNull methods to java.util.Objects
darcy
parents: 4038
diff changeset
   213
     * public Foo(Bar bar, Baz baz) {
8166
13423c0952ad 7012540: java.util.Objects.nonNull() incorrectly named
briangoetz
parents: 5506
diff changeset
   214
     *     this.bar = Objects.requireNonNull(bar, "bar must not be null");
13423c0952ad 7012540: java.util.Objects.nonNull() incorrectly named
briangoetz
parents: 5506
diff changeset
   215
     *     this.baz = Objects.requireNonNull(baz, "baz must not be null");
4061
35a627ad2443 6889858: Add nonNull methods to java.util.Objects
darcy
parents: 4038
diff changeset
   216
     * }
35a627ad2443 6889858: Add nonNull methods to java.util.Objects
darcy
parents: 4038
diff changeset
   217
     * </pre></blockquote>
35a627ad2443 6889858: Add nonNull methods to java.util.Objects
darcy
parents: 4038
diff changeset
   218
     *
35a627ad2443 6889858: Add nonNull methods to java.util.Objects
darcy
parents: 4038
diff changeset
   219
     * @param obj     the object reference to check for nullity
35a627ad2443 6889858: Add nonNull methods to java.util.Objects
darcy
parents: 4038
diff changeset
   220
     * @param message detail message to be used in the event that a {@code
35a627ad2443 6889858: Add nonNull methods to java.util.Objects
darcy
parents: 4038
diff changeset
   221
     *                NullPointerException} is thrown
35a627ad2443 6889858: Add nonNull methods to java.util.Objects
darcy
parents: 4038
diff changeset
   222
     * @param <T> the type of the reference
35a627ad2443 6889858: Add nonNull methods to java.util.Objects
darcy
parents: 4038
diff changeset
   223
     * @return {@code obj} if not {@code null}
35a627ad2443 6889858: Add nonNull methods to java.util.Objects
darcy
parents: 4038
diff changeset
   224
     * @throws NullPointerException if {@code obj} is {@code null}
35a627ad2443 6889858: Add nonNull methods to java.util.Objects
darcy
parents: 4038
diff changeset
   225
     */
8166
13423c0952ad 7012540: java.util.Objects.nonNull() incorrectly named
briangoetz
parents: 5506
diff changeset
   226
    public static <T> T requireNonNull(T obj, String message) {
4061
35a627ad2443 6889858: Add nonNull methods to java.util.Objects
darcy
parents: 4038
diff changeset
   227
        if (obj == null)
35a627ad2443 6889858: Add nonNull methods to java.util.Objects
darcy
parents: 4038
diff changeset
   228
            throw new NullPointerException(message);
35a627ad2443 6889858: Add nonNull methods to java.util.Objects
darcy
parents: 4038
diff changeset
   229
        return obj;
35a627ad2443 6889858: Add nonNull methods to java.util.Objects
darcy
parents: 4038
diff changeset
   230
    }
17431
335d87f0d817 8013712: Add Objects.nonNull and Objects.isNull
mduigou
parents: 16864
diff changeset
   231
335d87f0d817 8013712: Add Objects.nonNull and Objects.isNull
mduigou
parents: 16864
diff changeset
   232
    /**
335d87f0d817 8013712: Add Objects.nonNull and Objects.isNull
mduigou
parents: 16864
diff changeset
   233
     * Returns {@code true} if the provided reference is {@code null} otherwise
335d87f0d817 8013712: Add Objects.nonNull and Objects.isNull
mduigou
parents: 16864
diff changeset
   234
     * returns {@code false}.
335d87f0d817 8013712: Add Objects.nonNull and Objects.isNull
mduigou
parents: 16864
diff changeset
   235
     *
335d87f0d817 8013712: Add Objects.nonNull and Objects.isNull
mduigou
parents: 16864
diff changeset
   236
     * @apiNote This method exists to be used as a
335d87f0d817 8013712: Add Objects.nonNull and Objects.isNull
mduigou
parents: 16864
diff changeset
   237
     * {@link java.util.function.Predicate}, {@code filter(Objects::isNull)}
335d87f0d817 8013712: Add Objects.nonNull and Objects.isNull
mduigou
parents: 16864
diff changeset
   238
     *
335d87f0d817 8013712: Add Objects.nonNull and Objects.isNull
mduigou
parents: 16864
diff changeset
   239
     * @param obj a reference to be checked against {@code null}
335d87f0d817 8013712: Add Objects.nonNull and Objects.isNull
mduigou
parents: 16864
diff changeset
   240
     * @return {@code true} if the provided reference is {@code null} otherwise
335d87f0d817 8013712: Add Objects.nonNull and Objects.isNull
mduigou
parents: 16864
diff changeset
   241
     * {@code false}
335d87f0d817 8013712: Add Objects.nonNull and Objects.isNull
mduigou
parents: 16864
diff changeset
   242
     *
335d87f0d817 8013712: Add Objects.nonNull and Objects.isNull
mduigou
parents: 16864
diff changeset
   243
     * @see java.util.function.Predicate
335d87f0d817 8013712: Add Objects.nonNull and Objects.isNull
mduigou
parents: 16864
diff changeset
   244
     * @since 1.8
335d87f0d817 8013712: Add Objects.nonNull and Objects.isNull
mduigou
parents: 16864
diff changeset
   245
     */
335d87f0d817 8013712: Add Objects.nonNull and Objects.isNull
mduigou
parents: 16864
diff changeset
   246
    public static boolean isNull(Object obj) {
335d87f0d817 8013712: Add Objects.nonNull and Objects.isNull
mduigou
parents: 16864
diff changeset
   247
        return obj == null;
335d87f0d817 8013712: Add Objects.nonNull and Objects.isNull
mduigou
parents: 16864
diff changeset
   248
    }
335d87f0d817 8013712: Add Objects.nonNull and Objects.isNull
mduigou
parents: 16864
diff changeset
   249
335d87f0d817 8013712: Add Objects.nonNull and Objects.isNull
mduigou
parents: 16864
diff changeset
   250
    /**
335d87f0d817 8013712: Add Objects.nonNull and Objects.isNull
mduigou
parents: 16864
diff changeset
   251
     * Returns {@code true} if the provided reference is non-{@code null}
335d87f0d817 8013712: Add Objects.nonNull and Objects.isNull
mduigou
parents: 16864
diff changeset
   252
     * otherwise returns {@code false}.
335d87f0d817 8013712: Add Objects.nonNull and Objects.isNull
mduigou
parents: 16864
diff changeset
   253
     *
335d87f0d817 8013712: Add Objects.nonNull and Objects.isNull
mduigou
parents: 16864
diff changeset
   254
     * @apiNote This method exists to be used as a
335d87f0d817 8013712: Add Objects.nonNull and Objects.isNull
mduigou
parents: 16864
diff changeset
   255
     * {@link java.util.function.Predicate}, {@code filter(Objects::nonNull)}
335d87f0d817 8013712: Add Objects.nonNull and Objects.isNull
mduigou
parents: 16864
diff changeset
   256
     *
335d87f0d817 8013712: Add Objects.nonNull and Objects.isNull
mduigou
parents: 16864
diff changeset
   257
     * @param obj a reference to be checked against {@code null}
335d87f0d817 8013712: Add Objects.nonNull and Objects.isNull
mduigou
parents: 16864
diff changeset
   258
     * @return {@code true} if the provided reference is non-{@code null}
335d87f0d817 8013712: Add Objects.nonNull and Objects.isNull
mduigou
parents: 16864
diff changeset
   259
     * otherwise {@code false}
335d87f0d817 8013712: Add Objects.nonNull and Objects.isNull
mduigou
parents: 16864
diff changeset
   260
     *
335d87f0d817 8013712: Add Objects.nonNull and Objects.isNull
mduigou
parents: 16864
diff changeset
   261
     * @see java.util.function.Predicate
335d87f0d817 8013712: Add Objects.nonNull and Objects.isNull
mduigou
parents: 16864
diff changeset
   262
     * @since 1.8
335d87f0d817 8013712: Add Objects.nonNull and Objects.isNull
mduigou
parents: 16864
diff changeset
   263
     */
335d87f0d817 8013712: Add Objects.nonNull and Objects.isNull
mduigou
parents: 16864
diff changeset
   264
    public static boolean nonNull(Object obj) {
335d87f0d817 8013712: Add Objects.nonNull and Objects.isNull
mduigou
parents: 16864
diff changeset
   265
        return obj != null;
335d87f0d817 8013712: Add Objects.nonNull and Objects.isNull
mduigou
parents: 16864
diff changeset
   266
    }
17465
6ea0e148a562 8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents: 17431
diff changeset
   267
6ea0e148a562 8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents: 17431
diff changeset
   268
    /**
6ea0e148a562 8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents: 17431
diff changeset
   269
     * Checks that the specified object reference is not {@code null} and
6ea0e148a562 8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents: 17431
diff changeset
   270
     * throws a customized {@link NullPointerException} if it is.
6ea0e148a562 8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents: 17431
diff changeset
   271
     *
17475
24f8cffd7390 8014677: Correct docs warning for Objects.requireNonNull(T, Supplier<String>)
darcy
parents: 17465
diff changeset
   272
     * <p>Unlike the method {@link #requireNonNull(Object, String)},
17465
6ea0e148a562 8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents: 17431
diff changeset
   273
     * this method allows creation of the message to be deferred until
6ea0e148a562 8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents: 17431
diff changeset
   274
     * after the null check is made. While this may confer a
6ea0e148a562 8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents: 17431
diff changeset
   275
     * performance advantage in the non-null case, when deciding to
6ea0e148a562 8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents: 17431
diff changeset
   276
     * call this method care should be taken that the costs of
6ea0e148a562 8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents: 17431
diff changeset
   277
     * creating the message supplier are less than the cost of just
6ea0e148a562 8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents: 17431
diff changeset
   278
     * creating the string message directly.
6ea0e148a562 8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents: 17431
diff changeset
   279
     *
6ea0e148a562 8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents: 17431
diff changeset
   280
     * @param obj     the object reference to check for nullity
6ea0e148a562 8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents: 17431
diff changeset
   281
     * @param messageSupplier supplier of the detail message to be
6ea0e148a562 8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents: 17431
diff changeset
   282
     * used in the event that a {@code NullPointerException} is thrown
6ea0e148a562 8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents: 17431
diff changeset
   283
     * @param <T> the type of the reference
6ea0e148a562 8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents: 17431
diff changeset
   284
     * @return {@code obj} if not {@code null}
6ea0e148a562 8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents: 17431
diff changeset
   285
     * @throws NullPointerException if {@code obj} is {@code null}
6ea0e148a562 8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents: 17431
diff changeset
   286
     * @since 1.8
6ea0e148a562 8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents: 17431
diff changeset
   287
     */
6ea0e148a562 8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents: 17431
diff changeset
   288
    public static <T> T requireNonNull(T obj, Supplier<String> messageSupplier) {
6ea0e148a562 8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents: 17431
diff changeset
   289
        if (obj == null)
6ea0e148a562 8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents: 17431
diff changeset
   290
            throw new NullPointerException(messageSupplier.get());
6ea0e148a562 8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents: 17431
diff changeset
   291
        return obj;
6ea0e148a562 8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents: 17431
diff changeset
   292
    }
4038
ea7aa63169db 6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff changeset
   293
}