    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.collections4.iterators;
    019
    020import java.util.ArrayList;
    021import java.util.Collection;
    022import java.util.HashSet;
    023import java.util.Iterator;
    024import java.util.List;
    025import java.util.Set;
    026import java.util.function.Supplier;
    027
    028/**
    029 * Extends {@link Iterator} with additional default methods.
    030 *
    031 * @param <E> the type of elements returned by this iterator.
    032 * @since 4.5.0-M3
    033 */
    034public interface IteratorOperations<E> extends Iterator<E> {
    035
    036    /**
    037     * Adds the remaining elements in the iterator to an arbitrary {@link Collection}. This method consumes the iterator.
    038     *
    039     * @param collection The target collection to add elements to.
    040     * @return the given {@code collection}.
    041     * @param <C> A collection of objects of type {@code <E>}.
    042     */
    043    default <C extends Collection<E>> C addTo(final C collection) {
    044        forEachRemaining(collection::add);
    045        return collection;
    046    }
    047
    048    /**
    049     * Returns the next item and removes it from the iterator.
    050     *
    051     * @return the next item from the iterator.
    052     */
    053    default E removeNext() {
    054        final E result = next();
    055        remove();
    056        return result;
    057    }
    058
    059    /**
    060     * Adds the remaining elements in the iterator to a new {@link Collection} provided by the supplier. This method consumes the iterator.
    061     *
    062     * @param collectionSupplier supplies a collection target.
    063     * @param <C> the collection type.
    064     * @return a new Collection containing the remaining elements of this instance.
    065     */
    066    default <C extends Collection<E>> C toCollection(final Supplier<C> collectionSupplier) {
    067        return addTo(collectionSupplier.get());
    068    }
    069
    070    /**
    071     * Adds the remaining elements in the iterator to a new {@link List}. This method consumes the iterator.
    072     *
    073     * @return a new List containing the remaining elements of this instance.
    074     */
    075    default List<E> toList() {
    076        return toCollection(ArrayList::new);
    077    }
    078
    079    /**
    080     * Adds the remaining elements in the iterator to a new {@link Set}. This method consumes the iterator.
    081     *
    082     * @return a new Set containing the remaining elements of this instance.
    083     */
    084    default Set<E> toSet() {
    085        return toCollection(HashSet::new);
    086    }
    087
    088}