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.collections4.iterators;
19
20 import java.util.ArrayList;
21 import java.util.Collection;
22 import java.util.HashSet;
23 import java.util.Iterator;
24 import java.util.List;
25 import java.util.Set;
26 import java.util.function.Supplier;
27
28 /**
29 * Extends {@link Iterator} with additional default methods.
30 *
31 * @param <E> the type of elements returned by this iterator.
32 * @since 4.5.0-M3
33 */
34 public interface IteratorOperations<E> extends Iterator<E> {
35
36 /**
37 * Adds the remaining elements in the iterator to an arbitrary {@link Collection}. This method consumes the iterator.
38 *
39 * @param collection The target collection to add elements to.
40 * @return the given {@code collection}.
41 * @param <C> A collection of objects of type {@code <E>}.
42 */
43 default <C extends Collection<E>> C addTo(final C collection) {
44 forEachRemaining(collection::add);
45 return collection;
46 }
47
48 /**
49 * Returns the next item and removes it from the iterator.
50 *
51 * @return the next item from the iterator.
52 */
53 default E removeNext() {
54 final E result = next();
55 remove();
56 return result;
57 }
58
59 /**
60 * Adds the remaining elements in the iterator to a new {@link Collection} provided by the supplier. This method consumes the iterator.
61 *
62 * @param collectionSupplier supplies a collection target.
63 * @param <C> the collection type.
64 * @return a new Collection containing the remaining elements of this instance.
65 */
66 default <C extends Collection<E>> C toCollection(final Supplier<C> collectionSupplier) {
67 return addTo(collectionSupplier.get());
68 }
69
70 /**
71 * Adds the remaining elements in the iterator to a new {@link List}. This method consumes the iterator.
72 *
73 * @return a new List containing the remaining elements of this instance.
74 */
75 default List<E> toList() {
76 return toCollection(ArrayList::new);
77 }
78
79 /**
80 * Adds the remaining elements in the iterator to a new {@link Set}. This method consumes the iterator.
81 *
82 * @return a new Set containing the remaining elements of this instance.
83 */
84 default Set<E> toSet() {
85 return toCollection(HashSet::new);
86 }
87
88 }