11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.util;
27
28 import java.util.function.BiConsumer;
29 import java.util.function.BiFunction;
30 import java.util.function.Function;
31
32 /**
33 * An object that maps keys to values. A map cannot contain duplicate keys;
34 * each key can map to at most one value.
35 *
36 * <p>This interface takes the place of the <tt>Dictionary</tt> class, which
37 * was a totally abstract class rather than an interface.
38 *
39 * <p>The <tt>Map</tt> interface provides three <i>collection views</i>, which
40 * allow a map's contents to be viewed as a set of keys, collection of values,
41 * or set of key-value mappings. The <i>order</i> of a map is defined as
42 * the order in which the iterators on the map's collection views return their
43 * elements. Some map implementations, like the <tt>TreeMap</tt> class, make
44 * specific guarantees as to their order; others, like the <tt>HashMap</tt>
45 * class, do not.
46 *
47 * <p>Note: great care must be exercised if mutable objects are used as map
48 * keys. The behavior of a map is not specified if the value of an object is
49 * changed in a manner that affects <tt>equals</tt> comparisons while the
50 * object is a key in the map. A special case of this prohibition is that it
429 */
430 boolean equals(Object o);
431
432 /**
433 * Returns the hash code value for this map entry. The hash code
434 * of a map entry <tt>e</tt> is defined to be: <pre>
435 * (e.getKey()==null ? 0 : e.getKey().hashCode()) ^
436 * (e.getValue()==null ? 0 : e.getValue().hashCode())
437 * </pre>
438 * This ensures that <tt>e1.equals(e2)</tt> implies that
439 * <tt>e1.hashCode()==e2.hashCode()</tt> for any two Entries
440 * <tt>e1</tt> and <tt>e2</tt>, as required by the general
441 * contract of <tt>Object.hashCode</tt>.
442 *
443 * @return the hash code value for this map entry
444 * @see Object#hashCode()
445 * @see Object#equals(Object)
446 * @see #equals(Object)
447 */
448 int hashCode();
449 }
450
451 // Comparison and hashing
452
453 /**
454 * Compares the specified object with this map for equality. Returns
455 * <tt>true</tt> if the given object is also a map and the two maps
456 * represent the same mappings. More formally, two maps <tt>m1</tt> and
457 * <tt>m2</tt> represent the same mappings if
458 * <tt>m1.entrySet().equals(m2.entrySet())</tt>. This ensures that the
459 * <tt>equals</tt> method works properly across different implementations
460 * of the <tt>Map</tt> interface.
461 *
462 * @param o object to be compared for equality with this map
463 * @return <tt>true</tt> if the specified object is equal to this map
464 */
465 boolean equals(Object o);
466
467 /**
468 * Returns the hash code value for this map. The hash code of a map is
|
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.util;
27
28 import java.util.function.BiConsumer;
29 import java.util.function.BiFunction;
30 import java.util.function.Function;
31 import java.io.Serializable;
32
33 /**
34 * An object that maps keys to values. A map cannot contain duplicate keys;
35 * each key can map to at most one value.
36 *
37 * <p>This interface takes the place of the <tt>Dictionary</tt> class, which
38 * was a totally abstract class rather than an interface.
39 *
40 * <p>The <tt>Map</tt> interface provides three <i>collection views</i>, which
41 * allow a map's contents to be viewed as a set of keys, collection of values,
42 * or set of key-value mappings. The <i>order</i> of a map is defined as
43 * the order in which the iterators on the map's collection views return their
44 * elements. Some map implementations, like the <tt>TreeMap</tt> class, make
45 * specific guarantees as to their order; others, like the <tt>HashMap</tt>
46 * class, do not.
47 *
48 * <p>Note: great care must be exercised if mutable objects are used as map
49 * keys. The behavior of a map is not specified if the value of an object is
50 * changed in a manner that affects <tt>equals</tt> comparisons while the
51 * object is a key in the map. A special case of this prohibition is that it
430 */
431 boolean equals(Object o);
432
433 /**
434 * Returns the hash code value for this map entry. The hash code
435 * of a map entry <tt>e</tt> is defined to be: <pre>
436 * (e.getKey()==null ? 0 : e.getKey().hashCode()) ^
437 * (e.getValue()==null ? 0 : e.getValue().hashCode())
438 * </pre>
439 * This ensures that <tt>e1.equals(e2)</tt> implies that
440 * <tt>e1.hashCode()==e2.hashCode()</tt> for any two Entries
441 * <tt>e1</tt> and <tt>e2</tt>, as required by the general
442 * contract of <tt>Object.hashCode</tt>.
443 *
444 * @return the hash code value for this map entry
445 * @see Object#hashCode()
446 * @see Object#equals(Object)
447 * @see #equals(Object)
448 */
449 int hashCode();
450
451 /**
452 * Returns a comparator that compares {@link Map.Entry} in natural order on key.
453 *
454 * <p>The returned comparator is serializable. Note that a null key in the
455 * map will cause the returned comparator to throw {@link
456 * NullPointerException}.
457 *
458 * @param <K> {@link Comparable} key type
459 * @param <V> value type
460 * @return A comparator that compares {@link Map.Entry} in natural order on key.
461 * @see Comparable
462 */
463 public static <K extends Comparable<? super K>, V> Comparator<Map.Entry<K,V>> comparingByKey() {
464 return (Comparator<Map.Entry<K, V>> & Serializable)
465 (c1, c2) -> c1.getKey().compareTo(c2.getKey());
466 }
467
468 /**
469 * Returns a comparator that compares {@link Map.Entry} in natural order on value.
470 *
471 * <p>The returned comparator is serializable. Note that a null value in
472 * the map will cause the returned comparator to throw {@link
473 * NullPointerException}.
474 *
475 * @param <K> key type
476 * @param <V> {@link Comparable} value type
477 * @return A comparator that compares {@link Map.Entry} in natural order on value.
478 * @see Comparable
479 */
480 public static <K, V extends Comparable<? super V>> Comparator<Map.Entry<K,V>> comparingByValue() {
481 return (Comparator<Map.Entry<K, V>> & Serializable)
482 (c1, c2) -> c1.getValue().compareTo(c2.getValue());
483 }
484
485 /**
486 * Returns a comparator that compares {@link Map.Entry} by key using the given
487 * {@link Comparator}.
488 *
489 * <p>The returned comparator is serializable if the specified
490 * comparator is also serializable.
491 *
492 * @param <K> key type
493 * @param <V> value type
494 * @param cmp the key {@link Comparator}
495 * @return A comparator that compares {@link Map.Entry} by the key.
496 */
497 public static <K, V> Comparator<Map.Entry<K, V>> comparingByKey(Comparator<? super K> cmp) {
498 Objects.requireNonNull(cmp);
499 return (Comparator<Map.Entry<K, V>> & Serializable)
500 (c1, c2) -> cmp.compare(c1.getKey(), c2.getKey());
501 }
502
503 /**
504 * Returns a comparator that compares {@link Map.Entry} by value using the given
505 * {@link Comparator}.
506 *
507 * <p>The returned comparator is serializable if the specified
508 * comparator is also serializable.
509 *
510 * @param <K> key type
511 * @param <V> value type
512 * @param cmp the value {@link Comparator}
513 * @return A comparator that compares {@link Map.Entry} by the value.
514 */
515 public static <K, V> Comparator<Map.Entry<K, V>> comparingByValue(Comparator<? super V> cmp) {
516 Objects.requireNonNull(cmp);
517 return (Comparator<Map.Entry<K, V>> & Serializable)
518 (c1, c2) -> cmp.compare(c1.getValue(), c2.getValue());
519 }
520 }
521
522 // Comparison and hashing
523
524 /**
525 * Compares the specified object with this map for equality. Returns
526 * <tt>true</tt> if the given object is also a map and the two maps
527 * represent the same mappings. More formally, two maps <tt>m1</tt> and
528 * <tt>m2</tt> represent the same mappings if
529 * <tt>m1.entrySet().equals(m2.entrySet())</tt>. This ensures that the
530 * <tt>equals</tt> method works properly across different implementations
531 * of the <tt>Map</tt> interface.
532 *
533 * @param o object to be compared for equality with this map
534 * @return <tt>true</tt> if the specified object is equal to this map
535 */
536 boolean equals(Object o);
537
538 /**
539 * Returns the hash code value for this map. The hash code of a map is
|