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
|
/*
* 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.Iterator;
#if KEYS_PRIMITIVE
import java.util.PrimitiveIterator;
#endif
#if KEYS_PRIMITIVE && !KEYS_INT_LONG_DOUBLE
import java.util.Objects;
#endif
#ifdef KEYS_PRIMITIVE
import java.util.function.Consumer;
#endif
/** A type-specific {@link Iterator}; provides an additional method to avoid (un)boxing, and
* the possibility to skip elements.
*
* @see Iterator
*/
#if KEYS_INT_LONG_DOUBLE
public interface KEY_ITERATOR KEY_GENERIC extends JDK_PRIMITIVE_ITERATOR {
#elif KEYS_PRIMITIVE
public interface KEY_ITERATOR KEY_GENERIC extends PrimitiveIterator<KEY_GENERIC_CLASS, KEY_CONSUMER> {
#else
public interface KEY_ITERATOR KEY_GENERIC extends Iterator<KEY_GENERIC_CLASS> {
#endif
#if KEYS_PRIMITIVE
/**
* Returns the next element as a primitive type.
*
* @return the next element in the iteration.
* @see Iterator#next()
*/
#if KEYS_INT_LONG_DOUBLE
@Override
#endif
KEY_TYPE NEXT_KEY();
/** {@inheritDoc}
* @deprecated Please use the corresponding type-specific method instead. */
@Deprecated
@Override
default KEY_CLASS next() {
return KEY_CLASS.valueOf(NEXT_KEY());
}
#if KEYS_INT_LONG_DOUBLE
// We inherit the canonical primitive forEachRemaining overload.
// 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.Iterator#forEachRemaining(java.util.function.Consumer)
* @since 8.5.0
*/
default void forEachRemaining(final KEY_CONSUMER action) {
forEachRemaining((JDK_PRIMITIVE_KEY_CONSUMER) action);
}
#else
/**
* Performs the given action for each remaining element until all elements
* have been processed or the action throws an exception.
*
* @param action the action to be performed for each element.
* @see java.util.Iterator#forEachRemaining(java.util.function.Consumer)
* @since 8.0.0
* @apiNote Implementing classes should generally override this method, and take the default
* implementation of the other overloads which will delegate to this method (after proper
* conversions).
*/
@Override
default void forEachRemaining(final KEY_CONSUMER action) {
Objects.requireNonNull(action);
while (hasNext()) {
action.accept(NEXT_KEY());
}
}
#if !KEY_CLASS_Boolean
/**
* Performs the given action for each remaining element, performing widening primitive casts,
* until all elements have been processed or the action throws an exception.
* @param action the action to be performed for each element.
* @see java.util.Iterator#forEachRemaining(java.util.function.Consumer)
* @since 8.5.0
* @implNote Unless the argument is type-specific, this method will introduce an intermediary
* lambda to perform widening casts. Please use the type-specific overload to avoid this overhead.
*/
default void forEachRemaining(final JDK_PRIMITIVE_KEY_CONSUMER action) {
Objects.requireNonNull(action);
forEachRemaining(action instanceof KEY_CONSUMER ? (KEY_CONSUMER)action : (KEY_CONSUMER)action::accept);
}
#endif
#endif
/** {@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.
forEachRemaining(action instanceof METHOD_ARG_KEY_CONSUMER ? (METHOD_ARG_KEY_CONSUMER)action : (METHOD_ARG_KEY_CONSUMER) action::accept);
}
#endif
/** Skips the given number of elements.
*
* <p>The effect of this call is exactly the same as that of calling {@link #next()} for {@code n} times (possibly stopping if {@link #hasNext()} becomes false).
*
* @param n the number of elements to skip.
* @return the number of elements actually skipped.
* @see Iterator#next()
*/
default int skip(final int n) {
if (n < 0) throw new IllegalArgumentException("Argument must be nonnegative: " + n);
int i = n;
while(i-- != 0 && hasNext()) NEXT_KEY();
return n - i - 1;
}
}
|
