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>char</code> values.
021 *
022 * @see org.apache.commons.collections.primitives.adapters.CharListIteratorListIterator
023 * @see org.apache.commons.collections.primitives.adapters.ListIteratorCharListIterator
024 *
025 * @since Commons Primitives 1.0
026 * @version $Revision: 480460 $ $Date: 2006-11-29 09:14:21 +0100 (Wed, 29 Nov 2006) $
027 *
028 * @author Rodney Waldhoff
029 */
030 public interface CharListIterator extends CharIterator {
031 /**
032 * Inserts the specified element into my underlying collection
033 * (optional operation).
034 * The element is inserted immediately before the next element
035 * that would have been returned by {@link #next}, if any,
036 * and immediately after the next element that would have been
037 * returned by {@link #previous}, if any.
038 * <p/>
039 * The new element is inserted immediately before the implied
040 * cursor. A subsequent call to {@link #previous} will return
041 * the added element, a subsequent call to {@link #next} will
042 * be unaffected. This call increases by one the value that
043 * would be returned by a call to {@link #nextIndex} or
044 * {@link #previousIndex}.
045 *
046 * @param element the value to be inserted
047 *
048 * @throws UnsupportedOperationException when this operation is not
049 * supported
050 * @throws IllegalArgumentException if some aspect of the specified element
051 * prevents it from being added
052 */
053 void add(char element);
054
055 /**
056 * Returns <code>true</code> iff I have more elements
057 * when traversed in the forward direction.
058 * (In other words, returns <code>true</code> iff
059 * a call to {@link #next} will return an element
060 * rather than throwing an exception.
061 *
062 * @return <code>true</code> iff I have more elements when
063 * traversed in the forward direction
064 */
065 boolean hasNext();
066
067 /**
068 * Returns <code>true</code> iff I have more elements
069 * when traversed in the reverse direction.
070 * (In other words, returns <code>true</code> iff
071 * a call to {@link #previous} will return an element
072 * rather than throwing an exception.
073 *
074 * @return <code>true</code> iff I have more elements when
075 * traversed in the reverse direction
076 */
077 boolean hasPrevious();
078
079 /**
080 * Returns the next element in me when traversed in the
081 * forward direction.
082 *
083 * @return the next element in me
084 * @throws java.util.NoSuchElementException if there is no next element
085 */
086 char next();
087
088 /**
089 * Returns the index of the element that would be returned
090 * by a subsequent call to {@link #next}, or the number
091 * of elements in my iteration if I have no next element.
092 *
093 * @return the index of the next element in me
094 */
095 int nextIndex();
096
097 /**
098 * Returns the next element in me when traversed in the
099 * reverse direction.
100 *
101 * @return the previous element in me
102 * @throws java.util.NoSuchElementException if there is no previous element
103 */
104 char previous();
105
106 /**
107 * Returns the index of the element that would be returned
108 * by a subsequent call to {@link #previous}, or
109 * <code>-1</code> if I have no previous element.
110 *
111 * @return the index of the previous element in me
112 */
113 int previousIndex();
114
115 /**
116 * Removes from my underlying collection the last
117 * element returned by {@link #next} or {@link #previous}
118 * (optional operation).
119 *
120 * @throws UnsupportedOperationException if this operation is not
121 * supported
122 * @throws IllegalStateException if neither {@link #next} nor
123 * {@link #previous} has yet been called, or
124 * {@link #remove} or {@link #add} has already been called since
125 * the last call to {@link #next} or {@link #previous}.
126 */
127 void remove();
128
129 /**
130 * Replaces in my underlying collection the last
131 * element returned by {@link #next} or {@link #previous}
132 * with the specified value (optional operation).
133 *
134 * @param element the value to replace the last returned element with
135 * @throws UnsupportedOperationException if this operation is not
136 * supported
137 * @throws IllegalStateException if neither {@link #next} nor
138 * {@link #previous} has yet been called, or
139 * {@link #remove} or {@link #add} has already been called since
140 * the last call to {@link #next} or {@link #previous}.
141 * @throws IllegalArgumentException if some aspect of the specified element
142 * prevents it from being added
143 */
144 void set(char element);
145 }