author | psandoz |
Tue, 17 Nov 2015 14:11:46 +0100 | |
changeset 33844 | c81ff6d8588d |
parent 33675 | 7d9d372a41df |
child 34360 | 1b8b4b0b1608 |
permissions | -rw-r--r-- |
4038
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
1 |
/* |
33277
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
2 |
* Copyright (c) 2009, 2015, 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 | 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 | 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 | 21 |
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
22 |
* or visit www.oracle.com if you need additional information or have any |
|
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 |
|
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
28 |
import java.util.function.BiFunction; |
17465
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
29 |
import java.util.function.Supplier; |
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
30 |
|
4038
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
31 |
/** |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
32 |
* This class consists of {@code static} utility methods for operating |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
33 |
* on objects, or checking certain conditions before operation. These utilities |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
34 |
* include {@code null}-safe or {@code null}-tolerant methods for computing the |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
35 |
* hash code of an object, returning a string for an object, comparing two |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
36 |
* objects, and checking if indexes or sub-range values are out of bounds. |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
37 |
* |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
38 |
* @apiNote |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
39 |
* Static methods such as {@link Objects#checkIndex}, |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
40 |
* {@link Objects#checkFromToIndex}, and {@link Objects#checkFromIndexSize} are |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
41 |
* provided for the convenience of checking if values corresponding to indexes |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
42 |
* and sub-ranges are out of bounds. |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
43 |
* Variations of these static methods support customization of the runtime |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
44 |
* exception, and corresponding exception detail message, that is thrown when |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
45 |
* values are out of bounds. Such methods accept a functional interface |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
46 |
* argument, instances of {@code BiFunction}, that maps out of bound values to a |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
47 |
* runtime exception. Care should be taken when using such methods in |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
48 |
* combination with an argument that is a lambda expression, method reference or |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
49 |
* class that capture values. In such cases the cost of capture, related to |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
50 |
* functional interface allocation, may exceed the cost of checking bounds. |
4038
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 |
* @since 1.7 |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
53 |
*/ |
4165
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
54 |
public final class Objects { |
4038
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
55 |
private Objects() { |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
56 |
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
|
57 |
} |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
58 |
|
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
59 |
/** |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
60 |
* 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
|
61 |
* and {@code false} otherwise. |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
62 |
* 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
|
63 |
* 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
|
64 |
* 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
|
65 |
* 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
|
66 |
* argument. |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
67 |
* |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
68 |
* @param a an object |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
69 |
* @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
|
70 |
* @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
|
71 |
* and {@code false} otherwise |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
72 |
* @see Object#equals(Object) |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
73 |
*/ |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
74 |
public static boolean equals(Object a, Object b) { |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
75 |
return (a == b) || (a != null && a.equals(b)); |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
76 |
} |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
77 |
|
4165
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 |
* 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
|
80 |
* and {@code false} otherwise. |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
81 |
* |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
82 |
* 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
|
83 |
* 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
|
84 |
* 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
|
85 |
* 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
|
86 |
* 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
|
87 |
* |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
88 |
* @param a an object |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
89 |
* @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
|
90 |
* @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
|
91 |
* and {@code false} otherwise |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
92 |
* @see Arrays#deepEquals(Object[], Object[]) |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
93 |
* @see Objects#equals(Object, Object) |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
94 |
*/ |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
95 |
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
|
96 |
if (a == b) |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
97 |
return true; |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
98 |
else if (a == null || b == null) |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
99 |
return false; |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
100 |
else |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
101 |
return Arrays.deepEquals0(a, b); |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
102 |
} |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
103 |
|
4038
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
104 |
/** |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
105 |
* 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
|
106 |
* a {@code null} argument. |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
107 |
* |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
108 |
* @param o an object |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
109 |
* @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
|
110 |
* a {@code null} argument |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
111 |
* @see Object#hashCode |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
112 |
*/ |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
113 |
public static int hashCode(Object o) { |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
114 |
return o != null ? o.hashCode() : 0; |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
115 |
} |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
116 |
|
4165
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 |
* 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
|
119 |
* 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
|
120 |
* 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
|
121 |
* Arrays#hashCode(Object[])}. |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
122 |
* |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
123 |
* <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
|
124 |
* 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
|
125 |
* 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
|
126 |
* 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
|
127 |
* |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
128 |
* <blockquote><pre> |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
129 |
* @Override public int hashCode() { |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
130 |
* return Objects.hash(x, y, z); |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
131 |
* } |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
132 |
* </pre></blockquote> |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
133 |
* |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
134 |
* <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
|
135 |
* 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
|
136 |
* 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
|
137 |
* |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
138 |
* @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
|
139 |
* @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
|
140 |
* @see Arrays#hashCode(Object[]) |
4165
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
141 |
* @see List#hashCode |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
142 |
*/ |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
143 |
public static int hash(Object... values) { |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
144 |
return Arrays.hashCode(values); |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
145 |
} |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
146 |
|
4038
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
147 |
/** |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
148 |
* 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
|
149 |
* 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
|
150 |
* |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
151 |
* @param o an object |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
152 |
* @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
|
153 |
* 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
|
154 |
* @see Object#toString |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
155 |
* @see String#valueOf(Object) |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
156 |
*/ |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
157 |
public static String toString(Object o) { |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
158 |
return String.valueOf(o); |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
159 |
} |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
160 |
|
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
161 |
/** |
4165
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
162 |
* 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
|
163 |
* 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
|
164 |
* the second argument otherwise. |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
165 |
* |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
166 |
* @param o an object |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
167 |
* @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
|
168 |
* {@code null} |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
169 |
* @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
|
170 |
* 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
|
171 |
* otherwise. |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
172 |
* @see Objects#toString(Object) |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
173 |
*/ |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
174 |
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
|
175 |
return (o != null) ? o.toString() : nullDefault; |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
176 |
} |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
177 |
|
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
178 |
/** |
4038
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
179 |
* 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
|
180 |
* c.compare(a, b)} otherwise. |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
181 |
* Consequently, if both arguments are {@code null} 0 |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
182 |
* is returned. |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
183 |
* |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
184 |
* <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
|
185 |
* 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
|
186 |
* 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
|
187 |
* chooses to have for {@code null} values. |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
188 |
* |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
189 |
* @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
|
190 |
* @param a an object |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
191 |
* @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
|
192 |
* @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
|
193 |
* @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
|
194 |
* c.compare(a, b)} otherwise. |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
195 |
* @see Comparable |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
196 |
* @see Comparator |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
197 |
*/ |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
198 |
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
|
199 |
return (a == b) ? 0 : c.compare(a, b); |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
200 |
} |
4061 | 201 |
|
202 |
/** |
|
203 |
* Checks that the specified object reference is not {@code null}. This |
|
204 |
* method is designed primarily for doing parameter validation in methods |
|
205 |
* and constructors, as demonstrated below: |
|
206 |
* <blockquote><pre> |
|
207 |
* public Foo(Bar bar) { |
|
8166
13423c0952ad
7012540: java.util.Objects.nonNull() incorrectly named
briangoetz
parents:
5506
diff
changeset
|
208 |
* this.bar = Objects.requireNonNull(bar); |
4061 | 209 |
* } |
210 |
* </pre></blockquote> |
|
211 |
* |
|
212 |
* @param obj the object reference to check for nullity |
|
213 |
* @param <T> the type of the reference |
|
214 |
* @return {@code obj} if not {@code null} |
|
215 |
* @throws NullPointerException if {@code obj} is {@code null} |
|
216 |
*/ |
|
8166
13423c0952ad
7012540: java.util.Objects.nonNull() incorrectly named
briangoetz
parents:
5506
diff
changeset
|
217 |
public static <T> T requireNonNull(T obj) { |
4061 | 218 |
if (obj == null) |
219 |
throw new NullPointerException(); |
|
220 |
return obj; |
|
221 |
} |
|
222 |
||
223 |
/** |
|
224 |
* Checks that the specified object reference is not {@code null} and |
|
225 |
* throws a customized {@link NullPointerException} if it is. This method |
|
226 |
* is designed primarily for doing parameter validation in methods and |
|
227 |
* constructors with multiple parameters, as demonstrated below: |
|
228 |
* <blockquote><pre> |
|
229 |
* public Foo(Bar bar, Baz baz) { |
|
8166
13423c0952ad
7012540: java.util.Objects.nonNull() incorrectly named
briangoetz
parents:
5506
diff
changeset
|
230 |
* this.bar = Objects.requireNonNull(bar, "bar must not be null"); |
13423c0952ad
7012540: java.util.Objects.nonNull() incorrectly named
briangoetz
parents:
5506
diff
changeset
|
231 |
* this.baz = Objects.requireNonNull(baz, "baz must not be null"); |
4061 | 232 |
* } |
233 |
* </pre></blockquote> |
|
234 |
* |
|
235 |
* @param obj the object reference to check for nullity |
|
236 |
* @param message detail message to be used in the event that a {@code |
|
237 |
* NullPointerException} is thrown |
|
238 |
* @param <T> the type of the reference |
|
239 |
* @return {@code obj} if not {@code null} |
|
240 |
* @throws NullPointerException if {@code obj} is {@code null} |
|
241 |
*/ |
|
8166
13423c0952ad
7012540: java.util.Objects.nonNull() incorrectly named
briangoetz
parents:
5506
diff
changeset
|
242 |
public static <T> T requireNonNull(T obj, String message) { |
4061 | 243 |
if (obj == null) |
244 |
throw new NullPointerException(message); |
|
245 |
return obj; |
|
246 |
} |
|
17431 | 247 |
|
248 |
/** |
|
249 |
* Returns {@code true} if the provided reference is {@code null} otherwise |
|
250 |
* returns {@code false}. |
|
251 |
* |
|
252 |
* @apiNote This method exists to be used as a |
|
253 |
* {@link java.util.function.Predicate}, {@code filter(Objects::isNull)} |
|
254 |
* |
|
255 |
* @param obj a reference to be checked against {@code null} |
|
256 |
* @return {@code true} if the provided reference is {@code null} otherwise |
|
257 |
* {@code false} |
|
258 |
* |
|
259 |
* @see java.util.function.Predicate |
|
260 |
* @since 1.8 |
|
261 |
*/ |
|
262 |
public static boolean isNull(Object obj) { |
|
263 |
return obj == null; |
|
264 |
} |
|
265 |
||
266 |
/** |
|
267 |
* Returns {@code true} if the provided reference is non-{@code null} |
|
268 |
* otherwise returns {@code false}. |
|
269 |
* |
|
270 |
* @apiNote This method exists to be used as a |
|
271 |
* {@link java.util.function.Predicate}, {@code filter(Objects::nonNull)} |
|
272 |
* |
|
273 |
* @param obj a reference to be checked against {@code null} |
|
274 |
* @return {@code true} if the provided reference is non-{@code null} |
|
275 |
* otherwise {@code false} |
|
276 |
* |
|
277 |
* @see java.util.function.Predicate |
|
278 |
* @since 1.8 |
|
279 |
*/ |
|
280 |
public static boolean nonNull(Object obj) { |
|
281 |
return obj != null; |
|
282 |
} |
|
17465
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
283 |
|
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
284 |
/** |
33277
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
285 |
* Returns the first argument if it is non-{@code null} and |
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
286 |
* otherwise returns the non-{@code null} second argument. |
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
287 |
* |
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
288 |
* @param obj an object |
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
289 |
* @param defaultObj a non-{@code null} object to return if the first argument |
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
290 |
* is {@code null} |
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
291 |
* @param <T> the type of the reference |
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
292 |
* @return the first argument if it is non-{@code null} and |
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
293 |
* otherwise the second argument if it is non-{@code null} |
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
294 |
* @throws NullPointerException if both {@code obj} is null and |
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
295 |
* {@code defaultObj} is {@code null} |
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
296 |
* @since 9 |
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
297 |
*/ |
33675
7d9d372a41df
8141652: Rename methods Objects.nonNullElse* to requireNonNullElse*
rriggs
parents:
33277
diff
changeset
|
298 |
public static <T> T requireNonNullElse(T obj, T defaultObj) { |
33277
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
299 |
return (obj != null) ? obj : requireNonNull(defaultObj, "defaultObj"); |
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
300 |
} |
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
301 |
|
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
302 |
/** |
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
303 |
* Returns the first argument if it is non-{@code null} and otherwise |
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
304 |
* returns the non-{@code null} value of {@code supplier.get()}. |
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
305 |
* |
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
306 |
* @param obj an object |
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
307 |
* @param supplier of a non-{@code null} object to return if the first argument |
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
308 |
* is {@code null} |
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
309 |
* @param <T> the type of the first argument and return type |
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
310 |
* @return the first argument if it is non-{@code null} and otherwise |
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
311 |
* the value from {@code supplier.get()} if it is non-{@code null} |
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
312 |
* @throws NullPointerException if both {@code obj} is null and |
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
313 |
* either the {@code supplier} is {@code null} or |
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
314 |
* the {@code supplier.get()} value is {@code null} |
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
315 |
* @since 9 |
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
316 |
*/ |
33675
7d9d372a41df
8141652: Rename methods Objects.nonNullElse* to requireNonNullElse*
rriggs
parents:
33277
diff
changeset
|
317 |
public static <T> T requireNonNullElseGet(T obj, Supplier<? extends T> supplier) { |
7d9d372a41df
8141652: Rename methods Objects.nonNullElse* to requireNonNullElse*
rriggs
parents:
33277
diff
changeset
|
318 |
return (obj != null) ? obj |
7d9d372a41df
8141652: Rename methods Objects.nonNullElse* to requireNonNullElse*
rriggs
parents:
33277
diff
changeset
|
319 |
: requireNonNull(requireNonNull(supplier, "supplier").get(), "supplier.get()"); |
33277
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
320 |
} |
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
321 |
|
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
322 |
/** |
17465
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
323 |
* Checks that the specified object reference is not {@code null} and |
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
324 |
* throws a customized {@link NullPointerException} if it is. |
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
325 |
* |
17475
24f8cffd7390
8014677: Correct docs warning for Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17465
diff
changeset
|
326 |
* <p>Unlike the method {@link #requireNonNull(Object, String)}, |
17465
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
327 |
* this method allows creation of the message to be deferred until |
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
328 |
* after the null check is made. While this may confer a |
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
329 |
* performance advantage in the non-null case, when deciding to |
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
330 |
* call this method care should be taken that the costs of |
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
331 |
* creating the message supplier are less than the cost of just |
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
332 |
* creating the string message directly. |
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
333 |
* |
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
334 |
* @param obj the object reference to check for nullity |
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
335 |
* @param messageSupplier supplier of the detail message to be |
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
336 |
* used in the event that a {@code NullPointerException} is thrown |
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
337 |
* @param <T> the type of the reference |
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
338 |
* @return {@code obj} if not {@code null} |
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
339 |
* @throws NullPointerException if {@code obj} is {@code null} |
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
340 |
* @since 1.8 |
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
341 |
*/ |
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
342 |
public static <T> T requireNonNull(T obj, Supplier<String> messageSupplier) { |
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
343 |
if (obj == null) |
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
344 |
throw new NullPointerException(messageSupplier.get()); |
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
345 |
return obj; |
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
346 |
} |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
347 |
|
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
348 |
/** |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
349 |
* Maps out of bounds values to a runtime exception. |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
350 |
* |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
351 |
* @param a the first out of bound value |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
352 |
* @param b the second out of bound value |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
353 |
* @param oobe the exception mapping function that when applied with out of |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
354 |
* bounds arguments returns a runtime exception. If {@code null} |
33844
c81ff6d8588d
8142493: Utility methods to check indexes and ranges doesn't specify behavior when function produces null
psandoz
parents:
33675
diff
changeset
|
355 |
* then, it is as if an exception mapping function was supplied that |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
356 |
* returns {@link IndexOutOfBoundsException} for any given arguments. |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
357 |
* @return the runtime exception |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
358 |
*/ |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
359 |
private static RuntimeException outOfBounds( |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
360 |
int a, int b, BiFunction<Integer, Integer, ? extends RuntimeException> oobe) { |
33844
c81ff6d8588d
8142493: Utility methods to check indexes and ranges doesn't specify behavior when function produces null
psandoz
parents:
33675
diff
changeset
|
361 |
RuntimeException e = oobe == null |
c81ff6d8588d
8142493: Utility methods to check indexes and ranges doesn't specify behavior when function produces null
psandoz
parents:
33675
diff
changeset
|
362 |
? null : oobe.apply(a, b); |
c81ff6d8588d
8142493: Utility methods to check indexes and ranges doesn't specify behavior when function produces null
psandoz
parents:
33675
diff
changeset
|
363 |
return e == null |
c81ff6d8588d
8142493: Utility methods to check indexes and ranges doesn't specify behavior when function produces null
psandoz
parents:
33675
diff
changeset
|
364 |
? new IndexOutOfBoundsException(a, b) : e; |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
365 |
} |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
366 |
|
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
367 |
/** |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
368 |
* Checks if the {@code index} is within the bounds of the range from |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
369 |
* {@code 0} (inclusive) to {@code length} (exclusive). |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
370 |
* |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
371 |
* <p>The {@code index} is defined to be out of bounds if any of the |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
372 |
* following inequalities is true: |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
373 |
* <ul> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
374 |
* <li>{@code index < 0}</li> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
375 |
* <li>{@code index >= length}</li> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
376 |
* <li>{@code length < 0}, which is implied from the former inequalities</li> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
377 |
* </ul> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
378 |
* |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
379 |
* @param index the index |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
380 |
* @param length the upper-bound (exclusive) of the range |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
381 |
* @return {@code index} if it is within bounds of the range |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
382 |
* @throws IndexOutOfBoundsException if the {@code index} is out of bounds |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
383 |
* @since 9 |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
384 |
*/ |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
385 |
public static |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
386 |
int checkIndex(int index, int length) throws IndexOutOfBoundsException { |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
387 |
return checkIndex(index, length, null); |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
388 |
} |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
389 |
|
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
390 |
/** |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
391 |
* Checks if the {@code index} is within the bounds of the range from |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
392 |
* {@code 0} (inclusive) to {@code length} (exclusive). |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
393 |
* |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
394 |
* <p>The {@code index} is defined to be out of bounds if any of the |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
395 |
* following inequalities is true: |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
396 |
* <ul> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
397 |
* <li>{@code index < 0}</li> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
398 |
* <li>{@code index >= length}</li> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
399 |
* <li>{@code length < 0}, which is implied from the former inequalities</li> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
400 |
* </ul> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
401 |
* |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
402 |
* <p>If the {@code index} is out of bounds, then a runtime exception is |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
403 |
* thrown that is the result of applying the arguments {@code index} and |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
404 |
* {@code length} to the given exception mapping function. |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
405 |
* |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
406 |
* @param <T> the type of runtime exception to throw if the arguments are |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
407 |
* out of bounds |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
408 |
* @param index the index |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
409 |
* @param length the upper-bound (exclusive) of the range |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
410 |
* @param oobe the exception mapping function that when applied with out |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
411 |
* of bounds arguments returns a runtime exception. If {@code null} |
33844
c81ff6d8588d
8142493: Utility methods to check indexes and ranges doesn't specify behavior when function produces null
psandoz
parents:
33675
diff
changeset
|
412 |
* or returns {@code null} then, it is as if an exception mapping |
c81ff6d8588d
8142493: Utility methods to check indexes and ranges doesn't specify behavior when function produces null
psandoz
parents:
33675
diff
changeset
|
413 |
* function was supplied that returns |
c81ff6d8588d
8142493: Utility methods to check indexes and ranges doesn't specify behavior when function produces null
psandoz
parents:
33675
diff
changeset
|
414 |
* {@link IndexOutOfBoundsException} for any given arguments. |
c81ff6d8588d
8142493: Utility methods to check indexes and ranges doesn't specify behavior when function produces null
psandoz
parents:
33675
diff
changeset
|
415 |
* Exceptions thrown by the function are relayed to the caller. |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
416 |
* @return {@code index} if it is within bounds of the range |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
417 |
* @throws T if the {@code index} is out of bounds, then a runtime exception |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
418 |
* is thrown that is the result of applying the out of bounds |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
419 |
* arguments to the exception mapping function. |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
420 |
* @throws IndexOutOfBoundsException if the {@code index} is out of bounds |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
421 |
* and the exception mapping function is {@code null} |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
422 |
* @since 9 |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
423 |
*/ |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
424 |
/* |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
425 |
@HotSpotIntrinsicCandidate |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
426 |
This method will be made intrinsic in C2 to guide HotSpot to perform |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
427 |
unsigned comparisons of the index and length when it is known the length is |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
428 |
a non-negative value (such as that of an array length or from the upper |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
429 |
bound of a loop) |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
430 |
*/ |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
431 |
public static <T extends RuntimeException> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
432 |
int checkIndex(int index, int length, |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
433 |
BiFunction<Integer, Integer, T> oobe) throws T, IndexOutOfBoundsException { |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
434 |
if (index < 0 || index >= length) |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
435 |
throw outOfBounds(index, length, oobe); |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
436 |
return index; |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
437 |
} |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
438 |
|
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
439 |
/** |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
440 |
* Checks if the sub-range from {@code fromIndex} (inclusive) to |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
441 |
* {@code toIndex} (exclusive) is within the bounds of range from {@code 0} |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
442 |
* (inclusive) to {@code length} (exclusive). |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
443 |
* |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
444 |
* <p>The sub-range is defined to be out of bounds if any of the following |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
445 |
* inequalities is true: |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
446 |
* <ul> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
447 |
* <li>{@code fromIndex < 0}</li> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
448 |
* <li>{@code fromIndex > toIndex}</li> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
449 |
* <li>{@code toIndex > length}</li> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
450 |
* <li>{@code length < 0}, which is implied from the former inequalities</li> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
451 |
* </ul> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
452 |
* |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
453 |
* @param fromIndex the lower-bound (inclusive) of the sub-range |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
454 |
* @param toIndex the upper-bound (exclusive) of the sub-range |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
455 |
* @param length the upper-bound (exclusive) the range |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
456 |
* @return {@code fromIndex} if the sub-range within bounds of the range |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
457 |
* @throws IndexOutOfBoundsException if the sub-range is out of bounds |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
458 |
* @since 9 |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
459 |
*/ |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
460 |
public static |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
461 |
int checkFromToIndex(int fromIndex, int toIndex, int length) throws IndexOutOfBoundsException { |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
462 |
return checkFromToIndex(fromIndex, toIndex, length, null); |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
463 |
} |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
464 |
|
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
465 |
/** |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
466 |
* Checks if the sub-range from {@code fromIndex} (inclusive) to |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
467 |
* {@code toIndex} (exclusive) is within the bounds of range from {@code 0} |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
468 |
* (inclusive) to {@code length} (exclusive). |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
469 |
* |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
470 |
* <p>The sub-range is defined to be out of bounds if any of the following |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
471 |
* inequalities is true: |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
472 |
* <ul> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
473 |
* <li>{@code fromIndex < 0}</li> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
474 |
* <li>{@code fromIndex > toIndex}</li> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
475 |
* <li>{@code toIndex > length}</li> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
476 |
* <li>{@code length < 0}, which is implied from the former inequalities</li> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
477 |
* </ul> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
478 |
* |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
479 |
* <p>If the sub-range is out of bounds, then a runtime exception is thrown |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
480 |
* that is the result of applying the arguments {@code fromIndex} and |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
481 |
* {@code toIndex} to the given exception mapping function. |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
482 |
* |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
483 |
* @param <T> the type of runtime exception to throw if the arguments are |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
484 |
* out of bounds |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
485 |
* @param fromIndex the lower-bound (inclusive) of the sub-range |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
486 |
* @param toIndex the upper-bound (exclusive) of the sub-range |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
487 |
* @param length the upper-bound (exclusive) the range |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
488 |
* @param oobe the exception mapping function that when applied with out |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
489 |
* of bounds arguments returns a runtime exception. If {@code null} |
33844
c81ff6d8588d
8142493: Utility methods to check indexes and ranges doesn't specify behavior when function produces null
psandoz
parents:
33675
diff
changeset
|
490 |
* or returns {@code null} then, it is as if an exception mapping |
c81ff6d8588d
8142493: Utility methods to check indexes and ranges doesn't specify behavior when function produces null
psandoz
parents:
33675
diff
changeset
|
491 |
* function was supplied that returns |
c81ff6d8588d
8142493: Utility methods to check indexes and ranges doesn't specify behavior when function produces null
psandoz
parents:
33675
diff
changeset
|
492 |
* {@link IndexOutOfBoundsException} for any given arguments. |
c81ff6d8588d
8142493: Utility methods to check indexes and ranges doesn't specify behavior when function produces null
psandoz
parents:
33675
diff
changeset
|
493 |
* Exceptions thrown by the function are relayed to the caller. |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
494 |
* @return {@code fromIndex} if the sub-range within bounds of the range |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
495 |
* @throws T if the sub-range is out of bounds, then a runtime exception is |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
496 |
* thrown that is the result of applying the out of bounds arguments |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
497 |
* to the exception mapping function. |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
498 |
* @throws IndexOutOfBoundsException if the sub-range is out of bounds and |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
499 |
* the exception mapping function is {@code null} |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
500 |
* @since 9 |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
501 |
*/ |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
502 |
public static <T extends RuntimeException> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
503 |
int checkFromToIndex(int fromIndex, int toIndex, int length, |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
504 |
BiFunction<Integer, Integer, T> oobe) throws T, IndexOutOfBoundsException { |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
505 |
if (fromIndex < 0 || fromIndex > toIndex || toIndex > length) |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
506 |
throw outOfBounds(fromIndex, toIndex, oobe); |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
507 |
return fromIndex; |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
508 |
} |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
509 |
|
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
510 |
/** |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
511 |
* Checks if the sub-range from {@code fromIndex} (inclusive) to |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
512 |
* {@code fromIndex + size} (exclusive) is within the bounds of range from |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
513 |
* {@code 0} (inclusive) to {@code length} (exclusive). |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
514 |
* |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
515 |
* <p>The sub-range is defined to be out of bounds if any of the following |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
516 |
* inequalities is true: |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
517 |
* <ul> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
518 |
* <li>{@code fromIndex < 0}</li> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
519 |
* <li>{@code size < 0}</li> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
520 |
* <li>{@code fromIndex + size > length}, taking into account integer overflow</li> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
521 |
* <li>{@code length < 0}, which is implied from the former inequalities</li> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
522 |
* </ul> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
523 |
* |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
524 |
* @param fromIndex the lower-bound (inclusive) of the sub-interval |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
525 |
* @param size the size of the sub-range |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
526 |
* @param length the upper-bound (exclusive) of the range |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
527 |
* @return {@code fromIndex} if the sub-range within bounds of the range |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
528 |
* @throws IndexOutOfBoundsException if the sub-range is out of bounds |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
529 |
* @since 9 |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
530 |
*/ |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
531 |
public static |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
532 |
int checkFromIndexSize(int fromIndex, int size, int length) throws IndexOutOfBoundsException { |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
533 |
return checkFromIndexSize(fromIndex, size, length, null); |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
534 |
} |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
535 |
|
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
536 |
/** |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
537 |
* Checks if the sub-range from {@code fromIndex} (inclusive) to |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
538 |
* {@code fromIndex + size} (exclusive) is within the bounds of range from |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
539 |
* {@code 0} (inclusive) to {@code length} (exclusive). |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
540 |
* |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
541 |
* <p>The sub-range is defined to be out of bounds if any of the following |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
542 |
* inequalities is true: |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
543 |
* <ul> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
544 |
* <li>{@code fromIndex < 0}</li> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
545 |
* <li>{@code size < 0}</li> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
546 |
* <li>{@code fromIndex + size > length}, taking into account integer overflow</li> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
547 |
* <li>{@code length < 0}, which is implied from the former inequalities</li> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
548 |
* </ul> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
549 |
* |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
550 |
* <p>If the sub-range is out of bounds then, a runtime exception is thrown |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
551 |
* that is the result of applying the arguments {@code fromIndex} and |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
552 |
* {@code size} to the given exception mapping function. |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
553 |
* |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
554 |
* @param <T> the type of runtime exception to throw if the arguments are |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
555 |
* out of bounds |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
556 |
* @param fromIndex the lower-bound (inclusive) of the sub-interval |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
557 |
* @param size the size of the sub-range |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
558 |
* @param length the upper-bound (exclusive) of the range |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
559 |
* @param oobe the exception mapping function that when applied with out |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
560 |
* of bounds arguments returns a runtime exception. If {@code null} |
33844
c81ff6d8588d
8142493: Utility methods to check indexes and ranges doesn't specify behavior when function produces null
psandoz
parents:
33675
diff
changeset
|
561 |
* or returns {@code null} then, it is as if an exception mapping |
c81ff6d8588d
8142493: Utility methods to check indexes and ranges doesn't specify behavior when function produces null
psandoz
parents:
33675
diff
changeset
|
562 |
* function was supplied that returns |
c81ff6d8588d
8142493: Utility methods to check indexes and ranges doesn't specify behavior when function produces null
psandoz
parents:
33675
diff
changeset
|
563 |
* {@link IndexOutOfBoundsException} for any given arguments. |
c81ff6d8588d
8142493: Utility methods to check indexes and ranges doesn't specify behavior when function produces null
psandoz
parents:
33675
diff
changeset
|
564 |
* Exceptions thrown by the function are relayed to the caller. |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
565 |
* @return {@code fromIndex} if the sub-range within bounds of the range |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
566 |
* @throws T if the sub-range is out of bounds, then a runtime exception is |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
567 |
* thrown that is the result of applying the out of bounds arguments |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
568 |
* to the exception mapping function. |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
569 |
* @throws IndexOutOfBoundsException if the sub-range is out of bounds and |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
570 |
* the exception mapping function is {@code null} |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
571 |
* @since 9 |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
572 |
*/ |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
573 |
public static <T extends RuntimeException> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
574 |
int checkFromIndexSize(int fromIndex, int size, int length, |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
575 |
BiFunction<Integer, Integer, T> oobe) throws T, IndexOutOfBoundsException { |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
576 |
if ((length | fromIndex | size) < 0 || size > length - fromIndex) |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
577 |
throw outOfBounds(fromIndex, size, oobe); |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
578 |
return fromIndex; |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
579 |
} |
4038
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
580 |
} |