KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > gnu > trove > TObjectIntIterator


1 ///////////////////////////////////////////////////////////////////////////////
2 // Copyright (c) 2001, Eric D. Friedman All Rights Reserved.
3 //
4 // This library is free software; you can redistribute it and/or
5 // modify it under the terms of the GNU Lesser General Public
6 // License as published by the Free Software Foundation; either
7 // version 2.1 of the License, or (at your option) any later version.
8 //
9 // This library is distributed in the hope that it will be useful,
10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 // GNU General Public License for more details.
13 //
14 // You should have received a copy of the GNU Lesser General Public
15 // License along with this program; if not, write to the Free Software
16 // Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
17 ///////////////////////////////////////////////////////////////////////////////
18
19 package gnu.trove;
20
21 import java.util.ConcurrentModificationException;
22
23 /**
24  * Iterator for maps of type Object and int.
25  *
26  * <p>The iterator semantics for Trove's primitive maps is slightly different
27  * from those defined in <tt>java.util.Iterator</tt>, but still well within
28  * the scope of the pattern, as defined by Gamma, et al.</p>
29  *
30  * <p>This iterator does <b>not</b> implicitly advance to the next entry when
31  * the value at the current position is retrieved. Rather, you must explicitly
32  * ask the iterator to <tt>advance()</tt> and then retrieve either the <tt>key()</tt>,
33  * the <tt>value()</tt> or both. This is done so that you have the option, but not
34  * the obligation, to retrieve keys and/or values as your application requires, and
35  * without introducing wrapper objects that would carry both. As the iteration is
36  * stateful, access to the key/value parts of the current map entry happens in
37  * constant time.</p>
38  *
39  * <p>In practice, the iterator is akin to a "search finger" that you move from
40  * position to position. Read or write operations affect the current entry only and
41  * do not assume responsibility for moving the finger.</p>
42  *
43  * <p>Here are some sample scenarios for this class of iterator:</p>
44  *
45  * <pre>
46  * // accessing keys/values through an iterator:
47  * for (TObjectIntIterator it = map.iterator();
48  * it.hasNext();) {
49  * it.advance();
50  * if (satisfiesCondition(it.key()) {
51  * doSomethingWithValue(it.value());
52  * }
53  * }
54  * </pre>
55  *
56  * <pre>
57  * // modifying values in-place through iteration:
58  * for (TObjectIntIterator it = map.iterator();
59  * it.hasNext();) {
60  * it.advance();
61  * if (satisfiesCondition(it.key()) {
62  * it.setValue(newValueForKey(it.key()));
63  * }
64  * }
65  * </pre>
66  *
67  * <pre>
68  * // deleting entries during iteration:
69  * for (TObjectIntIterator it = map.iterator();
70  * it.hasNext();) {
71  * it.advance();
72  * if (satisfiesCondition(it.key()) {
73  * it.remove();
74  * }
75  * }
76  * </pre>
77  *
78  * <pre>
79  * // faster iteration by avoiding hasNext():
80  * TObjectIntIterator iterator = map.iterator();
81  * for (int i = map.size(); i-- > 0;) {
82  * iterator.advance();
83  * doSomethingWithKeyAndValue(iterator.key(), iterator.value());
84  * }
85  * </pre>
86  *
87  * @author Eric D. Friedman
88  * @version $Id: TObjectIntIterator.java,v 1.3 2005/03/26 17:30:24 ericdf Exp $
89  */
90
91 public class TObjectIntIterator extends TIterator {
92     private final TObjectIntHashMap _map;
93
94     public TObjectIntIterator(TObjectIntHashMap map) {
95     super(map);
96     this._map = map;
97     }
98
99     /**
100      * Returns the index of the next value in the data structure
101      * or a negative value if the iterator is exhausted.
102      *
103      * @return an <code>int</code> value
104      */
105      protected final int nextIndex() {
106      if (_expectedSize != _hash.size()) {
107          throw new ConcurrentModificationException();
108      }
109
110      Object[] set = _map._set;
111      int i = _index;
112      while (i-- > 0 && (set[i] == TObjectHash.FREE || set[i] == TObjectHash.REMOVED)) ;
113      return i;
114      }
115
116     /**
117      * Moves the iterator forward to the next entry in the underlying map.
118      *
119      * @exception NoSuchElementException if the iterator is already exhausted
120      */
121     public void advance() {
122     moveToNextIndex();
123     }
124
125     /**
126      * Provides access to the key of the mapping at the iterator's position.
127      * Note that you must <tt>advance()</tt> the iterator at least once
128      * before invoking this method.
129      *
130      * @return the key of the entry at the iterator's current position.
131      */
132     public Object key() {
133     return _map._set[_index];
134     }
135
136     /**
137      * Provides access to the value of the mapping at the iterator's position.
138      * Note that you must <tt>advance()</tt> the iterator at least once
139      * before invoking this method.
140      *
141      * @return the value of the entry at the iterator's current position.
142      */
143     public int value() {
144     return _map._values[_index];
145     }
146
147     /**
148      * Replace the value of the mapping at the iterator's position with the
149      * specified value. Note that you must <tt>advance()</tt> the iterator at
150      * least once before invoking this method.
151      *
152      * @param val the value to set in the current entry
153      * @return the old value of the entry.
154      */
155     public int setValue(int val) {
156     int old = value();
157     _map._values[_index] = val;
158     return old;
159     }
160 }// TObjectIntIterator
161
Popular Tags