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>char</code> values.
21 *
22 * @see org.apache.commons.collections.primitives.adapters.CharListIteratorListIterator
23 * @see org.apache.commons.collections.primitives.adapters.ListIteratorCharListIterator
24 *
25 * @since Commons Primitives 1.0
26 * @version $Revision: 480460 $ $Date: 2006-11-29 03:14:21 -0500 (Wed, 29 Nov 2006) $
27 *
28 * @author Rodney Waldhoff
29 */
30 public interface CharListIterator extends CharIterator {
31 /**
32 * Inserts the specified element into my underlying collection
33 * (optional operation).
34 * The element is inserted immediately before the next element
35 * that would have been returned by {@link #next}, if any,
36 * and immediately after the next element that would have been
37 * returned by {@link #previous}, if any.
38 * <p/>
39 * The new element is inserted immediately before the implied
40 * cursor. A subsequent call to {@link #previous} will return
41 * the added element, a subsequent call to {@link #next} will
42 * be unaffected. This call increases by one the value that
43 * would be returned by a call to {@link #nextIndex} or
44 * {@link #previousIndex}.
45 *
46 * @param element the value to be inserted
47 *
48 * @throws UnsupportedOperationException when this operation is not
49 * supported
50 * @throws IllegalArgumentException if some aspect of the specified element
51 * prevents it from being added
52 */
53 void add(char element);
54
55 /**
56 * Returns <code>true</code> iff I have more elements
57 * when traversed in the forward direction.
58 * (In other words, returns <code>true</code> iff
59 * a call to {@link #next} will return an element
60 * rather than throwing an exception.
61 *
62 * @return <code>true</code> iff I have more elements when
63 * traversed in the forward direction
64 */
65 boolean hasNext();
66
67 /**
68 * Returns <code>true</code> iff I have more elements
69 * when traversed in the reverse direction.
70 * (In other words, returns <code>true</code> iff
71 * a call to {@link #previous} will return an element
72 * rather than throwing an exception.
73 *
74 * @return <code>true</code> iff I have more elements when
75 * traversed in the reverse direction
76 */
77 boolean hasPrevious();
78
79 /**
80 * Returns the next element in me when traversed in the
81 * forward direction.
82 *
83 * @return the next element in me
84 * @throws java.util.NoSuchElementException if there is no next element
85 */
86 char next();
87
88 /**
89 * Returns the index of the element that would be returned
90 * by a subsequent call to {@link #next}, or the number
91 * of elements in my iteration if I have no next element.
92 *
93 * @return the index of the next element in me
94 */
95 int nextIndex();
96
97 /**
98 * Returns the next element in me when traversed in the
99 * 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 }