1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
|
/*
* Copyright (C) 2002-2024 Sebastiano Vigna
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package PACKAGE;
import java.util.Spliterator;
#if KEYS_PRIMITIVE
import java.util.function.Consumer;
#endif
/** A type-specific {@link Spliterator}; provides an additional methods to avoid (un)boxing, and
* the possibility to skip elements.
*
* @author C. Sean Young <csyoung@google.com>
* @see Spliterator
* @since 8.5.0
*/
#if KEYS_INT_LONG_DOUBLE
public interface KEY_SPLITERATOR KEY_GENERIC extends JDK_PRIMITIVE_SPLITERATOR {
#elif KEYS_PRIMITIVE
public interface KEY_SPLITERATOR KEY_GENERIC extends Spliterator.OfPrimitive<KEY_GENERIC_CLASS, KEY_CONSUMER, KEY_SPLITERATOR KEY_GENERIC> {
#else
public interface KEY_SPLITERATOR KEY_GENERIC extends Spliterator<KEY_GENERIC_CLASS> {
#endif
#if KEYS_PRIMITIVE
// tryAdvance(KEY_CONSUMER action) declaration inherited from super interface.
/** {@inheritDoc}
* @deprecated Please use the corresponding type-specific method instead. */
@Deprecated
@Override
default boolean tryAdvance(final Consumer<? super KEY_GENERIC_CLASS> action) {
// The instanceof and cast is required for performance. Without it, calls routed through this
// overload using a primitive consumer would go through the slow lambda.
return tryAdvance(action instanceof METHOD_ARG_KEY_CONSUMER ? (METHOD_ARG_KEY_CONSUMER)action : (METHOD_ARG_KEY_CONSUMER) action::accept);
}
#if KEYS_INT_LONG_DOUBLE
// Because our primitive Consumer interface extends both the JDK's primitive
// and object Consumer interfaces, calling this method with it would be ambiguous.
// This overload exists to pass it to the proper primitive overload.
/**
* Attempts to perform the action on the next element, or do nothing
* but return {@code false} if there are no remaining elements.
*
* <p><b>WARNING</b>: Overriding this method is almost always a mistake, as this
* overload only exists to disambiguate. Instead, override the {@code tryAdvance()} overload
* that uses the JDK's primitive consumer type (e.g., {@link java.util.function.IntConsumer}).
*
* <br>If Java supported final default methods, this would be one, but sadly it does not.
*
* <p>If you checked and are overriding the version with {@code java.util.function.XConsumer}, and
* still see this warning, then your IDE is incorrectly conflating this method with the proper
* method to override, and you can safely ignore this message.
*
* @param action the action to be performed on the next element.
* @return whether there was a next element the action was performed on
* @see java.util.Spliterator#tryAdvance(java.util.function.Consumer)
*/
default boolean tryAdvance(final KEY_CONSUMER action) {
return tryAdvance((JDK_PRIMITIVE_KEY_CONSUMER) action);
}
#endif
// forEachRemaining(KEY_CONSUMER action) default impl inherited from super interface.
/** {@inheritDoc}
* @deprecated Please use the corresponding type-specific method instead. */
@Deprecated
@Override
default void forEachRemaining(final Consumer<? super KEY_GENERIC_CLASS> action) {
// The instanceof and cast is required for performance. Without it, calls routed through this
// overload using a primitive consumer would go through the slow lambda.
// This is not just theoretical; Oracle's Stream implementation (Pipeline) routes primitive
// consumer calls through this overload, and the difference in performance is an order
// of magnitude.
forEachRemaining(action instanceof METHOD_ARG_KEY_CONSUMER ? (METHOD_ARG_KEY_CONSUMER)action : (METHOD_ARG_KEY_CONSUMER) action::accept);
}
#endif
#if KEYS_INT_LONG_DOUBLE
// Because our primitive Consumer interface extends both the JDK's primitive
// and object Consumer interfaces, calling this method with it would be ambiguous.
// This overload exists to pass it to the proper primitive overload.
/**
* Performs the given action for each remaining element until all elements
* have been processed or the action throws an exception.
*
* <p><b>WARNING</b>: Overriding this method is almost always a mistake, as this
* overload only exists to disambiguate. Instead, override the {@code forEachRemaining()} overload
* that uses the JDK's primitive consumer type (e.g. {@link java.util.function.IntConsumer}).
*
* <p>If Java supported final default methods, this would be one, but sadly it does not.
*
* <p>If you checked and are overriding the version with {@code java.util.function.XConsumer}, and
* still see this warning, then your IDE is incorrectly conflating this method with the proper
* method to override, and you can safely ignore this message.
*
* @param action the action to be performed for each element.
* @see java.util.Spliterator#forEachRemaining(java.util.function.Consumer)
*/
default void forEachRemaining(final KEY_CONSUMER action) {
forEachRemaining((JDK_PRIMITIVE_KEY_CONSUMER) action);
}
#endif
/** Skips the given number of elements.
*
* <p>The effect of this call is exactly the same as that of calling {@link #tryAdvance} for
* {@code n} times (possibly stopping if {@link #tryAdvance} returns false).
* The action called will do nothing; elements will be discarded.
*
* @implSpec This default implementation is linear in n. It is expected concrete implementations
* that are capable of it will override it to run lower time, but be prepared for linear time.
*
* @param n the number of elements to skip.
* @return the number of elements actually skipped.
* @see Spliterator#tryAdvance
*/
default long skip(final long n) {
if (n < 0) throw new IllegalArgumentException("Argument must be nonnegative: " + n);
long i = n;
while(i-- != 0 && tryAdvance((KEY_GENERIC_TYPE unused) -> {})) {} // No loop body; logic all happens in conditional
return n - i - 1;
}
/**
* {@inheritDoc}
*
* @apiNote Note that this specification strengthens the one given in {@link Spliterator#trySplit()}.
*/
@Override
KEY_SPLITERATOR KEY_GENERIC trySplit();
#if KEYS_PRIMITIVE
/**
* {@inheritDoc}
*
* @apiNote Note that this specification strengthens the one given in {@link Spliterator#getComparator()}.
*/
@Override
default KEY_COMPARATOR KEY_SUPER_GENERIC getComparator() {
throw new IllegalStateException();
}
#endif
}
|
