Module org.jhotdraw8.icollection
Package org.jhotdraw8.icollection

Class RedBlackMap<K,V>

java.lang.Object
org.jhotdraw8.icollection.RedBlackMap<K,V>
Type Parameters:
K - the key type
V - the value type
All Implemented Interfaces:
Serializable, Iterable<Map.Entry<K,V>>, ImmutableMap<K,V>, ImmutableNavigableMap<K,V>, ImmutableSortedMap<K,V>, ReadOnlyMap<K,V>, ReadOnlyNavigableMap<K,V>, ReadOnlySequencedMap<K,V>, ReadOnlySortedMap<K,V>
public class RedBlackMap<K,V> extends Object implements ImmutableNavigableMap<K,V>, Serializable
Implements the ImmutableNavigableSet interface using a Red-Black tree.

References:

For a similar design, see 'TreeMap.java' in vavr. The internal data structure of this class is licensed from vavr.

TreeMap.java. Copyright 2023 (c) vavr. MIT License.
github.com
See Also:

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    RedBlackMap(PrivateData privateData)
    Creates a new instance with the provided privateData data object.

  • Method Summary

    Modifier and Type
    Method
    Description
    @Nullable Map.Entry<K,V>
    ceilingEntry(K k)
    Returns the least entry in this map with a key greater than or equal to the given key, or null if there is no such entry.
    int
    characteristics()
    Returns the spliterator characteristics of the key set.
    RedBlackMap<K,V>
    clear()
    Returns a copy of this map that is empty.
    @Nullable Comparator<? super K>
    comparator()
    Returns the comparator used to order the keys in this map, or null if this set uses the natural ordering of its keys.
    boolean
    containsKey(@Nullable Object key)
    Returns true if this map contains a entry for the specified key.
    static <K, V> RedBlackMap<K,V>
    copyOf(Iterable<? extends Map.Entry<? extends K,? extends V>> c)
    Returns an immutable map that contains the provided elements sorted according to the natural ordering of its elements.
    static <K, V> RedBlackMap<K,V>
    copyOf(Comparator<? super K> comparator, Iterable<? extends Map.Entry<? extends K,? extends V>> c)
    Returns an immutable map that contains the provided entries, sorted according to the specified comparator.
    static <K, V> RedBlackMap<K,V>
    copyOf(Map<? extends K,? extends V> map)
    Returns an immutable copy of the provided map that contains the provided elements sorted according to the natural ordering of its elements.
    boolean
    equals(Object o)
    Compares the specified object with this map for equality.
    @Nullable Map.Entry<K,V>
    firstEntry()
    Gets the first entry in this map or null if this map is empty.
    @Nullable Map.Entry<K,V>
    floorEntry(K k)
    Returns the greatest entry in this map with a key less than or equal to the given key, or null if there is no such entry.
    @Nullable V
    get(Object key)
    Returns the value to which the key is mapped, or null if this map contains no entry for the key.
    int
    hashCode()
    Returns the hash code value for this map.
    @Nullable Map.Entry<K,V>
    higherEntry(K k)
    Returns the least entry in this map with a key greater than the given key, or null if there is no such entry.
    boolean
    isEmpty()
    Returns true if this map contains no entries.
    Iterator<Map.Entry<K,V>>
    iterator()
    Returns an iterator over the entries contained in this map.
    @Nullable Map.Entry<K,V>
    lastEntry()
    Gets the last entry in this map or null if this map is empty.
    @Nullable Map.Entry<K,V>
    lowerEntry(K k)
    Returns the greatest entry in this map with a key less than the given key, or null if there is no such entry.
    int
    maxSize()
    Returns the maximal number of entries that this map type can hold
    protected RedBlackMap<K,V>
    newInstance(PrivateData privateData)
    Creates a new instance with the provided privateData object as its internal data structure.
    static <K, V> RedBlackMap<K,V>
    of()
    Returns an empty immutable map, sorted according to the natural ordering of its entries.
    static <K, V> RedBlackMap<K,V>
    of(Map.Entry<K,V> @Nullable ... entries)
    Returns an immutable map that contains the provided entries, sorted according to the natural ordering of its entries.
    RedBlackMap<K,V>
    put(K key, @Nullable V value)
    Returns a copy of this map that contains all entries of this map with the specified entry added or updated.
    RedBlackMap<K,V>
    putAll(Iterable<? extends Map.Entry<? extends K,? extends V>> c)
    Returns a copy of this map that contains all entries of this map with entries from the specified map added or updated.
    RedBlackMap<K,V>
    putAll(Map<? extends K,? extends V> m)
    Returns a copy of this map that contains all entries of this map with entries from the specified map added or updated.
    RedBlackMap<K,V>
    putKeyValues(Object... kv)
    Returns a copy of this map that contains all entries of this map with entries from the specified map added or updated.
    ReadOnlySequencedMap<K,V>
    readOnlyReversed()
    Returns a reversed-order view of this map.
    RedBlackMap<K,V>
    remove(K key)
    Returns a copy of this map that contains all entries of this map with the specified entry removed.
    RedBlackMap<K,V>
    removeAll(Iterable<? extends K> c)
    Returns a copy of this map that contains all entries of this map except the entries of the specified collection.
    RedBlackMap<K,V>
    retainAll(Iterable<? extends K> c)
    Returns a copy of this map that contains only entries that are in this map and in the specified collection.
    RedBlackMap<K,V>
    retainAll(ReadOnlyCollection<? extends K> c)
    Returns a copy of this map that contains only entries that are in this map and in the specified collection.
    int
    size()
    Returns the number of entries contained in this map..
    static <K, V> RedBlackMap<K,V>
    sortedOf(@Nullable Comparator<? super K> comparator)
    Returns an empty immutable map, sorted according to the specified comparator.
    static <K, V> RedBlackMap<K,V>
    sortedOf(@Nullable Comparator<? super K> comparator, Map.Entry<K,V> @Nullable ... elements)
    Returns an immutable map that contains the provided elements, sorted according to the specified comparator.
    MutableRedBlackMap<K,V>
    toMutable()
    Returns a mutable copy of this map.
    String
    toString()
     

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

    Methods inherited from interface java.lang.Iterable

    forEach

    Methods inherited from interface org.jhotdraw8.icollection.readonly.ReadOnlyMap

    containsEntry, containsValue, getOrDefault

    Methods inherited from interface org.jhotdraw8.icollection.readonly.ReadOnlyNavigableMap

    ceilingKey, floorKey, higherKey, lowerKey

    Methods inherited from interface org.jhotdraw8.icollection.readonly.ReadOnlySequencedMap

    asMap, readOnlyEntrySet, readOnlyKeySet, readOnlyValues

    Methods inherited from interface org.jhotdraw8.icollection.readonly.ReadOnlySortedMap

    spliterator

  • Constructor Details

    • RedBlackMap

      protected RedBlackMap(PrivateData privateData)
      Creates a new instance with the provided privateData data object.

      This constructor is intended to be called from a constructor of the subclass, that is called from method newInstance(PrivateData).

      Parameters:
      privateData - an privateData data object

  • Method Details

    • newInstance

      protected RedBlackMap<K,V> newInstance(PrivateData privateData)
      Creates a new instance with the provided privateData object as its internal data structure.

      Subclasses must override this method, and return a new instance of their subclass!

      Parameters:
      privateData - the internal data structure needed by this class for creating the instance.
      Returns:
      a new instance of the subclass

    • copyOf

      public static <K, V> RedBlackMap<K,V> copyOf(Comparator<? super K> comparator, Iterable<? extends Map.Entry<? extends K,? extends V>> c)
      Returns an immutable map that contains the provided entries, sorted according to the specified comparator.
      Type Parameters:
      K - the key type
      V - the value type
      Parameters:
      c - an iterable
      Returns:
      an immutable map of the provided elements

    • putAll

      public RedBlackMap<K,V> putAll(Map<? extends K,? extends V> m)
      Description copied from interface: ImmutableMap
      Returns a copy of this map that contains all entries of this map with entries from the specified map added or updated.
      Specified by:
      putAll in interface ImmutableMap<K,V>
      Specified by:
      putAll in interface ImmutableNavigableMap<K,V>
      Specified by:
      putAll in interface ImmutableSortedMap<K,V>
      Parameters:
      m - another map
      Returns:
      this map instance if it already contains the same entries, or a different map instance with the entries added or updated

    • putAll

      public RedBlackMap<K,V> putAll(Iterable<? extends Map.Entry<? extends K,? extends V>> c)
      Description copied from interface: ImmutableMap
      Returns a copy of this map that contains all entries of this map with entries from the specified map added or updated.
      Specified by:
      putAll in interface ImmutableMap<K,V>
      Specified by:
      putAll in interface ImmutableNavigableMap<K,V>
      Specified by:
      putAll in interface ImmutableSortedMap<K,V>
      Parameters:
      c - another map
      Returns:
      this map instance if it already contains the same entries, or a different map instance with the entries added or updated

    • putKeyValues

      public RedBlackMap<K,V> putKeyValues(Object... kv)
      Description copied from interface: ImmutableMap
      Returns a copy of this map that contains all entries of this map with entries from the specified map added or updated.
      Specified by:
      putKeyValues in interface ImmutableMap<K,V>
      Specified by:
      putKeyValues in interface ImmutableNavigableMap<K,V>
      Specified by:
      putKeyValues in interface ImmutableSortedMap<K,V>
      Parameters:
      kv - a list of alternating keys and values
      Returns:
      this map instance if it already contains the same entries, or a different map instance with the entries added or updated

    • removeAll

      public RedBlackMap<K,V> removeAll(Iterable<? extends K> c)
      Description copied from interface: ImmutableMap
      Returns a copy of this map that contains all entries of this map except the entries of the specified collection.
      Specified by:
      removeAll in interface ImmutableMap<K,V>
      Specified by:
      removeAll in interface ImmutableNavigableMap<K,V>
      Specified by:
      removeAll in interface ImmutableSortedMap<K,V>
      Parameters:
      c - a collection with keys of entries to be removed from this map
      Returns:
      this map instance if it already does not contain the entries, or a different map instance with the entries removed

    • retainAll

      public RedBlackMap<K,V> retainAll(Iterable<? extends K> c)
      Description copied from interface: ImmutableMap
      Returns a copy of this map that contains only entries that are in this map and in the specified collection.
      Specified by:
      retainAll in interface ImmutableMap<K,V>
      Specified by:
      retainAll in interface ImmutableNavigableMap<K,V>
      Specified by:
      retainAll in interface ImmutableSortedMap<K,V>
      Parameters:
      c - a collection with keys of entries to be retained in this map
      Returns:
      this map instance if it has not changed, or a different map instance with entries removed

    • retainAll

      public RedBlackMap<K,V> retainAll(ReadOnlyCollection<? extends K> c)
      Description copied from interface: ImmutableMap
      Returns a copy of this map that contains only entries that are in this map and in the specified collection.
      Specified by:
      retainAll in interface ImmutableMap<K,V>
      Specified by:
      retainAll in interface ImmutableNavigableMap<K,V>
      Specified by:
      retainAll in interface ImmutableSortedMap<K,V>
      Parameters:
      c - a collection with keys of entries to be retained in this map
      Returns:
      this map instance if it has not changed, or a different map instance with entries removed

    • copyOf

      public static <K, V> RedBlackMap<K,V> copyOf(Iterable<? extends Map.Entry<? extends K,? extends V>> c)
      Returns an immutable map that contains the provided elements sorted according to the natural ordering of its elements.
      Type Parameters:
      K - the key type
      V - the value type
      Parameters:
      c - an iterable
      Returns:
      an immutable map of the provided elements

    • copyOf

      public static <K, V> RedBlackMap<K,V> copyOf(Map<? extends K,? extends V> map)
      Returns an immutable copy of the provided map that contains the provided elements sorted according to the natural ordering of its elements.
      Type Parameters:
      K - the key type
      V - the value type
      Parameters:
      map - a map
      Returns:
      an immutable copy

    • sortedOf

      public static <K, V> RedBlackMap<K,V> sortedOf(@Nullable Comparator<? super K> comparator)
      Returns an empty immutable map, sorted according to the specified comparator.
      Type Parameters:
      K - the key type
      V - the value type
      Returns:
      an empty immutable map

    • sortedOf

      @SafeVarargs public static <K, V> RedBlackMap<K,V> sortedOf(@Nullable Comparator<? super K> comparator, Map.Entry<K,V> @Nullable ... elements)
      Returns an immutable map that contains the provided elements, sorted according to the specified comparator.
      Type Parameters:
      K - the key type
      V - the value type
      Parameters:
      elements - elements
      Returns:
      an immutable map of the provided elements

    • of

      public static <K, V> RedBlackMap<K,V> of()
      Returns an empty immutable map, sorted according to the natural ordering of its entries.
      Type Parameters:
      K - the key type
      V - the value type
      Returns:
      an empty immutable map

    • of

      @SafeVarargs public static <K, V> RedBlackMap<K,V> of(Map.Entry<K,V> @Nullable ... entries)
      Returns an immutable map that contains the provided entries, sorted according to the natural ordering of its entries.
      Type Parameters:
      K - the key type
      V - the value type
      Parameters:
      entries - entries
      Returns:
      an immutable map of the provided entries

    • ceilingEntry

      public @Nullable Map.Entry<K,V> ceilingEntry(K k)
      Description copied from interface: ReadOnlyNavigableMap
      Returns the least entry in this map with a key greater than or equal to the given key, or null if there is no such entry.
      Specified by:
      ceilingEntry in interface ReadOnlyNavigableMap<K,V>
      Parameters:
      k - the given key
      Returns:
      ceiling entry or null

    • comparator

      public @Nullable Comparator<? super K> comparator()
      Description copied from interface: ReadOnlySortedMap
      Returns the comparator used to order the keys in this map, or null if this set uses the natural ordering of its keys.
      Specified by:
      comparator in interface ReadOnlySortedMap<K,V>
      Returns:
      comparator or null

    • floorEntry

      public @Nullable Map.Entry<K,V> floorEntry(K k)
      Description copied from interface: ReadOnlyNavigableMap
      Returns the greatest entry in this map with a key less than or equal to the given key, or null if there is no such entry.
      Specified by:
      floorEntry in interface ReadOnlyNavigableMap<K,V>
      Parameters:
      k - the given key
      Returns:
      floor entry or null

    • higherEntry

      public @Nullable Map.Entry<K,V> higherEntry(K k)
      Description copied from interface: ReadOnlyNavigableMap
      Returns the least entry in this map with a key greater than the given key, or null if there is no such entry.
      Specified by:
      higherEntry in interface ReadOnlyNavigableMap<K,V>
      Parameters:
      k - the given key
      Returns:
      higher entry or null

    • lowerEntry

      public @Nullable Map.Entry<K,V> lowerEntry(K k)
      Description copied from interface: ReadOnlyNavigableMap
      Returns the greatest entry in this map with a key less than the given key, or null if there is no such entry.
      Specified by:
      lowerEntry in interface ReadOnlyNavigableMap<K,V>
      Parameters:
      k - the given key
      Returns:
      lower entry or null

    • firstEntry

      public @Nullable Map.Entry<K,V> firstEntry()
      Description copied from interface: ReadOnlySequencedMap
      Gets the first entry in this map or null if this map is empty.
      Specified by:
      firstEntry in interface ReadOnlySequencedMap<K,V>
      Returns:
      the first entry or null

    • lastEntry

      public @Nullable Map.Entry<K,V> lastEntry()
      Description copied from interface: ReadOnlySequencedMap
      Gets the last entry in this map or null if this map is empty.
      Specified by:
      lastEntry in interface ReadOnlySequencedMap<K,V>
      Returns:
      the last entry or null

    • clear

      public RedBlackMap<K,V> clear()
      Description copied from interface: ImmutableMap
      Returns a copy of this map that is empty.
      Specified by:
      clear in interface ImmutableMap<K,V>
      Specified by:
      clear in interface ImmutableNavigableMap<K,V>
      Specified by:
      clear in interface ImmutableSortedMap<K,V>
      Returns:
      this set instance if it is already empty, or a different set instance that is empty.

    • isEmpty

      public boolean isEmpty()
      Description copied from interface: ReadOnlyMap
      Returns true if this map contains no entries.
      Specified by:
      isEmpty in interface ReadOnlyMap<K,V>
      Returns:
      true if empty

    • readOnlyReversed

      public ReadOnlySequencedMap<K,V> readOnlyReversed()
      Description copied from interface: ReadOnlySequencedMap
      Returns a reversed-order view of this map.

      Changes to the underlying map are visible in the reversed view.

      Specified by:
      readOnlyReversed in interface ReadOnlySequencedMap<K,V>
      Returns:
      a reversed-order view of this map

    • size

      public int size()
      Description copied from interface: ReadOnlyMap
      Returns the number of entries contained in this map..
      Specified by:
      size in interface ReadOnlyMap<K,V>
      Returns:
      the number of entries

    • get

      public @Nullable V get(Object key)
      Description copied from interface: ReadOnlyMap
      Returns the value to which the key is mapped, or null if this map contains no entry for the key.
      Specified by:
      get in interface ReadOnlyMap<K,V>
      Parameters:
      key - a key
      Returns:
      the mapped value or null

    • containsKey

      public boolean containsKey(@Nullable Object key)
      Description copied from interface: ReadOnlyMap
      Returns true if this map contains a entry for the specified key.
      Specified by:
      containsKey in interface ReadOnlyMap<K,V>
      Parameters:
      key - a key
      Returns:
      true if this map contains a entry for the specified key

    • iterator

      public Iterator<Map.Entry<K,V>> iterator()
      Description copied from interface: ReadOnlyMap
      Returns an iterator over the entries contained in this map.
      Specified by:
      iterator in interface Iterable<K>
      Specified by:
      iterator in interface ReadOnlyMap<K,V>
      Returns:
      an iterator

    • put

      public RedBlackMap<K,V> put(K key, @Nullable V value)
      Description copied from interface: ImmutableMap
      Returns a copy of this map that contains all entries of this map with the specified entry added or updated.
      Specified by:
      put in interface ImmutableMap<K,V>
      Specified by:
      put in interface ImmutableNavigableMap<K,V>
      Specified by:
      put in interface ImmutableSortedMap<K,V>
      Parameters:
      key - the key of the entry
      value - the value of the entry
      Returns:
      this map instance if it already contains the same entry, or a different map instance with the entry added or updated

    • remove

      public RedBlackMap<K,V> remove(K key)
      Description copied from interface: ImmutableMap
      Returns a copy of this map that contains all entries of this map with the specified entry removed.
      Specified by:
      remove in interface ImmutableMap<K,V>
      Specified by:
      remove in interface ImmutableNavigableMap<K,V>
      Specified by:
      remove in interface ImmutableSortedMap<K,V>
      Parameters:
      key - the key of the entry
      Returns:
      this map instance if it already does not contain the entry, or a different map instance with the entry removed

    • toMutable

      public MutableRedBlackMap<K,V> toMutable()
      Description copied from interface: ImmutableMap
      Returns a mutable copy of this map.
      Specified by:
      toMutable in interface ImmutableMap<K,V>
      Returns:
      a mutable copy.

    • maxSize

      public int maxSize()
      Description copied from interface: ImmutableMap
      Returns the maximal number of entries that this map type can hold
      Specified by:
      maxSize in interface ImmutableMap<K,V>
      Returns:
      the maximal size

    • equals

      public boolean equals(Object o)
      Description copied from interface: ReadOnlyMap
      Compares the specified object with this map for equality.

      Returns true if the given object is also a read-only map and the two maps represent the same entries, ignorig the sequence of the map entries.

      Specified by:
      equals in interface ReadOnlyMap<K,V>
      Overrides:
      equals in class Object
      Parameters:
      o - an object
      Returns:
      true if the object is equal to this map

    • hashCode

      public int hashCode()
      Description copied from interface: ReadOnlyMap
      Returns the hash code value for this map. The hash code is the sum of the hash code of its entries.
      Specified by:
      hashCode in interface ReadOnlyMap<K,V>
      Overrides:
      hashCode in class Object
      Returns:
      the hash code value for this map
      See Also:

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • characteristics

      public int characteristics()
      Description copied from interface: ReadOnlySequencedMap
      Returns the spliterator characteristics of the key set. This implementation returns Spliterator.SIZED|Spliterator.DISTINCT.
      Specified by:
      characteristics in interface ReadOnlyMap<K,V>
      Specified by:
      characteristics in interface ReadOnlySequencedMap<K,V>
      Specified by:
      characteristics in interface ReadOnlySortedMap<K,V>
      Returns:
      characteristics.