001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018package org.apache.commons.io.function;
019
020import java.io.IOException;
021import java.io.UncheckedIOException;
022import java.util.Iterator;
023import java.util.NoSuchElementException;
024import java.util.Objects;
025import java.util.function.Consumer;
026
027/**
028 * Like {@link Iterator} but throws {@link IOException}.
029 *
030 * @param <E> the type of elements returned by this iterator.
031 * @since 2.12.0
032 */
033public interface IOIterator<E> {
034
035    /**
036     * Adapts the given Iterator as an IOIterator.
037     *
038     * @param <E> the type of the stream elements.
039     * @param iterator The iterator to adapt
040     * @return A new IOIterator
041     */
042    static <E> IOIterator<E> adapt(final Iterator<E> iterator) {
043        return IOIteratorAdapter.adapt(iterator);
044    }
045
046    /**
047     * Creates an {@link Iterator} for this instance that throws {@link UncheckedIOException} instead of
048     * {@link IOException}.
049     *
050     * @return an {@link UncheckedIOException} {@link Iterator}.
051     */
052    default Iterator<E> asIterator() {
053        return new UncheckedIOIterator<>(this);
054    }
055
056    /**
057     * Like {@link Iterator#forEachRemaining(Consumer)}.
058     *
059     * @param action See delegate.
060     * @throws IOException if an I/O error occurs.
061     */
062    default void forEachRemaining(final IOConsumer<? super E> action) throws IOException {
063        Objects.requireNonNull(action);
064        while (hasNext()) {
065            action.accept(next());
066        }
067    }
068
069    /**
070     * Like {@link Iterator#hasNext()}.
071     *
072     * @return See delegate.
073     * @throws IOException if an I/O error occurs.
074     */
075    boolean hasNext() throws IOException;
076
077    /**
078     * Like {@link Iterator#next()}.
079     *
080     * @return See delegate.
081     * @throws IOException if an I/O error occurs.
082     * @throws NoSuchElementException if the iteration has no more elements
083     */
084    E next() throws IOException;
085
086    /**
087     * Like {@link Iterator#remove()}.
088     *
089     * @throws IOException if an I/O error occurs.
090     */
091    @SuppressWarnings("unused")
092    default void remove() throws IOException {
093        unwrap().remove();
094    }
095
096    /**
097     * Unwraps this instance and returns the underlying {@link Iterator}.
098     * <p>
099     * Implementations may not have anything to unwrap and that behavior is undefined for now.
100     * </p>
101     * @return the underlying Iterator.
102     */
103    Iterator<E> unwrap();
104
105}