1 /*
2  * Copyright (C) 2007 The Guava Authors
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package com.google.common.collect;
18 
19 import com.google.common.annotations.GwtCompatible;
20 import com.google.errorprone.annotations.DoNotMock;
21 import java.util.Map;
22 import org.checkerframework.checker.nullness.compatqual.NullableDecl;
23 
24 /**
25  * An object representing the differences between two maps.
26  *
27  * @author Kevin Bourrillion
28  * @since 2.0
29  */
30 @DoNotMock("Use Maps.difference")
31 @GwtCompatible
32 public interface MapDifference<K, V> {
33   /**
34    * Returns {@code true} if there are no differences between the two maps; that is, if the maps are
35    * equal.
36    */
areEqual()37   boolean areEqual();
38 
39   /**
40    * Returns an unmodifiable map containing the entries from the left map whose keys are not present
41    * in the right map.
42    */
entriesOnlyOnLeft()43   Map<K, V> entriesOnlyOnLeft();
44 
45   /**
46    * Returns an unmodifiable map containing the entries from the right map whose keys are not
47    * present in the left map.
48    */
entriesOnlyOnRight()49   Map<K, V> entriesOnlyOnRight();
50 
51   /**
52    * Returns an unmodifiable map containing the entries that appear in both maps; that is, the
53    * intersection of the two maps.
54    */
entriesInCommon()55   Map<K, V> entriesInCommon();
56 
57   /**
58    * Returns an unmodifiable map describing keys that appear in both maps, but with different
59    * values.
60    */
entriesDiffering()61   Map<K, ValueDifference<V>> entriesDiffering();
62 
63   /**
64    * Compares the specified object with this instance for equality. Returns {@code true} if the
65    * given object is also a {@code MapDifference} and the values returned by the {@link
66    * #entriesOnlyOnLeft()}, {@link #entriesOnlyOnRight()}, {@link #entriesInCommon()} and {@link
67    * #entriesDiffering()} of the two instances are equal.
68    */
69   @Override
equals(@ullableDecl Object object)70   boolean equals(@NullableDecl Object object);
71 
72   /**
73    * Returns the hash code for this instance. This is defined as the hash code of
74    *
75    * <pre>{@code
76    * Arrays.asList(entriesOnlyOnLeft(), entriesOnlyOnRight(),
77    *     entriesInCommon(), entriesDiffering())
78    * }</pre>
79    */
80   @Override
hashCode()81   int hashCode();
82 
83   /**
84    * A difference between the mappings from two maps with the same key. The {@link #leftValue} and
85    * {@link #rightValue} are not equal, and one but not both of them may be null.
86    *
87    * @since 2.0
88    */
89   @DoNotMock("Use Maps.difference")
90   interface ValueDifference<V> {
91     /** Returns the value from the left map (possibly null). */
leftValue()92     V leftValue();
93 
94     /** Returns the value from the right map (possibly null). */
rightValue()95     V rightValue();
96 
97     /**
98      * Two instances are considered equal if their {@link #leftValue()} values are equal and their
99      * {@link #rightValue()} values are also equal.
100      */
101     @Override
equals(@ullableDecl Object other)102     boolean equals(@NullableDecl Object other);
103 
104     /**
105      * The hash code equals the value {@code Arrays.asList(leftValue(), rightValue()).hashCode()}.
106      */
107     @Override
hashCode()108     int hashCode();
109   }
110 }
111