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 * https://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.Iterator;
21 import java.util.Objects;
22
23 import org.apache.commons.collections4.Transformer;
24
25 /**
26 * Decorates an iterator such that each element returned is transformed.
27 *
28 * @param <I> The type of the input to the function.
29 * @param <O> The type of the result of the function.
30 * @since 1.0
31 */
32 public class TransformIterator<I, O> implements Iterator<O> {
33
34 /** The iterator being used */
35 private Iterator<? extends I> iterator;
36 /** The transformer being used */
37 private Transformer<? super I, ? extends O> transformer;
38
39 /**
40 * Constructs a new {@code TransformIterator} that will not function until the {@link #setIterator(Iterator) setIterator} and
41 * {@link #setTransformer(Transformer)} methods are invoked.
42 */
43 public TransformIterator() {
44 }
45
46 /**
47 * Constructs a new {@code TransformIterator} that won't transform elements from the given iterator.
48 *
49 * @param iterator The iterator to use.
50 */
51 public TransformIterator(final Iterator<? extends I> iterator) {
52 this(iterator, null);
53 }
54
55 /**
56 * Constructs a new {@code TransformIterator} that will use the given iterator and transformer. If the given transformer is null, then objects will not be
57 * transformed.
58 *
59 * @param iterator The iterator to use, may not be null.
60 * @param transformer The transformer to use, may be null to pass elements through unchanged
61 */
62 public TransformIterator(final Iterator<? extends I> iterator, final Transformer<? super I, ? extends O> transformer) {
63 this.iterator = Objects.requireNonNull(iterator, "iterator");
64 this.transformer = transformer;
65 }
66
67 /**
68 * Gets the iterator this iterator is using.
69 *
70 * @return The iterator.
71 */
72 public Iterator<? extends I> getIterator() {
73 return iterator;
74 }
75
76 /**
77 * Gets the transformer this iterator is using.
78 *
79 * @return The transformer, may be null.
80 */
81 public Transformer<? super I, ? extends O> getTransformer() {
82 return transformer;
83 }
84
85 @Override
86 public boolean hasNext() {
87 return iterator.hasNext();
88 }
89
90 /**
91 * Gets the next object from the iteration, transforming it using the current transformer. If the transformer is null, no transformation occurs and the
92 * object from the iterator is returned directly.
93 *
94 * @return The next object.
95 * @throws java.util.NoSuchElementException if there are no more elements.
96 */
97 @Override
98 public O next() {
99 return transform(iterator.next());
100 }
101
102 @Override
103 public void remove() {
104 iterator.remove();
105 }
106
107 /**
108 * Sets the iterator for this iterator to use. If iteration has started, this effectively resets the iterator.
109 *
110 * @param iterator The iterator to use.
111 */
112 public void setIterator(final Iterator<? extends I> iterator) {
113 this.iterator = iterator;
114 }
115
116 /**
117 * Sets the transformer this the iterator to use. A null transformer is a no-op transformer.
118 *
119 * @param transformer The transformer to use, may be null to pass elements through unchanged.
120 */
121 public void setTransformer(final Transformer<? super I, ? extends O> transformer) {
122 this.transformer = transformer;
123 }
124
125 /**
126 * Transforms the given object using the transformer. If the transformer is null, the original object is returned as-is.
127 *
128 * @param source The object to transform, may be null.
129 * @return The transformed object, the original object the transformer is null.
130 */
131 @SuppressWarnings("unchecked")
132 protected O transform(final I source) {
133 return transformer == null ? (O) source : transformer.apply(source);
134 }
135 }