Interface DoubleKeyMap<Key1,​Key2,​Value>

  • All Known Implementing Classes:
    AbstractDoubleKeyMap, DoubleKeyHashMap, SynchronizedDoubleKeyHashMap

    public interface DoubleKeyMap<Key1,​Key2,​Value>
    Represents the map with the double key (Key1, Key2) -> Value.

    The interface promises efficient look up if both keys, just the first key, or just the second key is known (constant number of the ordinary map look ups):

       (key1, key2) -> value
       key1 -> (key2 -> value)
       key2 -> (key1 -> value)
     
    To add a value, both keys should be known.

    Derived classes can use various underlying java.util.Map implementations (HashMap, TreeMap, etc). Can be thread-safe or not thread-safe depending on a particular implementation.

    Since:
    8.1
    Author:
    Maxim Podkolzine (maxim.podkolzine@jetbrains.com)
    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void clear()
      Clears the map.
      boolean contains​(Key1 k1, Key2 k2)
      Returns whether the map contains a value for the key pair (k1, k2).
      boolean containsAnyByKey1​(Key1 k1)
      Returns whether the map contains any value for the specified first key k1.
      boolean containsAnyByKey2​(Key2 k2)
      Returns whether the map contains any value for the specified second key k2.
      java.util.Set<java.util.Map.Entry<Key1,​java.util.Map<Key2,​Value>>> entrySet()
      Returns a set view of the map entries in a form (key1, key2 -> value).
      java.util.Set<java.util.Map.Entry<Key2,​Value>> entrySetByKey1​(Key1 k1)
      Returns a set view of the map slice by the specified first key k1.
      java.util.Set<java.util.Map.Entry<Key1,​Value>> entrySetByKey2​(Key2 k2)
      Returns a set view of the map slice by the specified second key k2.
      Value get​(Key1 k1, Key2 k2)
      Returns the value corresponding to the key pair (k1, k2).
      java.util.Map<Key2,​Value> getAllByKey1​(Key1 k1)
      Returns the map slice by the first key k1 specified.
      java.util.Map<Key1,​Value> getAllByKey2​(Key2 k2)
      Returns the map slice by the second key k2 specified.
      boolean isEmpty()
      Returns whether the map is empty.
      java.util.Map<Key1,​java.util.Set<Key2>> keys()
      Returns all the keys of this map in a form key1 -> {key2}.
      java.util.Set<Key2> keySet1​(Key1 k1)
      Returns the key set of the map slice by the specified first key k1.
      java.util.Set<Key1> keySet2​(Key2 k2)
      Returns the key set of the map slice by the specified second key k2.
      Value put​(Key1 k1, Key2 k2, Value v)
      Adds the triple to the map, overwrites existing one if present.
      void putAll​(DoubleKeyMap<Key1,​Key2,​Value> map)
      Adds another DoubleKeyMap to this map.
      void putAllForKey1​(Key1 k1, java.util.Map<Key2,​Value> map)
      Adds the bunch of values to the map, overwriting existing ones if present.
      void putAllForKey2​(Key2 k2, java.util.Map<Key1,​Value> map)
      Adds the bunch of values to the map, overwriting existing ones if present.
      Value remove​(Key1 k1, Key2 k2)
      Removes the value from the map corresponding to the keys pair (k1, k2) (if present).
      void removeAll​(java.util.Collection<Key1> keys1, java.util.Collection<Key2> keys2)
      Removes the whole sector covered by the key sets keys1 and key2).
      java.util.Map<Key2,​Value> removeAllByKey1​(Key1 k1)
      Removes all values from the map corresponding to the first key k1 (if present).
      java.util.Map<Key1,​Value> removeAllByKey2​(Key2 k2)
      Removes all values from the map corresponding to the second key k2 (if present).
      int size()
      Returns the map size (the number of triples).
      java.util.Collection<Value> values()
      Returns a collection of values of this map.
      java.util.Collection<Value> valuesByKey1​(Key1 k1)
      Returns the values collection of the map slice by the specified first key k1.
      java.util.Collection<Value> valuesByKey2​(Key2 k2)
      Returns the values collection of the map slice by the specified second key k2.
    • Method Detail

      • put

        @Nullable
        Value put​(@NotNull
                  Key1 k1,
                  @NotNull
                  Key2 k2,
                  @Nullable
                  Value v)
        Adds the triple to the map, overwrites existing one if present.

        Uses the constant number of ordinary map operations (get and put).

        Parameters:
        k1 - first key
        k2 - second key
        v - the value (can be null).
        Returns:
        previous value for the (k1, k2)
      • putAllForKey1

        void putAllForKey1​(@NotNull
                           Key1 k1,
                           @NotNull
                           java.util.Map<Key2,​Value> map)
        Adds the bunch of values to the map, overwriting existing ones if present. More precisely, this method adds the entries (k1, k2, v), where (k2, v) are all mappings of the specified map.

        Works in a linear time of input map size.

        Parameters:
        k1 - first key
        map - the second key based map
      • putAllForKey2

        void putAllForKey2​(@NotNull
                           Key2 k2,
                           @NotNull
                           java.util.Map<Key1,​Value> map)
        Adds the bunch of values to the map, overwriting existing ones if present. More precisely, this method adds the entries (k1, k2, v), where (k1, v) are all mappings of the specified map.

        Works in a linear time of input map size.

        Parameters:
        k2 - second key
        map - the second key based map
      • putAll

        void putAll​(@NotNull
                    DoubleKeyMap<Key1,​Key2,​Value> map)
        Adds another DoubleKeyMap to this map.

        The values with same key pairs are overwritten.

        Parameters:
        map - the map
      • size

        int size()
        Returns the map size (the number of triples).

        Works in a constant time (O(1)). Can be invalid if DoubleKeyMap.entrySet().remove was used

        Returns:
        map size
      • isEmpty

        boolean isEmpty()
        Returns whether the map is empty.

        Works in a constant time (O(1)).

        Returns:
        true if the map is empty
      • get

        @Nullable
        Value get​(@NotNull
                  Key1 k1,
                  @NotNull
                  Key2 k2)
        Returns the value corresponding to the key pair (k1, k2).

        Uses the constant number of ordinary map operations (get).

        Parameters:
        k1 - first key
        k2 - second key
        Returns:
        the value if present, or null.
      • getAllByKey1

        @NotNull
        java.util.Map<Key2,​Value> getAllByKey1​(@NotNull
                                                     Key1 k1)
        Returns the map slice by the first key k1 specified. For all triples (k1, k2) -> value a map k2 -> value with fixed k1 is returned.

        Result map can be empty, but never null.

        Uses the constant number of ordinary map operations (get).

        Parameters:
        k1 - first key
        Returns:
        map slice by the first key
      • getAllByKey2

        @NotNull
        java.util.Map<Key1,​Value> getAllByKey2​(@NotNull
                                                     Key2 k2)
        Returns the map slice by the second key k2 specified. For all triples (k1, k2) -> value a map k1 -> value with fixed k2 is returned.

        Result map can be empty, but never null.

        Uses the constant number of ordinary map operations (get).

        Parameters:
        k2 - second key
        Returns:
        map slice by the second key
      • contains

        boolean contains​(@NotNull
                         Key1 k1,
                         @NotNull
                         Key2 k2)
        Returns whether the map contains a value for the key pair (k1, k2).

        Uses the constant number of ordinary map operations (get).

        Parameters:
        k1 - first key
        k2 - second key
        Returns:
        true if there is a value for the (k1, k2) pair.
      • containsAnyByKey1

        boolean containsAnyByKey1​(@NotNull
                                  Key1 k1)
        Returns whether the map contains any value for the specified first key k1.

        Uses the constant number of ordinary map operations (get).

        Parameters:
        k1 - first key
        Returns:
        true if there is a value for the first key
      • containsAnyByKey2

        boolean containsAnyByKey2​(@NotNull
                                  Key2 k2)
        Returns whether the map contains any value for the specified second key k2.

        Uses the constant number of ordinary map operations (get).

        Parameters:
        k2 - second key
        Returns:
        true if there is a value for the second key
      • entrySet

        @NotNull
        java.util.Set<java.util.Map.Entry<Key1,​java.util.Map<Key2,​Value>>> entrySet()
        Returns a set view of the map entries in a form (key1, key2 -> value).

        Works in a constant time (O(1)).

        Returns:
        a set view of the mappings contained in this map
      • entrySetByKey1

        @NotNull
        java.util.Set<java.util.Map.Entry<Key2,​Value>> entrySetByKey1​(@NotNull
                                                                            Key1 k1)
        Returns a set view of the map slice by the specified first key k1.

        Uses the constant number of ordinary map operations (get).

        Returns:
        a set view of the map slice by the first key
      • entrySetByKey2

        @NotNull
        java.util.Set<java.util.Map.Entry<Key1,​Value>> entrySetByKey2​(@NotNull
                                                                            Key2 k2)
        Returns a set view of the map slice by the specified second key k2.

        Uses the constant number of ordinary map operations (get).

        Returns:
        a set view of the map slice by the second key
      • keys

        @NotNull
        java.util.Map<Key1,​java.util.Set<Key2>> keys()
        Returns all the keys of this map in a form key1 -> {key2}.

        Works in a linear time of map size.

        Changes in the keys map do not reflect the changes in this map.

        Returns:
        all map keys as a map
      • keySet1

        @NotNull
        java.util.Set<Key2> keySet1​(@NotNull
                                    Key1 k1)
        Returns the key set of the map slice by the specified first key k1.

        Uses the constant number of ordinary map operations (get).

        Parameters:
        k1 - first key
        Returns:
        key set of the map slice by the first key
      • keySet2

        @NotNull
        java.util.Set<Key1> keySet2​(@NotNull
                                    Key2 k2)
        Returns the key set of the map slice by the specified second key k2.

        Uses the constant number of ordinary map operations (get).

        Parameters:
        k2 - second key
        Returns:
        key set of the map slice by the second key
      • values

        @NotNull
        java.util.Collection<Value> values()
        Returns a collection of values of this map. Result map can be empty, but never null.

        Works in a linear time of map size and uses linear memory.

        Changes in the values collection do not reflect the changes in this map.

        Returns:
        all map values
      • valuesByKey1

        @NotNull
        java.util.Collection<Value> valuesByKey1​(@NotNull
                                                 Key1 k1)
        Returns the values collection of the map slice by the specified first key k1. Result map can be empty, but never null.

        Uses the constant number of ordinary map operations (get).

        Parameters:
        k1 - first key
        Returns:
        values collection of the map slice by the first key
      • valuesByKey2

        @NotNull
        java.util.Collection<Value> valuesByKey2​(@NotNull
                                                 Key2 k2)
        Returns the values collection of the map slice by the specified second key k2. Result map can be empty, but never null.

        Uses the constant number of ordinary map operations (get).

        Parameters:
        k2 - second key
        Returns:
        values collection of the map slice by the second key
      • remove

        @Nullable
        Value remove​(@NotNull
                     Key1 k1,
                     @NotNull
                     Key2 k2)
        Removes the value from the map corresponding to the keys pair (k1, k2) (if present).

        Uses the constant number of ordinary map operations (get, remove).

        Parameters:
        k1 - first key
        k2 - second key
        Returns:
        the previous value for the (k1, k2) pair, or null if it is not present
      • removeAllByKey1

        @Nullable
        java.util.Map<Key2,​Value> removeAllByKey1​(@NotNull
                                                        Key1 k1)
        Removes all values from the map corresponding to the first key k1 (if present).

        Works in a linear time of the size of the returned map.

        Parameters:
        k1 - first key
        Returns:
        the map slice by the first key k1 present just before the removal (can be null).
      • removeAllByKey2

        @Nullable
        java.util.Map<Key1,​Value> removeAllByKey2​(@NotNull
                                                        Key2 k2)
        Removes all values from the map corresponding to the second key k2 (if present).

        Works in a linear time of the size of the returned map.

        Parameters:
        k2 - second key
        Returns:
        the map slice by the second key k2 present just before the removal (can be null).
      • removeAll

        void removeAll​(@NotNull
                       java.util.Collection<Key1> keys1,
                       @NotNull
                       java.util.Collection<Key2> keys2)
        Removes the whole sector covered by the key sets keys1 and key2). More precisely, this method removes all entries (k1, k2, v), for which keys1.contains(k1) && keys2.contains(k2).

        Time complexity is O(n1) * O(n2), where n1 and n2 are the sizes of the input collections.

        Parameters:
        keys1 - the first keys collection
        keys2 - the second keys collection
      • clear

        void clear()
        Clears the map. As a result of this call, the map size would be 0.

        Works in a linear time of the map size.