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.primitives;
18
19 /**
20 * A bi-directional iterator over <code>boolean</code> values.
21 *
22 * @see org.apache.commons.collections.primitives.adapters.BooleanListIteratorListIterator
23 * @see org.apache.commons.collections.primitives.adapters.BooleanIteratorBooleanListIterator
24 *
25 * @since Commons Primitives 1.1
26 * @version $Revision: 480460 $ $Date: 2006-11-29 03:14:21 -0500 (Wed, 29 Nov 2006) $
27 */
28 public interface BooleanListIterator extends BooleanIterator {
29 /**
30 * Inserts the specified element into my underlying collection
31 * (optional operation).
32 * The element is inserted immediately before the next element
33 * that would have been returned by {@link #next}, if any,
34 * and immediately after the next element that would have been
35 * returned by {@link #previous}, if any.
36 * <p/>
37 * The new element is inserted immediately before the implied
38 * cursor. A subsequent call to {@link #previous} will return
39 * the added element, a subsequent call to {@link #next} will
40 * be unaffected. This call increases by one the value that
41 * would be returned by a call to {@link #nextIndex} or
42 * {@link #previousIndex}.
43 *
44 * @param element the value to be inserted
45 *
46 * @throws UnsupportedOperationException when this operation is not
47 * supported
48 * @throws IllegalArgumentException if some aspect of the specified element
49 * prevents it from being added
50 */
51 void add(boolean element);
52
53 /**
54 * Returns <code>true</code> iff I have more elements when traversed in
55 * the forward direction. (In other words, returns <code>true</code> iff
56 * a call to {@link #next} will return an element rather than throwing
57 * an exception.
58 *
59 * @return <code>true</code> iff I have more elements when
60 * traversed in the forward direction
61 */
62 boolean hasNext();
63
64 /**
65 * Returns <code>true</code> iff I have more elements when traversed
66 * in the reverse direction. (In other words, returns <code>true</code>
67 * iff a call to {@link #previous} will return an element rather than
68 * throwing an exception.
69 *
70 * @return <code>true</code> iff I have more elements when traversed
71 * in the reverse direction
72 */
73 boolean hasPrevious();
74
75 /**
76 * Returns the next element in me when traversed in the
77 * forward direction.
78 *
79 * @return the next element in me
80 * @throws java.util.NoSuchElementException if there is no next element
81 */
82 boolean next();
83
84 /**
85 * Returns the index of the element that would be returned
86 * by a subsequent call to {@link #next}, or the number
87 * of elements in my iteration if I have no next element.
88 *
89 * @return the index of the next element in me
90 */
91 int nextIndex();
92
93 /**
94 * Returns the next element in me when traversed in the
95 * reverse direction.
96 *
97 * @return the previous element in me
98 * @throws java.util.NoSuchElementException if there is no previous element
99 */
100 boolean previous();
101
102 /**
103 * Returns the index of the element that would be returned
104 * by a subsequent call to {@link #previous}, or
105 * <code>-1</code> if I have no previous element.
106 *
107 * @return the index of the previous element in me
108 */
109 int previousIndex();
110
111 /**
112 * Removes from my underlying collection the last
113 * element returned by {@link #next} or {@link #previous}
114 * (optional operation).
115 *
116 * @throws UnsupportedOperationException if this operation is not
117 * supported
118 * @throws IllegalStateException if neither {@link #next} nor
119 * {@link #previous} has yet been called, or
120 * {@link #remove} or {@link #add} has already been called since
121 * the last call to {@link #next} or {@link #previous}.
122 */
123 void remove();
124
125 /**
126 * Replaces in my underlying collection the last
127 * element returned by {@link #next} or {@link #previous}
128 * with the specified value (optional operation).
129 *
130 * @param element the value to replace the last returned element with
131 * @throws UnsupportedOperationException if this operation is not
132 * supported
133 * @throws IllegalStateException if neither {@link #next} nor
134 * {@link #previous} has yet been called, or
135 * {@link #remove} or {@link #add} has already been called since
136 * the last call to {@link #next} or {@link #previous}.
137 * @throws IllegalArgumentException if some aspect of the specified element
138 * prevents it from being added
139 */
140 void set(boolean element);
141 }