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 com.uwyn.rife.pcj.map;
020:
021: import com.uwyn.rife.pcj.set.CharSet;
022:
023: /**
024: * This interface represents maps from char values to objects.
025: *
026: * @see java.util.Map
027: *
028: * @author Søren Bak
029: * @version 1.1 2003/6/1
030: * @since 1.0
031: */
032: public interface CharKeyMap<E> {
033:
034: /**
035: * Clears this map.
036: */
037: void clear();
038:
039: /**
040: * Indicates whether this map contains a mapping from a specified
041: * key.
042: *
043: * @param key
044: * the key to test for.
045: *
046: * @return <tt>true</tt> if this map contains a mapping from
047: * the specified key; returns <tt>false</tt>
048: * otherwise.
049: */
050: boolean containsKey(char key);
051:
052: /**
053: * Indicates whether this map contains a mapping to a specified
054: * value.
055: *
056: * @param value
057: * the value to test for.
058: *
059: * @return <tt>true</tt> if this map contains at least one
060: * mapping to the specified value; returns
061: * <tt>false</tt> otherwise.
062: */
063: boolean containsValue(Object value);
064:
065: /**
066: * Returns an iterator over the entries of this map. It is
067: * possible to remove entries from this map using the iterator
068: * provided that the concrete map supports removal of
069: * entries.
070: *
071: * @return an iterator over the entries of this map.
072: */
073: CharKeyMapIterator<E> entries();
074:
075: /**
076: * Indicates whether this map is equal to some object.
077: *
078: * @param obj
079: * the object with which to compare this map.
080: *
081: * @return <tt>true</tt> if this map is equal to the
082: * specified object; returns <tt>false</tt>
083: * otherwise.
084: */
085: boolean equals(Object obj);
086:
087: /**
088: * Maps a specified key to a value.
089: *
090: * @param key
091: * the key to map to a value.
092: *
093: * @return the value that the specified key maps to; returns
094: * <tt>null</tt>, if no mapping exists for the
095: * specified key.
096: */
097: E get(char key);
098:
099: /**
100: * Returns a hash code value for this map.
101: *
102: * @return a hash code value for this map.
103: */
104: int hashCode();
105:
106: /**
107: * Indicates whether this map is empty.
108: *
109: * @return <tt>true</tt> if this map is empty; returns
110: * <tt>false</tt> otherwise.
111: */
112: public boolean isEmpty();
113:
114: /**
115: * Returns a set view of the keys of this map. The set is not
116: * directly modifiable, but changes to the map are reflected in
117: * the set.
118: *
119: * @return a set view of the keys of this map.
120: */
121: CharSet keySet();
122:
123: /**
124: * Adds a mapping from a specified key to a specified value to
125: * this map. If a mapping already exists for the specified key
126: * it is overwritten by the new mapping.
127: *
128: * @param key
129: * the key of the mapping to add to this map.
130: *
131: * @param value
132: * the value of the mapping to add to this map.
133: *
134: * @return the old value (which can be <tt>null</tt>) if a
135: * mapping from the specified key already existed
136: * in this map; returns <tt>null</tt> otherwise.
137: *
138: * @throws UnsupportedOperationException
139: * if the operation is not supported by this map.
140: */
141: E put(char key, E value);
142:
143: /**
144: * Adds all mappings from a specified map to this map. Any
145: * existing mappings whose keys collide with a new mapping is
146: * overwritten by the new mapping.
147: *
148: * @param map
149: * the map whose mappings to add to this map.
150: *
151: * @throws NullPointerException
152: * if <tt>map</tt> is <tt>null</tt>.
153: *
154: * @throws UnsupportedOperationException
155: * if the operation is not supported by this map.
156: */
157: void putAll(CharKeyMap<E> map);
158:
159: /**
160: * Removes the mapping from a specified key from this map.
161: *
162: * @param key
163: * the key whose mapping to remove from this map.
164: *
165: * @return the old value (which can be <tt>null</tt>) if a
166: * mapping from the specified key already existed
167: * in this map; returns <tt>null</tt> otherwise.
168: *
169: * @throws UnsupportedOperationException
170: * if the operation is not supported by this map.
171: */
172: E remove(char key);
173:
174: /**
175: * Returns the size of this map. The size is defined as the
176: * number of mappings from keys to values.
177: *
178: * @return the size of this map.
179: */
180: int size();
181:
182: /**
183: * Returns a collection view of the values in this map. The
184: * collection is not modifiable, but changes to the map are
185: * reflected in the collection.
186: *
187: * @return a collection view of the values in this map.
188: */
189: java.util.Collection values();
190:
191: }
|