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 package org.apache.commons.collections.primitives;
018
019 /**
020 * A bi-directional iterator over <code>boolean</code> values.
021 *
022 * @see org.apache.commons.collections.primitives.adapters.BooleanListIteratorListIterator
023 * @see org.apache.commons.collections.primitives.adapters.BooleanIteratorBooleanListIterator
024 *
025 * @since Commons Primitives 1.1
026 * @version $Revision: 480460 $ $Date: 2006-11-29 09:14:21 +0100 (Wed, 29 Nov 2006) $
027 */
028 public interface BooleanListIterator extends BooleanIterator {
029 /**
030 * Inserts the specified element into my underlying collection
031 * (optional operation).
032 * The element is inserted immediately before the next element
033 * that would have been returned by {@link #next}, if any,
034 * and immediately after the next element that would have been
035 * returned by {@link #previous}, if any.
036 * <p/>
037 * The new element is inserted immediately before the implied
038 * cursor. A subsequent call to {@link #previous} will return
039 * the added element, a subsequent call to {@link #next} will
040 * be unaffected. This call increases by one the value that
041 * would be returned by a call to {@link #nextIndex} or
042 * {@link #previousIndex}.
043 *
044 * @param element the value to be inserted
045 *
046 * @throws UnsupportedOperationException when this operation is not
047 * supported
048 * @throws IllegalArgumentException if some aspect of the specified element
049 * prevents it from being added
050 */
051 void add(boolean element);
052
053 /**
054 * Returns <code>true</code> iff I have more elements when traversed in
055 * the forward direction. (In other words, returns <code>true</code> iff
056 * a call to {@link #next} will return an element rather than throwing
057 * an exception.
058 *
059 * @return <code>true</code> iff I have more elements when
060 * traversed in the forward direction
061 */
062 boolean hasNext();
063
064 /**
065 * Returns <code>true</code> iff I have more elements when traversed
066 * in the reverse direction. (In other words, returns <code>true</code>
067 * iff a call to {@link #previous} will return an element rather than
068 * throwing an exception.
069 *
070 * @return <code>true</code> iff I have more elements when traversed
071 * in the reverse direction
072 */
073 boolean hasPrevious();
074
075 /**
076 * Returns the next element in me when traversed in the
077 * forward direction.
078 *
079 * @return the next element in me
080 * @throws java.util.NoSuchElementException if there is no next element
081 */
082 boolean next();
083
084 /**
085 * Returns the index of the element that would be returned
086 * by a subsequent call to {@link #next}, or the number
087 * of elements in my iteration if I have no next element.
088 *
089 * @return the index of the next element in me
090 */
091 int nextIndex();
092
093 /**
094 * Returns the next element in me when traversed in the
095 * reverse direction.
096 *
097 * @return the previous element in me
098 * @throws java.util.NoSuchElementException if there is no previous element
099 */
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 }