Coverage Report

Coverage Report - jaggregate.AbstractDictionary

Classes in this File

 /*
  Copyright 2004-2008 Paul R. Holser, Jr.  All rights reserved.
  Licensed under the Academic Free License version 3.0
  */
 
 package jaggregate;
 
 /**
  * Provides protocol for accessing, adding, removing, and iterating over the
  * <dfn>elements</dfn> of an unordered collection whose elements are accessed using
  * an explicitly assigned external <dfn>key</dfn>.
  *
  * @param <K> a restriction on the types of the keys that may be contained in the
  * dictionary
  * @param <V> a restriction on the types of the values that may be contained in the
  * dictionary
  *
  * @author <a href="mailto:pholser@alumni.rice.edu">Paul Holser</a>
  * @version $Id: AbstractDictionary.java,v 1.5 2008/05/08 03:49:37 pholser Exp $
  */
 public interface AbstractDictionary<K, V> extends ExtensibleCollection<Pair<K, V>> {
     /**
      * {@inheritDoc}
      *
      * @return a bag of results
      */
     <R> AbstractBag<R> collect(
         UnaryFunctor<? super Pair<K, V>, ? extends R> transformer );
 
     /**
      * {@inheritDoc}
      *
      * @return a dictionary of rejects
      */
     AbstractDictionary<K, V> reject( UnaryCondition<? super Pair<K, V>> discriminator );
 
     /**
      * {@inheritDoc}
      *
      * @return a dictionary of matches
      */
     AbstractDictionary<K, V> select( UnaryCondition<? super Pair<K, V>> discriminator );
 
     /**
      * Answers the element associated with the given key in this dictionary.
      *
      * @param key the key to look up
      * @return the associated element, or {@code null} if there is no such element
      */
     V at( K key );
 
     /**
      * Answers a new dictionary whose keys are this dictionary's keys, and whose
      * corresponding elements are the results of evaluating the given transformer with
      * each corresponding element of this dictionary.  For each of this dictionary's
      * keys, a new element is obtained by evaluating {@code transformer} with the
      * corresponding element of this dictionary as a parameter.
      * <p/>
      * The elements are traversed in the order specified by {@link
      * #forEachDo(UnaryFunctor) forEachDo} for this dictionary.
      *
      * @param <R> return type of the transformer
      * @param transformer the transformer to evaluate
      * @return the results of evaluating {@code transformer} with the elements of this
      * dictionary
      * @throws NullPointerException if {@code transformer} is {@code null}
      */
     <R> AbstractDictionary<K, R> collectValues(
         UnaryFunctor<? super V, ? extends R> transformer );
 
     /**
      * Answers {@code true} if this dictionary contains an element stored at the given
      * key, else answers {@code false}.
      *
      * @param key the key to lookup
      * @return whether the key is in this dictionary
      */
     boolean includesKey( K key );
 
     /**
      * Answers a key such that the element associated with this key is equivalent to
      * the given value.
      * <p/>
      * Note that if there are multiple elements in this dictionary that are equivalent to
      * the given value, then the one whose key answered is arbitrary.
      *
      * @param value the value to look up
      * @return an associated key, or {@code null} if there is no such key
      */
     K keyAt( V value );
 
     /**
      * Answers a set of keys at which there is an element stored in this dictionary.
      * <p/>
      * The {@linkplain #size() size} of the result is equal to the {@linkplain #size()
      * size} of this dictionary.
      *
      * @return a set of the keys in this dictionary
      */
     AbstractSet<K> keys();
 
     /**
      * Iteratively evaluates the given operation with each of this dictionary's keys and
      * values.
      * <p/>
      * For each of this dictionary's elements, {@code operation} is evaluated with the
      * corresponding key as the first argument and the element as the second argument.
      * <p/>
      * The order in which the elements are visited is not specified.  Each key is visited
      * exactly once.
      *
      * @param operation the operation to perform
      * @throws NullPointerException if {@code operation} is {@code null}
      */
     void keysAndValuesDo( BinaryFunctor<? super K, ? super V, ?> operation );
 
     /**
      * Iteratively evaluates the given operation with each of this dictionary's keys
      * at which there are elements stored.
      * <p/>
      * For each of this dictionary's elements, {@code operation} is evaluated with the
      * corresponding key as the argument.
      * <p/>
      * The order in which the elements are visited is not specified.  Each key is visited
      * exactly once.
      *
      * @param <R> a constraint on the return type of the operation
      * @param operation the operation to perform
      * @throws NullPointerException if {@code operation} is {@code null}
      */
     <R> void keysDo( UnaryFunctor<? super K, ? extends R> operation );
 
     /**
      * Stores the elements of the given dictionary in this dictionary at the
      * corresponding key from the given dictionary.
      * <p/>
      * This message is equivalent to repeatedly performing {@link #putAt(Object,Object)
      * putAt} on this dictionary with each of the keys and elements from {@code newPairs}
      * in turn.  If a key in {@code newPairs} is <dfn>key-equivalent</dfn> to a key in
      * this dictionary, the associated element in {@code newPairs} replaces the element
      * in this dictionary.
      *
      * @param newPairs the pairs to add
      * @throws NullPointerException if {@code newPairs} is {@code null}
      */
     void putAll( AbstractDictionary<? extends K, ? extends V> newPairs );
 
     /**
      * Stores a new element at a given key in this dictionary.
      * <p/>
      * If lookup succeeds for {@code key}, then {@code newElement} replaces the element
      * previously stored at {@code key}.  Otherwise, {@code newElement} is stored at the
      * new {@code key}.  In either case, subsequent successful lookups for {@code key}
      * will answer {@code newElement}.
      *
      * @param key a key
      * @param newElement the new element to associate with {@code key}
      * @return the element previously associated with {@code key}, or {@code null} if
      * there is no such element
      */
     V putAt( K key, V newElement );
 
     /**
      * Answers a new dictionary which excludes the elements in this dictionary that cause
      * the given discriminator to answer {@code true}.
      * <p/>
      * For each of this dictionary's keys, {@code discriminator} is evaluated with the
      * corresponding element as the argument.  If the element causes {@code discriminator}
      * to answer {@code false}, the key is added to the answer with the element as its
      * corresponding value.
      *
      * @param discriminator the discriminator to evaluate
      * @return a dictionary of rejects
      * @throws NullPointerException if {@code discriminator} is {@code null}
      */
     AbstractDictionary<K, V> rejectValues( UnaryCondition<? super V> discriminator );
 
     /**
      * Removes any elements from this dictionary which are stored at any of the given
      * keys.
      * <p/>
      * This message has the same effect as repeatedly performing {@link
      * #removeKey(Object) removeKey} on this dictionary for each element in
      * {@code oldKeys}.
      *
      * @param oldKeys the keys to remove
      * @throws NullPointerException if {@code oldKeys} is {@code null}
      */
     void removeAllKeys( Collection<? extends K> oldKeys );
 
     /**
      * @see #removeAllKeys(Collection)
      * @param oldKeys the keys to remove
      * @throws NullPointerException if {@code restOfOldKeys} is {@code null}
      */
     void removeAllKeys( K[] oldKeys );
 
     /**
      * @see #removeAllKeys(Collection)
      * @param oldKey the first key to remove
      * @param restOfOldKeys the remainder of keys to remove
      * @throws NullPointerException if {@code restOfOldKeys} is {@code null}
      */
     void removeAllKeys( K oldKey, K... restOfOldKeys );
 
     /**
      * @see #removeAllKeys(Collection)
      * @param oldKeys the keys to remove
      * @throws NullPointerException if {@code oldKeys} is {@code null}
      */
     void removeAllKeys( Iterable<? extends K> oldKeys );
 
     /**
      * Removes the element stored at the given key in this dictionary.
      *
      * @param key the key to remove
      * @return the removed element, or {@code null} if there is no such element
      */
     V removeKey( K key );
 
     /**
      * Removes each element of this dictionary whose key causes the given discriminator
      * to answer {@code true}.
      *
      * @param discriminator the discriminator to evaluate
      * @return {@code true} if any removal occurred
      * @throws NullPointerException if {@code discriminator} is {@code null}
      */
     boolean removeIfKey( UnaryCondition<? super K> discriminator );
 
     /**
      * Removes each element of this dictionary which causes the given discriminator to
      * answer {@code true}.
      *
      * @param discriminator the discriminator to evaluate
      * @return {@code true} if any removal occurred
      * @throws NullPointerException if {@code discriminator} is {@code null}
      */
     boolean removeIfValue( UnaryCondition<? super V> discriminator );
 
     /**
      * Removes any elements from this dictionary which are not stored at any of the given
      * keys.
      * <p/>
      * Note that if the given collection is {@linkplain #isEmpty() empty}, this method
      * has the effect of "clearing" this dictionary.
      *
      * @param keepers the keys to retain
      * @return {@code true} if any elements were removed from this dictionary
      * @throws NullPointerException if {@code keepers} is {@code null}
      */
     boolean retainAllKeys( Collection<? extends K> keepers );
 
     /**
      * @see #retainAllKeys(Collection)
      * @param keepers the keys to retain
      * @return {@code true} if any elements were removed from this dictionary
      * @throws NullPointerException if {@code keepers} is {@code null}
      */
     boolean retainAllKeys( K[] keepers );
 
     /**
      * @see #retainAllKeys(Collection)
      * @param keeper the first key to retain
      * @param restOfKeepers the remainder of keys to retain
      * @return {@code true} if any elements were removed from this dictionary
      * @throws NullPointerException if {@code restOfKeepers} is {@code null}
      */
     boolean retainAllKeys( K keeper, K... restOfKeepers );
 
     /**
      * @see #retainAllKeys(Collection)
      * @param keepers the keys to retain
      * @return {@code true} if any elements were removed from this dictionary
      * @throws NullPointerException if {@code keepers} is {@code null}
      */
     boolean retainAllKeys( Iterable<? extends K> keepers );
 
     /**
      * Removes each element of this dictionary whose key causes the given discriminator
      * to answer {@code false}.
      *
      * @param discriminator the discriminator to evaluate
      * @return {@code true} if any removal occurred
      * @throws NullPointerException if {@code discriminator} is {@code null}
      */
     boolean retainIfKey( UnaryCondition<? super K> discriminator );
 
     /**
      * Removes each element of this dictionary which causes the given discriminator to
      * answer {@code false}.
      *
      * @param discriminator the discriminator to evaluate
      * @return {@code true} if any removal occurred
      * @throws NullPointerException if {@code discriminator} is {@code null}
      */
     boolean retainIfValue( UnaryCondition<? super V> discriminator );
 
    /**
      * Answers a new dictionary which contains the elements in this dictionary whose keys
      * cause the given discriminator to answer {@code true}.
      * <p/>
      * For each of this dictionary's keys, {@code discriminator} is evaluated with the
      * corresponding element as the argument.  If the element causes {@code discriminator}
      * to answer {@code true}, the key is added to the answer with the element as
      * its corresponding value.
      *
      * @param discriminator the discriminator to evaluate
      * @return a dictionary of matches
      * @throws NullPointerException if {@code discriminator} is {@code null}
      */
     AbstractDictionary<K, V> selectValues( UnaryCondition<? super V> discriminator );
 
     /**
      * Answers a collection of this dictionary's elements.
      *
      * @return a bag of the values in this dictionary
      */
     AbstractBag<V> values();
 }

