1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18 package org.apache.commons.io.function;
19
20 import java.io.IOException;
21 import java.io.UncheckedIOException;
22 import java.util.Objects;
23 import java.util.Spliterator;
24 import java.util.function.Consumer;
25
26 /**
27 * Like {@link Spliterator} but throws {@link IOException}.
28 *
29 * @param <T> the type of elements returned by this IOSpliterator.
30 * @since 2.12.0
31 */
32 public interface IOSpliterator<T> {
33
34 /**
35 * Adapts the given Spliterator as an IOSpliterator.
36 *
37 * @param <E> the type of the stream elements.
38 * @param iterator The iterator to adapt
39 * @return A new IOSpliterator
40 */
41 static <E> IOSpliterator<E> adapt(final Spliterator<E> iterator) {
42 return IOSpliteratorAdapter.adapt(iterator);
43 }
44
45 /**
46 * Constructs a {@link Spliterator} for this instance that throws {@link UncheckedIOException} instead of
47 * {@link IOException}.
48 *
49 * @return an {@link UncheckedIOException} {@link Spliterator}.
50 */
51 default Spliterator<T> asSpliterator() {
52 return new UncheckedIOSpliterator<>(this);
53 }
54
55 /**
56 * Like {@link Spliterator#characteristics()}.
57 *
58 * @return a representation of characteristics
59 */
60 default int characteristics() {
61 return unwrap().characteristics();
62 }
63
64 /**
65 * Like {@link Spliterator#estimateSize()}.
66 *
67 *
68 * @return the estimated size, or {@code Long.MAX_VALUE} if infinite, unknown, or too expensive to compute.
69 */
70 default long estimateSize() {
71 return unwrap().estimateSize();
72 }
73
74 /**
75 * Like {@link Spliterator#forEachRemaining(Consumer)}.
76 *
77 * @param action The action
78 * @throws NullPointerException if the specified action is null
79 */
80 default void forEachRemaining(final IOConsumer<? super T> action) {
81 while (tryAdvance(action)) { // NOPMD
82 }
83 }
84
85 /**
86 * Like {@link Spliterator#getComparator()}.
87 *
88 * @return a Comparator, or {@code null} if the elements are sorted in the natural order.
89 * @throws IllegalStateException if the spliterator does not report a characteristic of {@code SORTED}.
90 */
91 @SuppressWarnings("unchecked")
92 default IOComparator<? super T> getComparator() {
93 return (IOComparator<T>) unwrap().getComparator();
94 }
95
96 /**
97 * Like {@link Spliterator#getExactSizeIfKnown()}.
98 *
99 * @return the exact size, if known, else {@code -1}.
100 */
101 default long getExactSizeIfKnown() {
102 return unwrap().getExactSizeIfKnown();
103 }
104
105 /**
106 * Like {@link Spliterator#hasCharacteristics(int)}.
107 *
108 * @param characteristics the characteristics to check for
109 * @return {@code true} if all the specified characteristics are present, else {@code false}
110 */
111 default boolean hasCharacteristics(final int characteristics) {
112 return unwrap().hasCharacteristics(characteristics);
113 }
114
115 /**
116 * Like {@link Spliterator#tryAdvance(Consumer)}.
117 *
118 * @param action The action
119 * @return {@code false} if no remaining elements existed upon entry to this method, else {@code true}.
120 * @throws NullPointerException if the specified action is null
121 */
122 default boolean tryAdvance(final IOConsumer<? super T> action) {
123 return unwrap().tryAdvance(Objects.requireNonNull(action, "action").asConsumer());
124 }
125
126 /**
127 * Like {@link Spliterator#trySplit()}.
128 *
129 * @return a {@code Spliterator} covering some portion of the elements, or {@code null} if this spliterator cannot be
130 * split
131 */
132 default IOSpliterator<T> trySplit() {
133 return adapt(unwrap().trySplit());
134 }
135
136 /**
137 * Unwraps this instance and returns the underlying {@link Spliterator}.
138 * <p>
139 * Implementations may not have anything to unwrap and that behavior is undefined for now.
140 * </p>
141 *
142 * @return the underlying Spliterator.
143 */
144 Spliterator<T> unwrap();
145
146 }