Package org.javimmutable.collections

Interface IMap<K,V>

All Superinterfaces:
ICollection<IMapEntry<K,V>>, InvariantCheckable, IStreamable<IMapEntry<K,V>>, Iterable<IMapEntry<K,V>>, Mapped<K,V>, Serializable, SplitableIterable<IMapEntry<K,V>>
All Known Implementing Classes:
AbstractMap, EmptyHashMap, HashMap, OrderedMap, TreeMap
@Immutable public interface IMap<K,V> extends ICollection<IMapEntry<K,V>>, Mapped<K,V>, InvariantCheckable, Serializable
Interface for immutable data structures that allow storage and retrieval of key/value pairs. null is always an allowed value within the map but is not an allowed key.

  • Method Details

    • insert

      @Nonnull IMap<K,V> insert(@Nonnull IMapEntry<K,V> value)
      Add key/value entry to the map, replacing any existing entry with same key.
      Specified by:
      insert in interface ICollection<K>

    • insertAll

      @Nonnull default IMap<K,V> insertAll(@Nonnull Iterable<? extends IMapEntry<K,V>> values)
      Adds the values to the end of the list in the same order they appear in the Iterable. May be invoked on an empty list.
      Specified by:
      insertAll in interface ICollection<K>
      Returns:
      instance of list containing the collection

    • insertAll

      @Nonnull default IMap<K,V> insertAll(@Nonnull Iterator<? extends IMapEntry<K,V>> values)
      Adds the values to the end of the list in the same order they appear in the Iterable. May be invoked on an empty list.
      Specified by:
      insertAll in interface ICollection<K>
      Returns:
      instance of list containing the collection

    • find

      @Nonnull Maybe<V> find(@Nonnull K key)
      Search for a value within the map and return a Holder indicating if the value was found and, if it was found, the value itself. Holder allows null values to be returned unambiguously.
      Specified by:
      find in interface Mapped<K,V>
      Parameters:
      key - non-null key to search for
      Returns:
      empty Holder if not found, otherwise filled Holder with value

    • findEntry

      @Nonnull Maybe<IMapEntry<K,V>> findEntry(@Nonnull K key)
      Search for an Entry within the map and return a Holder indicating if the Entry was found and, if it was found, the Entry itself.
      Parameters:
      key - non-null key to search for
      Returns:
      empty Holder if not found, otherwise filled Holder with Entry

    • assign

      @Nonnull IMap<K,V> assign(@Nonnull K key, V value)
      Sets the value associated with a specific key. Key must be non-null but value can be null. If the key already has a value in the map the old value is discarded and the new value is stored in its place. Returns a new IMap reflecting any changes. The original map is always left unchanged.
      Parameters:
      key - non-null key
      value - possibly null value
      Returns:
      new map reflecting the change

    • assignAll

      @Nonnull IMap<K,V> assignAll(@Nonnull IMap<? extends K,? extends V> map)
      Copies all key-value pairs from the given map. The map itself and its keys must be nonnull, but values can be null. If a key already has a value in the map, the old value is replaced with the new value. Returns a new IMap with the changes.
      Parameters:
      map - IMap to take values from
      Returns:
      new map reflecting the change

    • assignAll

      @Nonnull IMap<K,V> assignAll(@Nonnull Map<? extends K,? extends V> map)
      Copies all key-value pairs from the given map. The map itself and its keys must be nonnull, but values can be null. If a key already has a value in the map, the old value is replaced with the new value. Returns a new IMap with the changes.
      Parameters:
      map - Map to take values from
      Returns:
      new map reflecting the change

    • delete

      @Nonnull IMap<K,V> delete(@Nonnull K key)
      Deletes the entry for the specified key (if any). Returns a new map if the value was deleted or the current map if the key was not contained in the map.
      Parameters:
      key - non-null key
      Returns:
      same or different map depending on whether key was removed

    • deleteAll

      @Nonnull IMap<K,V> deleteAll()
      Specified by:
      deleteAll in interface ICollection<K>
      Returns:
      an equivalent collection with no values

    • getMap

      @Nonnull Map<K,V> getMap()
      Creates an unmodifiable java.util.Map reflecting the values of this IMap.
      Returns:
      Map view of this IMap

    • keys

      @Nonnull IStreamable<K> keys()
      Creates an IStreamable to access all of the Map's keys.

    • values

      @Nonnull IStreamable<V> values()
      Creates an IStreamable to access all of the Map's values.

    • mapBuilder

      @Nonnull IMapBuilder<K,V> mapBuilder()
      Creates a Builder with the same type signature as this Map.

    • mapCollector

      @Nonnull default java.util.stream.Collector<IMapEntry<K,V>,?,IMap<K,V>> mapCollector()
      Returns a Collector that creates a set of the same type as this containing all of the collected values inserted over whatever starting values this already contained.

    • update

      @Nonnull default IMap<K,V> update(@Nonnull K key, @Nonnull Func1<Maybe<V>,V> generator)
      Update the value at the key. A Holder containing the value currently stored at the key, or an empty Holder if the key is not currently bound, is passed to the generator function.
      Parameters:
      key - non-null key
      generator - function to call with current value to create value if key is already bound
      Returns:
      new map with changes applied

    • forEach

      default void forEach(@Nonnull Proc2<K,V> proc)
      Processes every key/value pair in this map using the provided function.

    • forEachThrows

      default <E extends Exception> void forEachThrows(@Nonnull Proc2Throws<K,V,E> proc) throws E
      Processes every key/value pair in this map using the provided function.
      Throws:
      E

    • reduce

      default <R> R reduce(R sum, @Nonnull Sum2<K,V,R> proc)
      Processes every key value pair in this map using the provided function to produce a value.
      Type Parameters:
      R - type of the sum
      Parameters:
      sum - initial value for process (used with first key/value pair of map)
      proc - function to combine a sum with a key value pair to produce a new sum
      Returns:
      final value (or initial value if this map is empty)

    • reduceThrows

      default <R, E extends Exception> R reduceThrows(R sum, @Nonnull Sum2Throws<K,V,R,E> proc) throws E
      Processes every key value pair in this map using the provided function to produce a value.
      Type Parameters:
      R - type of the sum
      E - type of the Exception thrown by the function
      Parameters:
      sum - initial value for process (used with first key/value pair of map)
      proc - function to combine a sum with a key value pair to produce a new sum
      Returns:
      final value (or initial value if this map is empty)
      Throws:
      E

    • select

      @Nonnull IMap<K,V> select(@Nonnull java.util.function.BiPredicate<K,V> predicate)
      Returns a map of the same type as this containing only those elements for which predicate returns true. Implementations are optimized assuming predicate will return false more often than true.
      Parameters:
      predicate - decides whether to include an element
      Returns:
      map of same type as this containing only those elements for which predicate returns true

    • reject

      @Nonnull IMap<K,V> reject(@Nonnull java.util.function.BiPredicate<K,V> predicate)
      Returns a map of the same type as this containing all those elements for which predicate returns false. Implementations can be optimized assuming predicate will return false more often than true.
      Parameters:
      predicate - decides whether to include an element
      Returns:
      map of same type as this containing only those elements for which predicate returns false