author | psandoz |
Wed, 13 Apr 2016 15:05:50 +0200 | |
changeset 37345 | 9cb6e1141bdb |
parent 34360 | 1b8b4b0b1608 |
child 38356 | 1e4ecca97792 |
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 |
|
37345
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
28 |
import jdk.internal.HotSpotIntrinsicCandidate; |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
29 |
|
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
30 |
import java.util.function.BiFunction; |
37345
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
31 |
import java.util.function.Function; |
17465
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
32 |
import java.util.function.Supplier; |
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
33 |
|
4038
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
34 |
/** |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
35 |
* 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
|
36 |
* 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
|
37 |
* 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
|
38 |
* hash code of an object, returning a string for an object, comparing two |
37345
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
39 |
* objects, and checking if indexes or sub-range values are out-of-bounds. |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
40 |
* |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
41 |
* @apiNote |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
42 |
* Static methods such as {@link Objects#checkIndex}, |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
43 |
* {@link Objects#checkFromToIndex}, and {@link Objects#checkFromIndexSize} are |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
44 |
* provided for the convenience of checking if values corresponding to indexes |
37345
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
45 |
* and sub-ranges are out-of-bounds. |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
46 |
* 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
|
47 |
* exception, and corresponding exception detail message, that is thrown when |
37345
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
48 |
* values are out-of-bounds. Such methods accept a functional interface |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
49 |
* argument, instances of {@code BiFunction}, that maps out-of-bound values to a |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
50 |
* 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
|
51 |
* 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
|
52 |
* 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
|
53 |
* 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
|
54 |
* |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
55 |
* @since 1.7 |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
56 |
*/ |
4165
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
57 |
public final class Objects { |
4038
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
58 |
private Objects() { |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
59 |
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
|
60 |
} |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
61 |
|
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
62 |
/** |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
63 |
* 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
|
64 |
* and {@code false} otherwise. |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
65 |
* 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
|
66 |
* 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
|
67 |
* 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
|
68 |
* 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
|
69 |
* argument. |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
70 |
* |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
71 |
* @param a an object |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
72 |
* @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
|
73 |
* @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
|
74 |
* and {@code false} otherwise |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
75 |
* @see Object#equals(Object) |
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 |
public static boolean equals(Object a, Object b) { |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
78 |
return (a == b) || (a != null && a.equals(b)); |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
79 |
} |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
80 |
|
4165
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 |
* 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
|
83 |
* and {@code false} otherwise. |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
84 |
* |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
85 |
* 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
|
86 |
* 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
|
87 |
* 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
|
88 |
* 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
|
89 |
* 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
|
90 |
* |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
91 |
* @param a an object |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
92 |
* @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
|
93 |
* @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
|
94 |
* and {@code false} otherwise |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
95 |
* @see Arrays#deepEquals(Object[], Object[]) |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
96 |
* @see Objects#equals(Object, Object) |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
97 |
*/ |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
98 |
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
|
99 |
if (a == b) |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
100 |
return true; |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
101 |
else if (a == null || b == null) |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
102 |
return false; |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
103 |
else |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
104 |
return Arrays.deepEquals0(a, b); |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
105 |
} |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
106 |
|
4038
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 |
* 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
|
109 |
* a {@code null} argument. |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
110 |
* |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
111 |
* @param o an object |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
112 |
* @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
|
113 |
* a {@code null} argument |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
114 |
* @see Object#hashCode |
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 |
public static int hashCode(Object o) { |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
117 |
return o != null ? o.hashCode() : 0; |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
118 |
} |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
119 |
|
4165
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
120 |
/** |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
121 |
* 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
|
122 |
* 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
|
123 |
* 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
|
124 |
* Arrays#hashCode(Object[])}. |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
125 |
* |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
126 |
* <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
|
127 |
* 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
|
128 |
* 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
|
129 |
* 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
|
130 |
* |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
131 |
* <blockquote><pre> |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
132 |
* @Override public int hashCode() { |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
133 |
* return Objects.hash(x, y, z); |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
134 |
* } |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
135 |
* </pre></blockquote> |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
136 |
* |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
137 |
* <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
|
138 |
* 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
|
139 |
* 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
|
140 |
* |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
141 |
* @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
|
142 |
* @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
|
143 |
* @see Arrays#hashCode(Object[]) |
4165
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
144 |
* @see List#hashCode |
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 |
public static int hash(Object... values) { |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
147 |
return Arrays.hashCode(values); |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
148 |
} |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
149 |
|
4038
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 |
* 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
|
152 |
* 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
|
153 |
* |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
154 |
* @param o an object |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
155 |
* @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
|
156 |
* 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
|
157 |
* @see Object#toString |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
158 |
* @see String#valueOf(Object) |
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 |
public static String toString(Object o) { |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
161 |
return String.valueOf(o); |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
162 |
} |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
163 |
|
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
164 |
/** |
4165
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
165 |
* 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
|
166 |
* 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
|
167 |
* the second argument otherwise. |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
168 |
* |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
169 |
* @param o an object |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
170 |
* @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
|
171 |
* {@code null} |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
172 |
* @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
|
173 |
* 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
|
174 |
* otherwise. |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
175 |
* @see Objects#toString(Object) |
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 |
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
|
178 |
return (o != null) ? o.toString() : nullDefault; |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
179 |
} |
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
180 |
|
7cd799c224da
6891113: More methods for java.util.Objects: deepEquals, hash, toString with default
darcy
parents:
4061
diff
changeset
|
181 |
/** |
4038
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
182 |
* 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
|
183 |
* c.compare(a, b)} otherwise. |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
184 |
* Consequently, if both arguments are {@code null} 0 |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
185 |
* is returned. |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
186 |
* |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
187 |
* <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
|
188 |
* 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
|
189 |
* 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
|
190 |
* chooses to have for {@code null} values. |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
191 |
* |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
192 |
* @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
|
193 |
* @param a an object |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
194 |
* @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
|
195 |
* @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
|
196 |
* @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
|
197 |
* c.compare(a, b)} otherwise. |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
198 |
* @see Comparable |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
199 |
* @see Comparator |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
200 |
*/ |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
201 |
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
|
202 |
return (a == b) ? 0 : c.compare(a, b); |
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
203 |
} |
4061 | 204 |
|
205 |
/** |
|
206 |
* Checks that the specified object reference is not {@code null}. This |
|
207 |
* method is designed primarily for doing parameter validation in methods |
|
208 |
* and constructors, as demonstrated below: |
|
209 |
* <blockquote><pre> |
|
210 |
* public Foo(Bar bar) { |
|
8166
13423c0952ad
7012540: java.util.Objects.nonNull() incorrectly named
briangoetz
parents:
5506
diff
changeset
|
211 |
* this.bar = Objects.requireNonNull(bar); |
4061 | 212 |
* } |
213 |
* </pre></blockquote> |
|
214 |
* |
|
215 |
* @param obj the object reference to check for nullity |
|
216 |
* @param <T> the type of the reference |
|
217 |
* @return {@code obj} if not {@code null} |
|
218 |
* @throws NullPointerException if {@code obj} is {@code null} |
|
219 |
*/ |
|
8166
13423c0952ad
7012540: java.util.Objects.nonNull() incorrectly named
briangoetz
parents:
5506
diff
changeset
|
220 |
public static <T> T requireNonNull(T obj) { |
4061 | 221 |
if (obj == null) |
222 |
throw new NullPointerException(); |
|
223 |
return obj; |
|
224 |
} |
|
225 |
||
226 |
/** |
|
227 |
* Checks that the specified object reference is not {@code null} and |
|
228 |
* throws a customized {@link NullPointerException} if it is. This method |
|
229 |
* is designed primarily for doing parameter validation in methods and |
|
230 |
* constructors with multiple parameters, as demonstrated below: |
|
231 |
* <blockquote><pre> |
|
232 |
* public Foo(Bar bar, Baz baz) { |
|
8166
13423c0952ad
7012540: java.util.Objects.nonNull() incorrectly named
briangoetz
parents:
5506
diff
changeset
|
233 |
* this.bar = Objects.requireNonNull(bar, "bar must not be null"); |
13423c0952ad
7012540: java.util.Objects.nonNull() incorrectly named
briangoetz
parents:
5506
diff
changeset
|
234 |
* this.baz = Objects.requireNonNull(baz, "baz must not be null"); |
4061 | 235 |
* } |
236 |
* </pre></blockquote> |
|
237 |
* |
|
238 |
* @param obj the object reference to check for nullity |
|
239 |
* @param message detail message to be used in the event that a {@code |
|
240 |
* NullPointerException} is thrown |
|
241 |
* @param <T> the type of the reference |
|
242 |
* @return {@code obj} if not {@code null} |
|
243 |
* @throws NullPointerException if {@code obj} is {@code null} |
|
244 |
*/ |
|
8166
13423c0952ad
7012540: java.util.Objects.nonNull() incorrectly named
briangoetz
parents:
5506
diff
changeset
|
245 |
public static <T> T requireNonNull(T obj, String message) { |
4061 | 246 |
if (obj == null) |
247 |
throw new NullPointerException(message); |
|
248 |
return obj; |
|
249 |
} |
|
17431 | 250 |
|
251 |
/** |
|
252 |
* Returns {@code true} if the provided reference is {@code null} otherwise |
|
253 |
* returns {@code false}. |
|
254 |
* |
|
255 |
* @apiNote This method exists to be used as a |
|
256 |
* {@link java.util.function.Predicate}, {@code filter(Objects::isNull)} |
|
257 |
* |
|
258 |
* @param obj a reference to be checked against {@code null} |
|
259 |
* @return {@code true} if the provided reference is {@code null} otherwise |
|
260 |
* {@code false} |
|
261 |
* |
|
262 |
* @see java.util.function.Predicate |
|
263 |
* @since 1.8 |
|
264 |
*/ |
|
265 |
public static boolean isNull(Object obj) { |
|
266 |
return obj == null; |
|
267 |
} |
|
268 |
||
269 |
/** |
|
270 |
* Returns {@code true} if the provided reference is non-{@code null} |
|
271 |
* otherwise returns {@code false}. |
|
272 |
* |
|
273 |
* @apiNote This method exists to be used as a |
|
274 |
* {@link java.util.function.Predicate}, {@code filter(Objects::nonNull)} |
|
275 |
* |
|
276 |
* @param obj a reference to be checked against {@code null} |
|
277 |
* @return {@code true} if the provided reference is non-{@code null} |
|
278 |
* otherwise {@code false} |
|
279 |
* |
|
280 |
* @see java.util.function.Predicate |
|
281 |
* @since 1.8 |
|
282 |
*/ |
|
283 |
public static boolean nonNull(Object obj) { |
|
284 |
return obj != null; |
|
285 |
} |
|
17465
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
286 |
|
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
287 |
/** |
33277
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
288 |
* 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
|
289 |
* 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
|
290 |
* |
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
291 |
* @param obj an object |
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
292 |
* @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
|
293 |
* is {@code null} |
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
294 |
* @param <T> the type of the reference |
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
295 |
* @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
|
296 |
* 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
|
297 |
* @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
|
298 |
* {@code defaultObj} is {@code null} |
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
299 |
* @since 9 |
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
300 |
*/ |
33675
7d9d372a41df
8141652: Rename methods Objects.nonNullElse* to requireNonNullElse*
rriggs
parents:
33277
diff
changeset
|
301 |
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
|
302 |
return (obj != null) ? obj : requireNonNull(defaultObj, "defaultObj"); |
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
303 |
} |
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
304 |
|
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 |
* 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
|
307 |
* 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
|
308 |
* |
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
309 |
* @param obj an object |
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
310 |
* @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
|
311 |
* is {@code null} |
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
312 |
* @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
|
313 |
* @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
|
314 |
* 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
|
315 |
* @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
|
316 |
* 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
|
317 |
* 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
|
318 |
* @since 9 |
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
319 |
*/ |
33675
7d9d372a41df
8141652: Rename methods Objects.nonNullElse* to requireNonNullElse*
rriggs
parents:
33277
diff
changeset
|
320 |
public static <T> T requireNonNullElseGet(T obj, Supplier<? extends T> supplier) { |
7d9d372a41df
8141652: Rename methods Objects.nonNullElse* to requireNonNullElse*
rriggs
parents:
33277
diff
changeset
|
321 |
return (obj != null) ? obj |
7d9d372a41df
8141652: Rename methods Objects.nonNullElse* to requireNonNullElse*
rriggs
parents:
33277
diff
changeset
|
322 |
: 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
|
323 |
} |
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
324 |
|
90a40b7f53ef
8138963: java.lang.Objects new method to default to non-null
rriggs
parents:
32929
diff
changeset
|
325 |
/** |
17465
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
326 |
* Checks that the specified object reference is not {@code null} and |
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
327 |
* throws a customized {@link NullPointerException} if it is. |
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
328 |
* |
17475
24f8cffd7390
8014677: Correct docs warning for Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17465
diff
changeset
|
329 |
* <p>Unlike the method {@link #requireNonNull(Object, String)}, |
17465
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
330 |
* this method allows creation of the message to be deferred until |
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
331 |
* after the null check is made. While this may confer a |
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
332 |
* performance advantage in the non-null case, when deciding to |
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
333 |
* call this method care should be taken that the costs of |
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
334 |
* creating the message supplier are less than the cost of just |
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
335 |
* creating the string message directly. |
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
336 |
* |
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
337 |
* @param obj the object reference to check for nullity |
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
338 |
* @param messageSupplier supplier of the detail message to be |
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
339 |
* used in the event that a {@code NullPointerException} is thrown |
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
340 |
* @param <T> the type of the reference |
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
341 |
* @return {@code obj} if not {@code null} |
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
342 |
* @throws NullPointerException if {@code obj} is {@code null} |
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
343 |
* @since 1.8 |
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
344 |
*/ |
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
345 |
public static <T> T requireNonNull(T obj, Supplier<String> messageSupplier) { |
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
346 |
if (obj == null) |
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
347 |
throw new NullPointerException(messageSupplier.get()); |
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
348 |
return obj; |
6ea0e148a562
8014365: Restore Objects.requireNonNull(T, Supplier<String>)
darcy
parents:
17431
diff
changeset
|
349 |
} |
32929
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 |
/** |
37345
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
352 |
* Maps out-of-bounds values to a runtime exception. |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
353 |
* |
37345
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
354 |
* @param checkKind the kind of bounds check, whose name may correspond |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
355 |
* to the name of one of the range check methods, checkIndex, |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
356 |
* checkFromToIndex, checkFromIndexSize |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
357 |
* @param args the out-of-bounds arguments that failed the range check. |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
358 |
* If the checkKind corresponds a the name of a range check method |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
359 |
* then the bounds arguments are those that can be passed in order |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
360 |
* to the method. |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
361 |
* @param oobef the exception formatter that when applied with a checkKind |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
362 |
* and a list out-of-bounds arguments returns a runtime exception. |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
363 |
* If {@code null} then, it is as if an exception formatter was |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
364 |
* supplied that returns {@link IndexOutOfBoundsException} for any |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
365 |
* given arguments. |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
366 |
* @return the runtime exception |
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 |
private static RuntimeException outOfBounds( |
37345
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
369 |
BiFunction<String, List<Integer>, ? extends RuntimeException> oobef, |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
370 |
String checkKind, |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
371 |
Integer... args) { |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
372 |
List<Integer> largs = List.of(args); |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
373 |
RuntimeException e = oobef == null |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
374 |
? null : oobef.apply(checkKind, largs); |
33844
c81ff6d8588d
8142493: Utility methods to check indexes and ranges doesn't specify behavior when function produces null
psandoz
parents:
33675
diff
changeset
|
375 |
return e == null |
37345
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
376 |
? new IndexOutOfBoundsException(outOfBoundsMessage(checkKind, largs)) : e; |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
377 |
} |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
378 |
|
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
379 |
// Specific out-of-bounds exception producing methods that avoid |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
380 |
// the varargs-based code in the critical methods there by reducing their |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
381 |
// the byte code size, and therefore less likely to peturb inlining |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
382 |
|
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
383 |
private static RuntimeException outOfBoundsCheckIndex( |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
384 |
BiFunction<String, List<Integer>, ? extends RuntimeException> oobe, |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
385 |
int index, int length) { |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
386 |
return outOfBounds(oobe, "checkIndex", index, length); |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
387 |
} |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
388 |
|
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
389 |
private static RuntimeException outOfBoundsCheckFromToIndex( |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
390 |
BiFunction<String, List<Integer>, ? extends RuntimeException> oobe, |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
391 |
int fromIndex, int toIndex, int length) { |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
392 |
return outOfBounds(oobe, "checkFromToIndex", fromIndex, toIndex, length); |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
393 |
} |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
394 |
|
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
395 |
private static RuntimeException outOfBoundsCheckFromIndexSize( |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
396 |
BiFunction<String, List<Integer>, ? extends RuntimeException> oobe, |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
397 |
int fromIndex, int size, int length) { |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
398 |
return outOfBounds(oobe, "checkFromIndexSize", fromIndex, size, length); |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
399 |
} |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
400 |
|
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
401 |
/** |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
402 |
* Returns an out-of-bounds exception formatter from an given exception |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
403 |
* factory. The exception formatter is a function that formats an |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
404 |
* out-of-bounds message from its arguments and applies that message to the |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
405 |
* given exception factory to produce and relay an exception. |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
406 |
* |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
407 |
* <p>The exception formatter accepts two arguments: a {@code String} |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
408 |
* describing the out-of-bounds range check that failed, referred to as the |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
409 |
* <em>check kind</em>; and a {@code List<Integer>} containing the |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
410 |
* out-of-bound integer values that failed the check. The list of |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
411 |
* out-of-bound values is not modified. |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
412 |
* |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
413 |
* <p>Three check kinds are supported {@code checkIndex}, |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
414 |
* {@code checkFromToIndex} and {@code checkFromIndexSize} corresponding |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
415 |
* respectively to the specified application of an exception formatter as an |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
416 |
* argument to the out-of-bounds range check methods |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
417 |
* {@link #checkIndex(int, int, BiFunction) checkIndex}, |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
418 |
* {@link #checkFromToIndex(int, int, int, BiFunction) checkFromToIndex}, and |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
419 |
* {@link #checkFromIndexSize(int, int, int, BiFunction) checkFromIndexSize}. |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
420 |
* Thus a supported check kind corresponds to a method name and the |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
421 |
* out-of-bound integer values correspond to method argument values, in |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
422 |
* order, preceding the exception formatter argument (similar in many |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
423 |
* respects to the form of arguments required for a reflective invocation of |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
424 |
* such a range check method). |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
425 |
* |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
426 |
* <p>Formatter arguments conforming to such supported check kinds will |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
427 |
* produce specific exception messages describing failed out-of-bounds |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
428 |
* checks. Otherwise, more generic exception messages will be produced in |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
429 |
* any of the following cases: the check kind is supported but fewer |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
430 |
* or more out-of-bounds values are supplied, the check kind is not |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
431 |
* supported, the check kind is {@code null}, or the list of out-of-bound |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
432 |
* values is {@code null}. |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
433 |
* |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
434 |
* @apiNote |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
435 |
* This method produces an out-of-bounds exception formatter that can be |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
436 |
* passed as an argument to any of the supported out-of-bounds range check |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
437 |
* methods declared by {@code Objects}. For example, a formatter producing |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
438 |
* an {@code ArrayIndexOutOfBoundsException} may be produced and stored on a |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
439 |
* {@code static final} field as follows: |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
440 |
* <pre>{@code |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
441 |
* static final |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
442 |
* BiFunction<String, List<Integer>, ArrayIndexOutOfBoundsException> AIOOBEF = |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
443 |
* outOfBoundsExceptionFormatter(ArrayIndexOutOfBoundsException::new); |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
444 |
* }</pre> |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
445 |
* The formatter instance {@code AIOOBEF} may be passed as an argument to an |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
446 |
* out-of-bounds range check method, such as checking if an {@code index} |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
447 |
* is within the bounds of a {@code limit}: |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
448 |
* <pre>{@code |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
449 |
* checkIndex(index, limit, AIOOBEF); |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
450 |
* }</pre> |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
451 |
* If the bounds check fails then the range check method will throw an |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
452 |
* {@code ArrayIndexOutOfBoundsException} with an appropriate exception |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
453 |
* message that is a produced from {@code AIOOBEF} as follows: |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
454 |
* <pre>{@code |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
455 |
* AIOOBEF.apply("checkIndex", List.of(index, limit)); |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
456 |
* }</pre> |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
457 |
* |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
458 |
* @param f the exception factory, that produces an exception from a message |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
459 |
* where the message is produced and formatted by the returned |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
460 |
* exception formatter. If this factory is stateless and side-effect |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
461 |
* free then so is the returned formatter. |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
462 |
* Exceptions thrown by the factory are relayed to the caller |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
463 |
* of the returned formatter. |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
464 |
* @param <X> the type of runtime exception to be returned by the given |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
465 |
* exception factory and relayed by the exception formatter |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
466 |
* @return the out-of-bounds exception formatter |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
467 |
*/ |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
468 |
public static <X extends RuntimeException> |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
469 |
BiFunction<String, List<Integer>, X> outOfBoundsExceptionFormatter(Function<String, X> f) { |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
470 |
// Use anonymous class to avoid bootstrap issues if this method is |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
471 |
// used early in startup |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
472 |
return new BiFunction<String, List<Integer>, X>() { |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
473 |
@Override |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
474 |
public X apply(String checkKind, List<Integer> args) { |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
475 |
return f.apply(outOfBoundsMessage(checkKind, args)); |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
476 |
} |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
477 |
}; |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
478 |
} |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
479 |
|
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
480 |
private static String outOfBoundsMessage(String checkKind, List<Integer> args) { |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
481 |
if (checkKind == null && args == null) { |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
482 |
return String.format("Range check failed"); |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
483 |
} else if (checkKind == null) { |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
484 |
return String.format("Range check failed: %s", args); |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
485 |
} else if (args == null) { |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
486 |
return String.format("Range check failed: %s", checkKind); |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
487 |
} |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
488 |
|
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
489 |
int argSize = 0; |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
490 |
switch (checkKind) { |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
491 |
case "checkIndex": |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
492 |
argSize = 2; |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
493 |
break; |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
494 |
case "checkFromToIndex": |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
495 |
case "checkFromIndexSize": |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
496 |
argSize = 3; |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
497 |
break; |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
498 |
default: |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
499 |
} |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
500 |
|
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
501 |
// Switch to default if fewer or more arguments than required are supplied |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
502 |
switch ((args.size() != argSize) ? "" : checkKind) { |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
503 |
case "checkIndex": |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
504 |
return String.format("Index %d out-of-bounds for length %d", |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
505 |
args.get(0), args.get(1)); |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
506 |
case "checkFromToIndex": |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
507 |
return String.format("Range [%d, %d) out-of-bounds for length %d", |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
508 |
args.get(0), args.get(1), args.get(2)); |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
509 |
case "checkFromIndexSize": |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
510 |
return String.format("Range [%d, %<d + %d) out-of-bounds for length %d", |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
511 |
args.get(0), args.get(1), args.get(2)); |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
512 |
default: |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
513 |
return String.format("Range check failed: %s %s", checkKind, args); |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
514 |
} |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
515 |
} |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
516 |
|
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
517 |
/** |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
518 |
* 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
|
519 |
* {@code 0} (inclusive) to {@code length} (exclusive). |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
520 |
* |
37345
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
521 |
* <p>The {@code index} is defined to be out-of-bounds if any of the |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
522 |
* following inequalities is true: |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
523 |
* <ul> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
524 |
* <li>{@code index < 0}</li> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
525 |
* <li>{@code index >= length}</li> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
526 |
* <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
|
527 |
* </ul> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
528 |
* |
37345
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
529 |
* <p>This method behaves as if {@link #checkIndex(int, int, BiFunction)} |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
530 |
* was called with same out-of-bounds arguments and an exception formatter |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
531 |
* argument produced from an invocation of |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
532 |
* {@code outOfBoundsExceptionFormatter(IndexOutOfBounds::new)} (though it may |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
533 |
* be more efficient). |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
534 |
* |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
535 |
* @param index the index |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
536 |
* @param length the upper-bound (exclusive) of the range |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
537 |
* @return {@code index} if it is within bounds of the range |
37345
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
538 |
* @throws IndexOutOfBoundsException if the {@code index} is out-of-bounds |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
539 |
* @since 9 |
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 |
public static |
37345
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
542 |
int checkIndex(int index, int length) { |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
543 |
return checkIndex(index, length, null); |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
544 |
} |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
545 |
|
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
546 |
/** |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
547 |
* 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
|
548 |
* {@code 0} (inclusive) to {@code length} (exclusive). |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
549 |
* |
37345
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
550 |
* <p>The {@code index} is defined to be out-of-bounds if any of the |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
551 |
* following inequalities is true: |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
552 |
* <ul> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
553 |
* <li>{@code index < 0}</li> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
554 |
* <li>{@code index >= length}</li> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
555 |
* <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
|
556 |
* </ul> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
557 |
* |
37345
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
558 |
* <p>If the {@code index} is out-of-bounds, then a runtime exception is |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
559 |
* thrown that is the result of applying the following arguments to the |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
560 |
* exception formatter: the name of this method, {@code checkIndex}; |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
561 |
* and an unmodifiable list integers whose values are, in order, the |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
562 |
* out-of-bounds arguments {@code index} and {@code length}. |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
563 |
* |
37345
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
564 |
* @param <X> the type of runtime exception to throw if the arguments are |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
565 |
* out-of-bounds |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
566 |
* @param index the index |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
567 |
* @param length the upper-bound (exclusive) of the range |
37345
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
568 |
* @param oobef the exception formatter that when applied with this |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
569 |
* method name and out-of-bounds arguments returns a runtime |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
570 |
* exception. If {@code null} or returns {@code null} then, it is as |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
571 |
* if an exception formatter produced from an invocation of |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
572 |
* {@code outOfBoundsExceptionFormatter(IndexOutOfBounds::new)} is used |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
573 |
* instead (though it may be more efficient). |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
574 |
* Exceptions thrown by the formatter are relayed to the caller. |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
575 |
* @return {@code index} if it is within bounds of the range |
37345
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
576 |
* @throws X if the {@code index} is out-of-bounds and the exception |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
577 |
* formatter is non-{@code null} |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
578 |
* @throws IndexOutOfBoundsException if the {@code index} is out-of-bounds |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
579 |
* and the exception formatter is {@code null} |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
580 |
* @since 9 |
34358
7dfab3d8f8aa
8042997: Make intrinsic some or all check index/range methods
roland
parents:
33277
diff
changeset
|
581 |
* |
7dfab3d8f8aa
8042997: Make intrinsic some or all check index/range methods
roland
parents:
33277
diff
changeset
|
582 |
* @implNote |
37345
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
583 |
* This method is made intrinsic in optimizing compilers to guide them to |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
584 |
* perform unsigned comparisons of the index and length when it is known the |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
585 |
* length is a non-negative value (such as that of an array length or from |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
586 |
* the upper bound of a loop) |
34358
7dfab3d8f8aa
8042997: Make intrinsic some or all check index/range methods
roland
parents:
33277
diff
changeset
|
587 |
*/ |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
588 |
@HotSpotIntrinsicCandidate |
37345
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
589 |
public static <X extends RuntimeException> |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
590 |
int checkIndex(int index, int length, |
37345
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
591 |
BiFunction<String, List<Integer>, X> oobef) { |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
592 |
if (index < 0 || index >= length) |
37345
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
593 |
throw outOfBoundsCheckIndex(oobef, index, length); |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
594 |
return index; |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
595 |
} |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
596 |
|
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
597 |
/** |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
598 |
* 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
|
599 |
* {@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
|
600 |
* (inclusive) to {@code length} (exclusive). |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
601 |
* |
37345
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
602 |
* <p>The sub-range is defined to be out-of-bounds if any of the following |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
603 |
* inequalities is true: |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
604 |
* <ul> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
605 |
* <li>{@code fromIndex < 0}</li> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
606 |
* <li>{@code fromIndex > toIndex}</li> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
607 |
* <li>{@code toIndex > length}</li> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
608 |
* <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
|
609 |
* </ul> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
610 |
* |
37345
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
611 |
* <p>This method behaves as if {@link #checkFromToIndex(int, int, int, BiFunction)} |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
612 |
* was called with same out-of-bounds arguments and an exception formatter |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
613 |
* argument produced from an invocation of |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
614 |
* {@code outOfBoundsExceptionFormatter(IndexOutOfBounds::new)} (though it may |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
615 |
* be more efficient). |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
616 |
* |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
617 |
* @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
|
618 |
* @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
|
619 |
* @param length the upper-bound (exclusive) the range |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
620 |
* @return {@code fromIndex} if the sub-range within bounds of the range |
37345
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
621 |
* @throws IndexOutOfBoundsException if the sub-range is out-of-bounds |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
622 |
* @since 9 |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
623 |
*/ |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
624 |
public static |
37345
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
625 |
int checkFromToIndex(int fromIndex, int toIndex, int length) { |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
626 |
return checkFromToIndex(fromIndex, toIndex, length, null); |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
627 |
} |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
628 |
|
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
629 |
/** |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
630 |
* 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
|
631 |
* {@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
|
632 |
* (inclusive) to {@code length} (exclusive). |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
633 |
* |
37345
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
634 |
* <p>The sub-range is defined to be out-of-bounds if any of the following |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
635 |
* inequalities is true: |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
636 |
* <ul> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
637 |
* <li>{@code fromIndex < 0}</li> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
638 |
* <li>{@code fromIndex > toIndex}</li> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
639 |
* <li>{@code toIndex > length}</li> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
640 |
* <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
|
641 |
* </ul> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
642 |
* |
37345
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
643 |
* <p>If the sub-range is out-of-bounds, then a runtime exception is |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
644 |
* thrown that is the result of applying the following arguments to the |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
645 |
* exception formatter: the name of this method, {@code checkFromToIndex}; |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
646 |
* and an unmodifiable list integers whose values are, in order, the |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
647 |
* out-of-bounds arguments {@code fromIndex}, {@code toIndex}, and {@code length}. |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
648 |
* |
37345
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
649 |
* @param <X> the type of runtime exception to throw if the arguments are |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
650 |
* out-of-bounds |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
651 |
* @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
|
652 |
* @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
|
653 |
* @param length the upper-bound (exclusive) the range |
37345
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
654 |
* @param oobef the exception formatter that when applied with this |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
655 |
* method name and out-of-bounds arguments returns a runtime |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
656 |
* exception. If {@code null} or returns {@code null} then, it is as |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
657 |
* if an exception formatter produced from an invocation of |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
658 |
* {@code outOfBoundsExceptionFormatter(IndexOutOfBounds::new)} is used |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
659 |
* instead (though it may be more efficient). |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
660 |
* Exceptions thrown by the formatter are relayed to the caller. |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
661 |
* @return {@code fromIndex} if the sub-range within bounds of the range |
37345
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
662 |
* @throws X if the sub-range is out-of-bounds and the exception factory |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
663 |
* function is non-{@code null} |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
664 |
* @throws IndexOutOfBoundsException if the sub-range is out-of-bounds and |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
665 |
* the exception factory function is {@code null} |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
666 |
* @since 9 |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
667 |
*/ |
37345
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
668 |
public static <X extends RuntimeException> |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
669 |
int checkFromToIndex(int fromIndex, int toIndex, int length, |
37345
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
670 |
BiFunction<String, List<Integer>, X> oobef) { |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
671 |
if (fromIndex < 0 || fromIndex > toIndex || toIndex > length) |
37345
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
672 |
throw outOfBoundsCheckFromToIndex(oobef, fromIndex, toIndex, length); |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
673 |
return fromIndex; |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
674 |
} |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
675 |
|
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
676 |
/** |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
677 |
* 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
|
678 |
* {@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
|
679 |
* {@code 0} (inclusive) to {@code length} (exclusive). |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
680 |
* |
37345
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
681 |
* <p>The sub-range is defined to be out-of-bounds if any of the following |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
682 |
* inequalities is true: |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
683 |
* <ul> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
684 |
* <li>{@code fromIndex < 0}</li> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
685 |
* <li>{@code size < 0}</li> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
686 |
* <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
|
687 |
* <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
|
688 |
* </ul> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
689 |
* |
37345
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
690 |
* <p>This method behaves as if {@link #checkFromIndexSize(int, int, int, BiFunction)} |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
691 |
* was called with same out-of-bounds arguments and an exception formatter |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
692 |
* argument produced from an invocation of |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
693 |
* {@code outOfBoundsExceptionFormatter(IndexOutOfBounds::new)} (though it may |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
694 |
* be more efficient). |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
695 |
* |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
696 |
* @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
|
697 |
* @param size the size of the sub-range |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
698 |
* @param length the upper-bound (exclusive) of the range |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
699 |
* @return {@code fromIndex} if the sub-range within bounds of the range |
37345
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
700 |
* @throws IndexOutOfBoundsException if the sub-range is out-of-bounds |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
701 |
* @since 9 |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
702 |
*/ |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
703 |
public static |
37345
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
704 |
int checkFromIndexSize(int fromIndex, int size, int length) { |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
705 |
return checkFromIndexSize(fromIndex, size, length, null); |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
706 |
} |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
707 |
|
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
708 |
/** |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
709 |
* 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
|
710 |
* {@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
|
711 |
* {@code 0} (inclusive) to {@code length} (exclusive). |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
712 |
* |
37345
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
713 |
* <p>The sub-range is defined to be out-of-bounds if any of the following |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
714 |
* inequalities is true: |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
715 |
* <ul> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
716 |
* <li>{@code fromIndex < 0}</li> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
717 |
* <li>{@code size < 0}</li> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
718 |
* <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
|
719 |
* <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
|
720 |
* </ul> |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
721 |
* |
37345
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
722 |
* <p>If the sub-range is out-of-bounds, then a runtime exception is |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
723 |
* thrown that is the result of applying the following arguments to the |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
724 |
* exception formatter: the name of this method, {@code checkFromIndexSize}; |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
725 |
* and an unmodifiable list integers whose values are, in order, the |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
726 |
* out-of-bounds arguments {@code fromIndex}, {@code size}, and |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
727 |
* {@code length}. |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
728 |
* |
37345
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
729 |
* @param <X> the type of runtime exception to throw if the arguments are |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
730 |
* out-of-bounds |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
731 |
* @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
|
732 |
* @param size the size of the sub-range |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
733 |
* @param length the upper-bound (exclusive) of the range |
37345
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
734 |
* @param oobef the exception formatter that when applied with this |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
735 |
* method name and out-of-bounds arguments returns a runtime |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
736 |
* exception. If {@code null} or returns {@code null} then, it is as |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
737 |
* if an exception formatter produced from an invocation of |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
738 |
* {@code outOfBoundsExceptionFormatter(IndexOutOfBounds::new)} is used |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
739 |
* instead (though it may be more efficient). |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
740 |
* Exceptions thrown by the formatter are relayed to the caller. |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
741 |
* @return {@code fromIndex} if the sub-range within bounds of the range |
37345
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
742 |
* @throws X if the sub-range is out-of-bounds and the exception factory |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
743 |
* function is non-{@code null} |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
744 |
* @throws IndexOutOfBoundsException if the sub-range is out-of-bounds and |
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
745 |
* the exception factory function is {@code null} |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
746 |
* @since 9 |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
747 |
*/ |
37345
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
748 |
public static <X extends RuntimeException> |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
749 |
int checkFromIndexSize(int fromIndex, int size, int length, |
37345
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
750 |
BiFunction<String, List<Integer>, X> oobef) { |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
751 |
if ((length | fromIndex | size) < 0 || size > length - fromIndex) |
37345
9cb6e1141bdb
8146458: Improve exception reporting for Objects.checkIndex/checkFromToIndex/checkFromIndexSize
psandoz
parents:
34360
diff
changeset
|
752 |
throw outOfBoundsCheckFromIndexSize(oobef, fromIndex, size, length); |
32929
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
753 |
return fromIndex; |
7e1bb9268b8a
8135248: Add utility methods to check indexes and ranges
psandoz
parents:
25859
diff
changeset
|
754 |
} |
4038
ea7aa63169db
6797535: Add shared two argument static equals method to the platform
darcy
parents:
diff
changeset
|
755 |
} |