com.jnape.palatable.lambda.adt.hmap

## Class HMap

- java.lang.Object
- - com.jnape.palatable.lambda.adt.hmap.HMap

- All Implemented Interfaces:
    Iterable<Tuple2<TypeSafeKey<?,?>,Object>>

      public final class HMap
      extends Object
      implements Iterable<Tuple2<TypeSafeKey<?,?>,Object>>

  An immutable heterogeneous mapping from a parametrized type-safe key to any value, supporting a minimal mapping interface.
  See Also:
    `TypeSafeKey`, `HList`

- - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `containsKey(TypeSafeKey<?,?> key)` Determine if a key is mapped.
    `<V> V` | `demand(TypeSafeKey<?,V> key)` Retrieve the value at this key, throwing a `NoSuchElementException` if this key is unmapped.
    `static HMap` | `emptyHMap()` Static factory method for creating an empty HMap.
    `boolean` | `equals(Object other)`
    `<A,B> Maybe<B>` | `get(TypeSafeKey<A,B> key)` Retrieve the value at this key.
    `int` | `hashCode()`
    `static <V1,V2> HMap` | `hMap(TypeSafeKey<?,V1> key1, V1 value1, TypeSafeKey<?,V2> key2, V2 value2)` Static factory method for creating an HMap from two given associations.
    `static <V1,V2,V3> HMap` | `hMap(TypeSafeKey<?,V1> key1, V1 value1, TypeSafeKey<?,V2> key2, V2 value2, TypeSafeKey<?,V3> key3, V3 value3)` Static factory method for creating an HMap from three given associations.
    `static <V1,V2,V3,V4> HMap` | `hMap(TypeSafeKey<?,V1> key1, V1 value1, TypeSafeKey<?,V2> key2, V2 value2, TypeSafeKey<?,V3> key3, V3 value3, TypeSafeKey<?,V4> key4, V4 value4)` Static factory method for creating an HMap from four given associations.
    `static <V1,V2,V3,V4,V5> HMap` | `hMap(TypeSafeKey<?,V1> key1, V1 value1, TypeSafeKey<?,V2> key2, V2 value2, TypeSafeKey<?,V3> key3, V3 value3, TypeSafeKey<?,V4> key4, V4 value4, TypeSafeKey<?,V5> key5, V5 value5)` Static factory method for creating an HMap from five given associations.
    `static <V1,V2,V3,V4,V5,V6> HMap` | `hMap(TypeSafeKey<?,V1> key1, V1 value1, TypeSafeKey<?,V2> key2, V2 value2, TypeSafeKey<?,V3> key3, V3 value3, TypeSafeKey<?,V4> key4, V4 value4, TypeSafeKey<?,V5> key5, V5 value5, TypeSafeKey<?,V6> key6, V6 value6)` Static factory method for creating an HMap from six given associations.
    `static <V1,V2,V3,V4,V5,V6,V7> HMap` | `hMap(TypeSafeKey<?,V1> key1, V1 value1, TypeSafeKey<?,V2> key2, V2 value2, TypeSafeKey<?,V3> key3, V3 value3, TypeSafeKey<?,V4> key4, V4 value4, TypeSafeKey<?,V5> key5, V5 value5, TypeSafeKey<?,V6> key6, V6 value6, TypeSafeKey<?,V7> key7, V7 value7)` Static factory method for creating an HMap from seven given associations.
    `static <V1,V2,V3,V4,V5,V6,V7,V8> HMap` | `hMap(TypeSafeKey<?,V1> key1, V1 value1, TypeSafeKey<?,V2> key2, V2 value2, TypeSafeKey<?,V3> key3, V3 value3, TypeSafeKey<?,V4> key4, V4 value4, TypeSafeKey<?,V5> key5, V5 value5, TypeSafeKey<?,V6> key6, V6 value6, TypeSafeKey<?,V7> key7, V7 value7, TypeSafeKey<?,V8> key8, V8 value8)` Static factory method for creating an HMap from eight given associations.
    `boolean` | `isEmpty()` Test whether this `HMap` is empty.
    `Iterator<Tuple2<TypeSafeKey<?,?>,Object>>` | `iterator()`
    `Set<TypeSafeKey<?,?>>` | `keys()` Retrieve all the mapped keys.
    `<V> HMap` | `put(TypeSafeKey<?,V> key, V value)` Store a value for the given key.
    `HMap` | `putAll(HMap hMap)` Store all the key/value mappings in `hMap` in this HMap.
    `HMap` | `remove(TypeSafeKey<?,?> key)` Remove a mapping from this HMap.
    `HMap` | `removeAll(HMap hMap)` Remove all the key/value mappings in `hMap` from this HMap.
    `static <V> HMap` | `singletonHMap(TypeSafeKey<?,V> key, V value)` Static factory method for creating a singleton HMap.
    `Map<TypeSafeKey<?,?>,Object>` | `toMap()` Return a standard `Map` view of the current snapshot of this `HMap`.
    `String` | `toString()`
    `Collection<Object>` | `values()` Retrieve all the mapped values.

    - ### Methods inherited from class java.lang.Object

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

    - ### Methods inherited from interface java.lang.Iterable

      `forEach, spliterator`