1		/*
2		Copyright 2004-2008 Paul R. Holser, Jr. All rights reserved.
3		Licensed under the Academic Free License version 3.0
4		*/
5
6		package jaggregate;
7
8		/**
9		* Provides protocol for accessing, adding, removing, and iterating over the
10		* <dfn>elements</dfn> of an unordered collection whose elements are accessed using
11		* an explicitly assigned external <dfn>key</dfn>.
12		*
13		* @param <K> a restriction on the types of the keys that may be contained in the
14		* dictionary
15		* @param <V> a restriction on the types of the values that may be contained in the
16		* dictionary
17		*
18		* @author <a href="mailto:pholser@alumni.rice.edu">Paul Holser</a>
19		* @version $Id: AbstractDictionary.java,v 1.5 2008/05/08 03:49:37 pholser Exp $
20		*/
21		public interface AbstractDictionary<K, V> extends ExtensibleCollection<Pair<K, V>> {
22		/**
23		* {@inheritDoc}
24		*
25		* @return a bag of results
26		*/
27		<R> AbstractBag<R> collect(
28		UnaryFunctor<? super Pair<K, V>, ? extends R> transformer );
29
30		/**
31		* {@inheritDoc}
32		*
33		* @return a dictionary of rejects
34		*/
35		AbstractDictionary<K, V> reject( UnaryCondition<? super Pair<K, V>> discriminator );
36
37		/**
38		* {@inheritDoc}
39		*
40		* @return a dictionary of matches
41		*/
42		AbstractDictionary<K, V> select( UnaryCondition<? super Pair<K, V>> discriminator );
43
44		/**
45		* Answers the element associated with the given key in this dictionary.
46		*
47		* @param key the key to look up
48		* @return the associated element, or {@code null} if there is no such element
49		*/
50		V at( K key );
51
52		/**
53		* Answers a new dictionary whose keys are this dictionary's keys, and whose
54		* corresponding elements are the results of evaluating the given transformer with
55		* each corresponding element of this dictionary. For each of this dictionary's
56		* keys, a new element is obtained by evaluating {@code transformer} with the
57		* corresponding element of this dictionary as a parameter.
58		* <p/>
59		* The elements are traversed in the order specified by {@link
60		* #forEachDo(UnaryFunctor) forEachDo} for this dictionary.
61		*
62		* @param <R> return type of the transformer
63		* @param transformer the transformer to evaluate
64		* @return the results of evaluating {@code transformer} with the elements of this
65		* dictionary
66		* @throws NullPointerException if {@code transformer} is {@code null}
67		*/
68		<R> AbstractDictionary<K, R> collectValues(
69		UnaryFunctor<? super V, ? extends R> transformer );
70
71		/**
72		* Answers {@code true} if this dictionary contains an element stored at the given
73		* key, else answers {@code false}.
74		*
75		* @param key the key to lookup
76		* @return whether the key is in this dictionary
77		*/
78		boolean includesKey( K key );
79
80		/**
81		* Answers a key such that the element associated with this key is equivalent to
82		* the given value.
83		* <p/>
84		* Note that if there are multiple elements in this dictionary that are equivalent to
85		* the given value, then the one whose key answered is arbitrary.
86		*
87		* @param value the value to look up
88		* @return an associated key, or {@code null} if there is no such key
89		*/
90		K keyAt( V value );
91
92		/**
93		* Answers a set of keys at which there is an element stored in this dictionary.
94		* <p/>
95		* The {@linkplain #size() size} of the result is equal to the {@linkplain #size()
96		* size} of this dictionary.
97		*
98		* @return a set of the keys in this dictionary
99		*/
100		AbstractSet<K> keys();
101
102		/**
103		* Iteratively evaluates the given operation with each of this dictionary's keys and
104		* values.
105		* <p/>
106		* For each of this dictionary's elements, {@code operation} is evaluated with the
107		* corresponding key as the first argument and the element as the second argument.
108		* <p/>
109		* The order in which the elements are visited is not specified. Each key is visited
110		* exactly once.
111		*
112		* @param operation the operation to perform
113		* @throws NullPointerException if {@code operation} is {@code null}
114		*/
115		void keysAndValuesDo( BinaryFunctor<? super K, ? super V, ?> operation );
116
117		/**
118		* Iteratively evaluates the given operation with each of this dictionary's keys
119		* at which there are elements stored.
120		* <p/>
121		* For each of this dictionary's elements, {@code operation} is evaluated with the
122		* corresponding key as the argument.
123		* <p/>
124		* The order in which the elements are visited is not specified. Each key is visited
125		* exactly once.
126		*
127		* @param <R> a constraint on the return type of the operation
128		* @param operation the operation to perform
129		* @throws NullPointerException if {@code operation} is {@code null}
130		*/
131		<R> void keysDo( UnaryFunctor<? super K, ? extends R> operation );
132
133		/**
134		* Stores the elements of the given dictionary in this dictionary at the
135		* corresponding key from the given dictionary.
136		* <p/>
137		* This message is equivalent to repeatedly performing {@link #putAt(Object,Object)
138		* putAt} on this dictionary with each of the keys and elements from {@code newPairs}
139		* in turn. If a key in {@code newPairs} is <dfn>key-equivalent</dfn> to a key in
140		* this dictionary, the associated element in {@code newPairs} replaces the element
141		* in this dictionary.
142		*
143		* @param newPairs the pairs to add
144		* @throws NullPointerException if {@code newPairs} is {@code null}
145		*/
146		void putAll( AbstractDictionary<? extends K, ? extends V> newPairs );
147
148		/**
149		* Stores a new element at a given key in this dictionary.
150		* <p/>
151		* If lookup succeeds for {@code key}, then {@code newElement} replaces the element
152		* previously stored at {@code key}. Otherwise, {@code newElement} is stored at the
153		* new {@code key}. In either case, subsequent successful lookups for {@code key}
154		* will answer {@code newElement}.
155		*
156		* @param key a key
157		* @param newElement the new element to associate with {@code key}
158		* @return the element previously associated with {@code key}, or {@code null} if
159		* there is no such element
160		*/
161		V putAt( K key, V newElement );
162
163		/**
164		* Answers a new dictionary which excludes the elements in this dictionary that cause
165		* the given discriminator to answer {@code true}.
166		* <p/>
167		* For each of this dictionary's keys, {@code discriminator} is evaluated with the
168		* corresponding element as the argument. If the element causes {@code discriminator}
169		* to answer {@code false}, the key is added to the answer with the element as its
170		* corresponding value.
171		*
172		* @param discriminator the discriminator to evaluate
173		* @return a dictionary of rejects
174		* @throws NullPointerException if {@code discriminator} is {@code null}
175		*/
176		AbstractDictionary<K, V> rejectValues( UnaryCondition<? super V> discriminator );
177
178		/**
179		* Removes any elements from this dictionary which are stored at any of the given
180		* keys.
181		* <p/>
182		* This message has the same effect as repeatedly performing {@link
183		* #removeKey(Object) removeKey} on this dictionary for each element in
184		* {@code oldKeys}.
185		*
186		* @param oldKeys the keys to remove
187		* @throws NullPointerException if {@code oldKeys} is {@code null}
188		*/
189		void removeAllKeys( Collection<? extends K> oldKeys );
190
191		/**
192		* @see #removeAllKeys(Collection)
193		* @param oldKeys the keys to remove
194		* @throws NullPointerException if {@code restOfOldKeys} is {@code null}
195		*/
196		void removeAllKeys( K[] oldKeys );
197
198		/**
199		* @see #removeAllKeys(Collection)
200		* @param oldKey the first key to remove
201		* @param restOfOldKeys the remainder of keys to remove
202		* @throws NullPointerException if {@code restOfOldKeys} is {@code null}
203		*/
204		void removeAllKeys( K oldKey, K... restOfOldKeys );
205
206		/**
207		* @see #removeAllKeys(Collection)
208		* @param oldKeys the keys to remove
209		* @throws NullPointerException if {@code oldKeys} is {@code null}
210		*/
211		void removeAllKeys( Iterable<? extends K> oldKeys );
212
213		/**
214		* Removes the element stored at the given key in this dictionary.
215		*
216		* @param key the key to remove
217		* @return the removed element, or {@code null} if there is no such element
218		*/
219		V removeKey( K key );
220
221		/**
222		* Removes each element of this dictionary whose key causes the given discriminator
223		* to answer {@code true}.
224		*
225		* @param discriminator the discriminator to evaluate
226		* @return {@code true} if any removal occurred
227		* @throws NullPointerException if {@code discriminator} is {@code null}
228		*/
229		boolean removeIfKey( UnaryCondition<? super K> discriminator );
230
231		/**
232		* Removes each element of this dictionary which causes the given discriminator to
233		* answer {@code true}.
234		*
235		* @param discriminator the discriminator to evaluate
236		* @return {@code true} if any removal occurred
237		* @throws NullPointerException if {@code discriminator} is {@code null}
238		*/
239		boolean removeIfValue( UnaryCondition<? super V> discriminator );
240
241		/**
242		* Removes any elements from this dictionary which are not stored at any of the given
243		* keys.
244		* <p/>
245		* Note that if the given collection is {@linkplain #isEmpty() empty}, this method
246		* has the effect of "clearing" this dictionary.
247		*
248		* @param keepers the keys to retain
249		* @return {@code true} if any elements were removed from this dictionary
250		* @throws NullPointerException if {@code keepers} is {@code null}
251		*/
252		boolean retainAllKeys( Collection<? extends K> keepers );
253
254		/**
255		* @see #retainAllKeys(Collection)
256		* @param keepers the keys to retain
257		* @return {@code true} if any elements were removed from this dictionary
258		* @throws NullPointerException if {@code keepers} is {@code null}
259		*/
260		boolean retainAllKeys( K[] keepers );
261
262		/**
263		* @see #retainAllKeys(Collection)
264		* @param keeper the first key to retain
265		* @param restOfKeepers the remainder of keys to retain
266		* @return {@code true} if any elements were removed from this dictionary
267		* @throws NullPointerException if {@code restOfKeepers} is {@code null}
268		*/
269		boolean retainAllKeys( K keeper, K... restOfKeepers );
270
271		/**
272		* @see #retainAllKeys(Collection)
273		* @param keepers the keys to retain
274		* @return {@code true} if any elements were removed from this dictionary
275		* @throws NullPointerException if {@code keepers} is {@code null}
276		*/
277		boolean retainAllKeys( Iterable<? extends K> keepers );
278
279		/**
280		* Removes each element of this dictionary whose key causes the given discriminator
281		* to answer {@code false}.
282		*
283		* @param discriminator the discriminator to evaluate
284		* @return {@code true} if any removal occurred
285		* @throws NullPointerException if {@code discriminator} is {@code null}
286		*/
287		boolean retainIfKey( UnaryCondition<? super K> discriminator );
288
289		/**
290		* Removes each element of this dictionary which causes the given discriminator to
291		* answer {@code false}.
292		*
293		* @param discriminator the discriminator to evaluate
294		* @return {@code true} if any removal occurred
295		* @throws NullPointerException if {@code discriminator} is {@code null}
296		*/
297		boolean retainIfValue( UnaryCondition<? super V> discriminator );
298
299		/**
300		* Answers a new dictionary which contains the elements in this dictionary whose keys
301		* cause the given discriminator to answer {@code true}.
302		* <p/>
303		* For each of this dictionary's keys, {@code discriminator} is evaluated with the
304		* corresponding element as the argument. If the element causes {@code discriminator}
305		* to answer {@code true}, the key is added to the answer with the element as
306		* its corresponding value.
307		*
308		* @param discriminator the discriminator to evaluate
309		* @return a dictionary of matches
310		* @throws NullPointerException if {@code discriminator} is {@code null}
311		*/
312		AbstractDictionary<K, V> selectValues( UnaryCondition<? super V> discriminator );
313
314		/**
315		* Answers a collection of this dictionary's elements.
316		*
317		* @return a bag of the values in this dictionary
318		*/
319		AbstractBag<V> values();
320		}