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 }