- - ### Method Detail

    - #### get

          public <A,B> Maybe<B> get(TypeSafeKey<A,B> key)

      Retrieve the value at this key.
      Type Parameters:
        `A` - the value type
        `B` - the value type
      Parameters:
        `key` - the key
      Returns:
        Maybe the value at this key

    - #### demand

          public <V> V demand(TypeSafeKey<?,V> key)
                       throws NoSuchElementException

      Retrieve the value at this key, throwing a `NoSuchElementException` if this key is unmapped.
      Type Parameters:
        `V` - the value type
      Parameters:
        `key` - the key
      Returns:
        the value at this key
      Throws:
        `NoSuchElementException` - if the key is unmapped

    - #### put

          public <V> HMap put(TypeSafeKey<?,V> key,
                              V value)

      Store a value for the given key.
      Type Parameters:
        `V` - the value type
      Parameters:
        `key` - the key
        `value` - the value
      Returns:
        the updated HMap

    - #### putAll

          public HMap putAll(HMap hMap)

      Store all the key/value mappings in `hMap` in this HMap.
      Parameters:
        `hMap` - the other HMap
      Returns:
        the updated HMap

    - #### containsKey

          public boolean containsKey(TypeSafeKey<?,?> key)

      Determine if a key is mapped.
      Parameters:
        `key` - the key
      Returns:
        true if the key is mapped; false otherwise

    - #### remove

          public HMap remove(TypeSafeKey<?,?> key)

      Remove a mapping from this HMap.
      Parameters:
        `key` - the key
      Returns:
        the updated HMap

    - #### removeAll

          public HMap removeAll(HMap hMap)

      Remove all the key/value mappings in `hMap` from this HMap.
      Parameters:
        `hMap` - the other HMap
      Returns:
        the updated HMap

    - #### isEmpty

          public boolean isEmpty()

      Test whether this `HMap` is empty.
      Returns:
        true if the `HMap` is empty; false otherwise.

    - #### keys

          public Set<TypeSafeKey<?,?>> keys()

      Retrieve all the mapped keys.

      Note that unlike with `Map.keySet()`, the resulting key set is not "live"; in fact that is, alterations to the resulting key set have no effect on the backing `HMap`.

      Returns:
        a `Set` of all the mapped keys

    - #### values

          public Collection<Object> values()

      Retrieve all the mapped values.
      Returns:
        a `List` of all the mapped values

    - #### toMap

          public Map<TypeSafeKey<?,?>,Object> toMap()

      Return a standard `Map` view of the current snapshot of this `HMap`. Note that updates to either the `Map` view or to the original `HMap` do not propagate to the other.
      Returns:
        the map view

    - #### iterator

          public Iterator<Tuple2<TypeSafeKey<?,?>,Object>> iterator()

      Specified by:
        `iterator` in interface `Iterable<Tuple2<TypeSafeKey<?,?>,Object>>`

    - #### equals

          public boolean equals(Object other)

      Overrides:
        `equals` in class `Object`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### emptyHMap

          public static HMap emptyHMap()

      Static factory method for creating an empty HMap.
      Returns:
        an empty HMap

    - #### singletonHMap

          public static <V> HMap singletonHMap(TypeSafeKey<?,V> key,
                                               V value)

      Static factory method for creating a singleton HMap.
      Type Parameters:
        `V` - the only mapped value type
      Parameters:
        `key` - the only mapped key
        `value` - the only mapped value
      Returns:
        a singleton HMap

    - #### hMap

          public static <V1,V2> HMap hMap(TypeSafeKey<?,V1> key1,
                                          V1 value1,
                                          TypeSafeKey<?,V2> key2,
                                          V2 value2)

      Static factory method for creating an HMap from two given associations.
      Type Parameters:
        `V1` - value1's type
        `V2` - value2's type
      Parameters:
        `key1` - the first mapped key
        `value1` - the value mapped at key1
        `key2` - the second mapped key
        `value2` - the value mapped at key2
      Returns:
        an HMap with the given associations

    - #### hMap

          public static <V1,V2,V3> HMap hMap(TypeSafeKey<?,V1> key1,
                                             V1 value1,
                                             TypeSafeKey<?,V2> key2,
                                             V2 value2,
                                             TypeSafeKey<?,V3> key3,
                                             V3 value3)

      Static factory method for creating an HMap from three given associations.
      Type Parameters:
        `V1` - value1's type
        `V2` - value2's type
        `V3` - value3's type
      Parameters:
        `key1` - the first mapped key
        `value1` - the value mapped at key1
        `key2` - the second mapped key
        `value2` - the value mapped at key2
        `key3` - the third mapped key
        `value3` - the value mapped at key3
      Returns:
        an HMap with the given associations

    - #### hMap

          public static <V1,V2,V3,V4> HMap hMap(TypeSafeKey<?,V1> key1,
                                                V1 value1,
                                                TypeSafeKey<?,V2> key2,
                                                V2 value2,
                                                TypeSafeKey<?,V3> key3,
                                                V3 value3,
                                                TypeSafeKey<?,V4> key4,
                                                V4 value4)

      Static factory method for creating an HMap from four given associations.
      Type Parameters:
        `V1` - value1's type
        `V2` - value2's type
        `V3` - value3's type
        `V4` - value4's type
      Parameters:
        `key1` - the first mapped key
        `value1` - the value mapped at key1
        `key2` - the second mapped key
        `value2` - the value mapped at key2
        `key3` - the third mapped key
        `value3` - the value mapped at key3
        `key4` - the fourth mapped key
        `value4` - the value mapped at key4
      Returns:
        an HMap with the given associations

    - #### hMap

          public static <V1,V2,V3,V4,V5> HMap hMap(TypeSafeKey<?,V1> key1,
                                                   V1 value1,
                                                   TypeSafeKey<?,V2> key2,
                                                   V2 value2,
                                                   TypeSafeKey<?,V3> key3,
                                                   V3 value3,
                                                   TypeSafeKey<?,V4> key4,
                                                   V4 value4,
                                                   TypeSafeKey<?,V5> key5,
                                                   V5 value5)

      Static factory method for creating an HMap from five given associations.
      Type Parameters:
        `V1` - value1's type
        `V2` - value2's type
        `V3` - value3's type
        `V4` - value4's type
        `V5` - value5's type
      Parameters:
        `key1` - the first mapped key
        `value1` - the value mapped at key1
        `key2` - the second mapped key
        `value2` - the value mapped at key2
        `key3` - the third mapped key
        `value3` - the value mapped at key3
        `key4` - the fourth mapped key
        `value4` - the value mapped at key4
        `key5` - the fifth mapped key
        `value5` - the value mapped at key5
      Returns:
        an HMap with the given associations

    - #### hMap

          public static <V1,V2,V3,V4,V5,V6> HMap hMap(TypeSafeKey<?,V1> key1,
                                                      V1 value1,
                                                      TypeSafeKey<?,V2> key2,
                                                      V2 value2,
                                                      TypeSafeKey<?,V3> key3,
                                                      V3 value3,
                                                      TypeSafeKey<?,V4> key4,
                                                      V4 value4,
                                                      TypeSafeKey<?,V5> key5,
                                                      V5 value5,
                                                      TypeSafeKey<?,V6> key6,
                                                      V6 value6)

      Static factory method for creating an HMap from six given associations.
      Type Parameters:
        `V1` - value1's type
        `V2` - value2's type
        `V3` - value3's type
        `V4` - value4's type
        `V5` - value5's type
        `V6` - value6's type
      Parameters:
        `key1` - the first mapped key
        `value1` - the value mapped at key1
        `key2` - the second mapped key
        `value2` - the value mapped at key2
        `key3` - the third mapped key
        `value3` - the value mapped at key3
        `key4` - the fourth mapped key
        `value4` - the value mapped at key4
        `key5` - the fifth mapped key
        `value5` - the value mapped at key5
        `key6` - the sixth mapped key
        `value6` - the value mapped at key6
      Returns:
        an HMap with the given associations

    - #### hMap

          public static <V1,V2,V3,V4,V5,V6,V7> HMap hMap(TypeSafeKey<?,V1> key1,
                                                         V1 value1,
                                                         TypeSafeKey<?,V2> key2,
                                                         V2 value2,
                                                         TypeSafeKey<?,V3> key3,
                                                         V3 value3,
                                                         TypeSafeKey<?,V4> key4,
                                                         V4 value4,
                                                         TypeSafeKey<?,V5> key5,
                                                         V5 value5,
                                                         TypeSafeKey<?,V6> key6,
                                                         V6 value6,
                                                         TypeSafeKey<?,V7> key7,
                                                         V7 value7)

      Static factory method for creating an HMap from seven given associations.
      Type Parameters:
        `V1` - value1's type
        `V2` - value2's type
        `V3` - value3's type
        `V4` - value4's type
        `V5` - value5's type
        `V6` - value6's type
        `V7` - value7's type
      Parameters:
        `key1` - the first mapped key
        `value1` - the value mapped at key1
        `key2` - the second mapped key
        `value2` - the value mapped at key2
        `key3` - the third mapped key
        `value3` - the value mapped at key3
        `key4` - the fourth mapped key
        `value4` - the value mapped at key4
        `key5` - the fifth mapped key
        `value5` - the value mapped at key5
        `key6` - the sixth mapped key
        `value6` - the value mapped at key6
        `key7` - the seventh mapped key
        `value7` - the value mapped at key7
      Returns:
        an HMap with the given associations

    - #### hMap

          public static <V1,V2,V3,V4,V5,V6,V7,V8> HMap hMap(TypeSafeKey<?,V1> key1,
                                                            V1 value1,
                                                            TypeSafeKey<?,V2> key2,
                                                            V2 value2,
                                                            TypeSafeKey<?,V3> key3,
                                                            V3 value3,
                                                            TypeSafeKey<?,V4> key4,
                                                            V4 value4,
                                                            TypeSafeKey<?,V5> key5,
                                                            V5 value5,
                                                            TypeSafeKey<?,V6> key6,
                                                            V6 value6,
                                                            TypeSafeKey<?,V7> key7,
                                                            V7 value7,
                                                            TypeSafeKey<?,V8> key8,
                                                            V8 value8)

      Static factory method for creating an HMap from eight given associations.
      Type Parameters:
        `V1` - value1's type
        `V2` - value2's type
        `V3` - value3's type
        `V4` - value4's type
        `V5` - value5's type
        `V6` - value6's type
        `V7` - value7's type
        `V8` - value8's type
      Parameters:
        `key1` - the first mapped key
        `value1` - the value mapped at key1
        `key2` - the second mapped key
        `value2` - the value mapped at key2
        `key3` - the third mapped key
        `value3` - the value mapped at key3
        `key4` - the fourth mapped key
        `value4` - the value mapped at key4
        `key5` - the fifth mapped key
        `value5` - the value mapped at key5
        `key6` - the sixth mapped key
        `value6` - the value mapped at key6
        `key7` - the seventh mapped key
        `value7` - the value mapped at key7
        `key8` - the eighth mapped key
        `value8` - the value mapped at key8
      Returns:
        an HMap with the given associations