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 package org.apache.commons.collections.iterators;
18
19 import java.util.List;
20 import java.util.ListIterator;
21
22 import org.apache.commons.collections.ResettableListIterator;
23
24 /**
25 * Iterates backwards through a List, starting with the last element
26 * and continuing to the first. This is useful for looping around
27 * a list in reverse order without needing to actually reverse the list.
28 * <p>
29 * The first call to <code>next()</code> will return the last element
30 * from the list, and so on. The <code>hasNext()</code> method works
31 * in concert with the <code>next()</code> method as expected.
32 * However, the <code>nextIndex()</code> method returns the correct
33 * index in the list, thus it starts high and reduces as the iteration
34 * continues. The previous methods work similarly.
35 *
36 * @since 3.2
37 * @version $Id: ReverseListIterator.java 1429905 2013-01-07 17:15:14Z ggregory $
38 */
39 public class ReverseListIterator<E> implements ResettableListIterator<E> {
40
41 /** The list being wrapped. */
42 private final List<E> list;
43 /** The list iterator being wrapped. */
44 private ListIterator<E> iterator;
45 /** Flag to indicate if updating is possible at the moment. */
46 private boolean validForUpdate = true;
47
48 /**
49 * Constructor that wraps a list.
50 *
51 * @param list the list to create a reversed iterator for
52 * @throws NullPointerException if the list is null
53 */
54 public ReverseListIterator(final List<E> list) {
55 super();
56 this.list = list;
57 iterator = list.listIterator(list.size());
58 }
59
60 //-----------------------------------------------------------------------
61 /**
62 * Checks whether there is another element.
63 *
64 * @return true if there is another element
65 */
66 public boolean hasNext() {
67 return iterator.hasPrevious();
68 }
69
70 /**
71 * Gets the next element.
72 * The next element is the previous in the list.
73 *
74 * @return the next element in the iterator
75 */
76 public E next() {
77 final E obj = iterator.previous();
78 validForUpdate = true;
79 return obj;
80 }
81
82 /**
83 * Gets the index of the next element.
84 *
85 * @return the index of the next element in the iterator
86 */
87 public int nextIndex() {
88 return iterator.previousIndex();
89 }
90
91 /**
92 * Checks whether there is a previous element.
93 *
94 * @return true if there is a previous element
95 */
96 public boolean hasPrevious() {
97 return iterator.hasNext();
98 }
99
100 /**
101 * Gets the previous element.
102 * The next element is the previous in the list.
103 *
104 * @return the previous element in the iterator
105 */
106 public E previous() {
107 final E obj = iterator.next();
108 validForUpdate = true;
109 return obj;
110 }
111
112 /**
113 * Gets the index of the previous element.
114 *
115 * @return the index of the previous element in the iterator
116 */
117 public int previousIndex() {
118 return iterator.nextIndex();
119 }
120
121 /**
122 * Removes the last returned element.
123 *
124 * @throws UnsupportedOperationException if the list is unmodifiable
125 * @throws IllegalStateException if there is no element to remove
126 */
127 public void remove() {
128 if (validForUpdate == false) {
129 throw new IllegalStateException("Cannot remove from list until next() or previous() called");
130 }
131 iterator.remove();
132 }
133
134 /**
135 * Replaces the last returned element.
136 *
137 * @param obj the object to set
138 * @throws UnsupportedOperationException if the list is unmodifiable
139 * @throws IllegalStateException if the iterator is not in a valid state for set
140 */
141 public void set(final E obj) {
142 if (validForUpdate == false) {
143 throw new IllegalStateException("Cannot set to list until next() or previous() called");
144 }
145 iterator.set(obj);
146 }
147
148 /**
149 * Adds a new element to the list between the next and previous elements.
150 *
151 * @param obj the object to add
152 * @throws UnsupportedOperationException if the list is unmodifiable
153 * @throws IllegalStateException if the iterator is not in a valid state for set
154 */
155 public void add(final E obj) {
156 // the validForUpdate flag is needed as the necessary previous()
157 // method call re-enables remove and add
158 if (validForUpdate == false) {
159 throw new IllegalStateException("Cannot add to list until next() or previous() called");
160 }
161 validForUpdate = false;
162 iterator.add(obj);
163 iterator.previous();
164 }
165
166 /**
167 * Resets the iterator back to the start (which is the
168 * end of the list as this is a reversed iterator)
169 */
170 public void reset() {
171 iterator = list.listIterator(list.size());
172 }
173
174 }