001: /*
002: * Primitive Collections for Java.
003: * Copyright (C) 2002, 2003 Søren Bak
004: *
005: * This library is free software; you can redistribute it and/or
006: * modify it under the terms of the GNU Lesser General Public
007: * License as published by the Free Software Foundation; either
008: * version 2.1 of the License, or (at your option) any later version.
009: *
010: * This library is distributed in the hope that it will be useful,
011: * but WITHOUT ANY WARRANTY; without even the implied warranty of
012: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
013: * Lesser General Public License for more details.
014: *
015: * You should have received a copy of the GNU Lesser General Public
016: * License along with this library; if not, write to the Free Software
017: * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
018: */
019: package bak.pcj.map;
020:
021: import bak.pcj.DoubleCollection;
022: import bak.pcj.set.LongSet;
023:
024: /**
025: * This interface represents maps from long values to double values.
026: * It is not possible to obtain a set of entries from primitive
027: * collections maps. Instead, an iterator over entries can be
028: * obtained. This removes a number of implementation constraints
029: * imposed by having to implement an entry interface.
030: *
031: * @see bak.pcj.map.LongKeyDoubleMapIterator
032: * @see java.util.Map
033: *
034: * @author Søren Bak
035: * @version 1.1 2003/6/1
036: * @since 1.0
037: */
038: public interface LongKeyDoubleMap {
039:
040: /**
041: * Clears this map.
042: *
043: * @throws UnsupportedOperationException
044: * if the operation is not supported by this map.
045: */
046: void clear();
047:
048: /**
049: * Indicates whether this map contains a mapping from a specified
050: * key. If the key is contained in this map, a succeeding call
051: * to {@link #lget() lget()} will return the corresponding value.
052: *
053: * @param key
054: * the key to test for.
055: *
056: * @return <tt>true</tt> if this map contains a mapping from
057: * the specified key; returns <tt>false</tt>
058: * otherwise.
059: *
060: * @see #lget()
061: */
062: boolean containsKey(long key);
063:
064: /**
065: * Indicates whether this map contains a mapping to a specified
066: * value.
067: *
068: * @param value
069: * the value to test for.
070: *
071: * @return <tt>true</tt> if this map contains at least one
072: * mapping to the specified value; returns
073: * <tt>false</tt> otherwise.
074: */
075: boolean containsValue(double value);
076:
077: /**
078: * Returns an iterator over the entries of this map. It is
079: * possible to remove entries from this map using the iterator
080: * provided that the concrete map supports removal of
081: * entries.
082: *
083: * @return an iterator over the entries of this map.
084: */
085: LongKeyDoubleMapIterator entries();
086:
087: /**
088: * Indicates whether this map is equal to some object.
089: *
090: * @param obj
091: * the object with which to compare this map.
092: *
093: * @return <tt>true</tt> if this map is equal to the
094: * specified object; returns <tt>false</tt>
095: * otherwise.
096: */
097: boolean equals(Object obj);
098:
099: /**
100: * Maps a specified key to a value. Returns a default value as
101: * specified by the <tt>MapDefaults</tt> class if no mapping
102: * exists for the specified key.
103: *
104: * @param key
105: * the key to map to a value.
106: *
107: * @return the value that the specified key maps to, or
108: * a default value, if no such mapping exists.
109: *
110: * @see MapDefaults
111: * @see #tget(long)
112: * @see #lget()
113: */
114: double get(long key);
115:
116: /**
117: * Returns a hash code value for this map.
118: *
119: * @return a hash code value for this map.
120: */
121: int hashCode();
122:
123: /**
124: * Indicates whether this map is empty.
125: *
126: * @return <tt>true</tt> if this map is empty; returns
127: * <tt>false</tt> otherwise.
128: */
129: boolean isEmpty();
130:
131: /**
132: * Returns a set view of the keys of this map. Removals from the
133: * returned set removes the corresponding entries in this map.
134: * Changes to the map are reflected in the set.
135: *
136: * @return a set view of the keys of this map.
137: */
138: LongSet keySet();
139:
140: /**
141: * Returns the last value corresponding to a positive result
142: * from {@link #containsKey(long) containsKey(long)}. This is useful
143: * for checking checking the existence of a mapping while
144: * avoiding two lookups on the same key.
145: *
146: * @return the value corresponding to the key from the
147: * last invokation of
148: * {@link #containsKey(long) containsKey(long)}.
149: *
150: * @throws IllegalStateException
151: * if {@link #containsKey(long) containsKey(long)} has
152: * not been called or the last call resulted in
153: * a return value of <tt>false</tt>.
154: *
155: * @see #get(long)
156: * @see #tget(long)
157: * @see #containsKey(long)
158: */
159: double lget();
160:
161: /**
162: * Adds a mapping from a specified key to a specified value to
163: * this map. If a mapping already exists for the specified key
164: * it is overwritten by the new mapping.
165: *
166: * @param key
167: * the key of the mapping to add to this map.
168: *
169: * @param value
170: * the value of the mapping to add to this map.
171: *
172: * @return the old value if a
173: * mapping from the specified key already existed
174: * in this map; otherwise returns a default value as
175: * specified by the <tt>MapDefaults</tt> class.
176: *
177: * @throws UnsupportedOperationException
178: * if the operation is not supported by this map.
179: *
180: * @see MapDefaults
181: */
182: double put(long key, double value);
183:
184: /**
185: * Adds all mappings from a specified map to this map. Any
186: * existing mappings whose keys collide with a new mapping is
187: * overwritten by the new mapping.
188: *
189: * @param map
190: * the map whose mappings to add to this map.
191: *
192: * @throws NullPointerException
193: * if <tt>map</tt> is <tt>null</tt>.
194: *
195: * @throws UnsupportedOperationException
196: * if the operation is not supported by this map.
197: */
198: void putAll(LongKeyDoubleMap map);
199:
200: /**
201: * Removes the mapping from a specified key from this map.
202: *
203: * @param key
204: * the key whose mapping to remove from this map.
205: *
206: * @return the old value if a
207: * mapping from the specified key already existed
208: * in this map; otherwise returns a default value as
209: * specified by the <tt>MapDefaults</tt> class.
210: *
211: * @throws UnsupportedOperationException
212: * if the operation is not supported by this map.
213: *
214: * @see MapDefaults
215: */
216: double remove(long key);
217:
218: /**
219: * Returns the size of this map. The size is defined as the
220: * number of mappings from keys to values.
221: *
222: * @return the size of this map.
223: */
224: int size();
225:
226: /**
227: * Maps a specified key to a value. This method should be used
228: * when the key is known to be in the map.
229: *
230: * @param key
231: * the key to map to a value.
232: *
233: * @return the value that the specified key maps to.
234: *
235: * @throws NoSuchMappingException
236: * if the specified key does not map to any value.
237: *
238: * @see #get(long)
239: * @see #lget()
240: */
241: double tget(long key);
242:
243: /**
244: * Minimizes the memory used by this map. The exact
245: * operation of this method depends on the class implementing it.
246: * Implementors may choose to ignore it completely.
247: */
248: void trimToSize();
249:
250: /**
251: * Returns a collection view of the values in this map. The
252: * collection is not modifiable, but changes to the map are
253: * reflected in the collection.
254: *
255: * @return a collection view of the values in this map.
256: */
257: DoubleCollection values();
258:
259: }
|