KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > gnu > trove > TByteIntIterator


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 /**
22  * Iterator for maps of type byte and int.
23  *
24  * <p>The iterator semantics for Trove's primitive maps is slightly different
25  * from those defined in <tt>java.util.Iterator</tt>, but still well within
26  * the scope of the pattern, as defined by Gamma, et al.</p>
27  *
28  * <p>This iterator does <b>not</b> implicitly advance to the next entry when
29  * the value at the current position is retrieved. Rather, you must explicitly
30  * ask the iterator to <tt>advance()</tt> and then retrieve either the <tt>key()</tt>,
31  * the <tt>value()</tt> or both. This is done so that you have the option, but not
32  * the obligation, to retrieve keys and/or values as your application requires, and
33  * without introducing wrapper objects that would carry both. As the iteration is
34  * stateful, access to the key/value parts of the current map entry happens in
35  * constant time.</p>
36  *
37  * <p>In practice, the iterator is akin to a "search finger" that you move from
38  * position to position. Read or write operations affect the current entry only and
39  * do not assume responsibility for moving the finger.</p>
40  *
41  * <p>Here are some sample scenarios for this class of iterator:</p>
42  *
43  * <pre>
44  * // accessing keys/values through an iterator:
45  * for (TByteIntIterator it = map.iterator();
46  * it.hasNext();) {
47  * it.advance();
48  * if (satisfiesCondition(it.key()) {
49  * doSomethingWithValue(it.value());
50  * }
51  * }
52  * </pre>
53  *
54  * <pre>
55  * // modifying values in-place through iteration:
56  * for (TByteIntIterator it = map.iterator();
57  * it.hasNext();) {
58  * it.advance();
59  * if (satisfiesCondition(it.key()) {
60  * it.setValue(newValueForKey(it.key()));
61  * }
62  * }
63  * </pre>
64  *
65  * <pre>
66  * // deleting entries during iteration:
67  * for (TByteIntIterator it = map.iterator();
68  * it.hasNext();) {
69  * it.advance();
70  * if (satisfiesCondition(it.key()) {
71  * it.remove();
72  * }
73  * }
74  * </pre>
75  *
76  * <pre>
77  * // faster iteration by avoiding hasNext():
78  * TByteIntIterator iterator = map.iterator();
79  * for (int i = map.size(); i-- > 0;) {
80  * iterator.advance();
81  * doSomethingWithKeyAndValue(iterator.key(), iterator.value());
82  * }
83  * </pre>
84  *
85  * @author Eric D. Friedman
86  * @version $Id: TByteIntIterator.java,v 1.2 2005/03/26 17:30:24 ericdf Exp $
87  */
88
89 public class TByteIntIterator extends TPrimitiveIterator {
90     /** the collection being iterated over */
91     private final TByteIntHashMap _map;
92
93     /**
94      * Creates an iterator over the specified map
95      */
96     public TByteIntIterator(TByteIntHashMap map) {
97     super(map);
98     this._map = map;
99     }
100
101     /**
102      * Moves the iterator forward to the next entry in the underlying map.
103      *
104      * @exception NoSuchElementException if the iterator is already exhausted
105      */
106     public void advance() {
107     moveToNextIndex();
108     }
109
110     /**
111      * Provides access to the key of the mapping at the iterator's position.
112      * Note that you must <tt>advance()</tt> the iterator at least once
113      * before invoking this method.
114      *
115      * @return the key of the entry at the iterator's current position.
116      */
117     public byte key() {
118     return _map._set[_index];
119     }
120
121     /**
122      * Provides access to the value of the mapping at the iterator's position.
123      * Note that you must <tt>advance()</tt> the iterator at least once
124      * before invoking this method.
125      *
126      * @return the value of the entry at the iterator's current position.
127      */
128     public int value() {
129     return _map._values[_index];
130     }
131
132     /**
133      * Replace the value of the mapping at the iterator's position with the
134      * specified value. Note that you must <tt>advance()</tt> the iterator at
135      * least once before invoking this method.
136      *
137      * @param val the value to set in the current entry
138      * @return the old value of the entry.
139      */
140     public int setValue(int val) {
141     int old = value();
142     _map._values[_index] = val;
143     return old;
144     }
145 }// TByteIntIterator
146
Popular Tags