com.jnape.palatable.lambda.optics.lenses

## Class MapLens

- java.lang.Object
- - com.jnape.palatable.lambda.optics.lenses.MapLens

-     public final class MapLens
      extends Object

  Lenses that operate on `Map`s.

- - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static <K,V> Lens.Simple<Map<K,V>,Map<K,V>>` | `asCopy()` A lens that focuses on a copy of a Map.
    `static <M extends Map<K,V>,K,V> Lens<Map<K,V>,M,M,M>` | `asCopy(Fn1<? super Map<K,V>,? extends M> copyFn)` A lens that focuses on a copy of a `Map` as a subtype `M`.
    `static <K,V> Lens.Simple<Map<K,V>,Map<V,K>>` | `inverted()` A lens that focuses on the inverse of a map (keys and values swapped).
    `static <K,V> Lens.Simple<Map<K,V>,Set<K>>` | `keys()` A lens that focuses on the keys of a map.
    `static <K,V,V2> Lens.Simple<Map<K,V>,Map<K,V2>>` | `mappingValues(Iso<V,V,V2,V2> iso)` A lens that focuses on a map while mapping its values with the mapping `Iso`.
    `static <M extends Map<K,V>,K,V> Lens<Map<K,V>,M,Maybe<V>,Maybe<V>>` | `valueAt(Fn1<? super Map<K,V>,? extends M> copyFn, K k)` A lens that focuses on a value at a key in a map, as a `Maybe`, and produces a subtype `M` on the way back out.
    `static <K,V> Lens.Simple<Map<K,V>,Maybe<V>>` | `valueAt(K k)` A lens that focuses on a value at a key in a map, as a `Maybe`.
    `static <K,V> Lens.Simple<Map<K,V>,V>` | `valueAt(K k, V defaultValue)` A lens that focuses on a value at a key in a map, falling back to `defaultV` if the value is missing.
    `static <K,V> Lens.Simple<Map<K,V>,Collection<V>>` | `values()` A lens that focuses on the values of a map.

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

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### asCopy

          public static <M extends Map<K,V>,K,V> Lens<Map<K,V>,M,M,M> asCopy(Fn1<? super Map<K,V>,? extends M> copyFn)

      A lens that focuses on a copy of a `Map` as a subtype `M`. Useful for composition to avoid mutating a map reference.
      Type Parameters:
        `M` - the map subtype
        `K` - the key type
        `V` - the value type
      Parameters:
        `copyFn` - the copy function
      Returns:
        a lens that focuses on copies of maps as a specific subtype

    - #### asCopy

          public static <K,V> Lens.Simple<Map<K,V>,Map<K,V>> asCopy()

      A lens that focuses on a copy of a Map. Useful for composition to avoid mutating a map reference.
      Type Parameters:
        `K` - the key type
        `V` - the value type
      Returns:
        a lens that focuses on copies of maps

    - #### valueAt

          public static <M extends Map<K,V>,K,V> Lens<Map<K,V>,M,Maybe<V>,Maybe<V>> valueAt(Fn1<? super Map<K,V>,? extends M> copyFn,
                                                                                            K k)

      A lens that focuses on a value at a key in a map, as a `Maybe`, and produces a subtype `M` on the way back out.
      Type Parameters:
        `M` - the map subtype
        `K` - the key type
        `V` - the value type
      Parameters:
        `copyFn` - the copy function
        `k` - the key to focus on
      Returns:
        a lens that focuses on the value at key, as a `Maybe`

    - #### valueAt

          public static <K,V> Lens.Simple<Map<K,V>,Maybe<V>> valueAt(K k)

      A lens that focuses on a value at a key in a map, as a `Maybe`.
      Type Parameters:
        `K` - the key type
        `V` - the value type
      Parameters:
        `k` - the key to focus on
      Returns:
        a lens that focuses on the value at key, as a `Maybe`

    - #### valueAt

          public static <K,V> Lens.Simple<Map<K,V>,V> valueAt(K k,
                                                              V defaultValue)

      A lens that focuses on a value at a key in a map, falling back to `defaultV` if the value is missing.

      Note that this lens is NOT lawful, since "putting back what you got changes nothing" fails for any value `B` where `S` is the empty map

      Type Parameters:
        `K` - the key type
        `V` - the value type
      Parameters:
        `k` - the key to focus on
        `defaultValue` - the default value to use in case of a missing value at key
      Returns:
        a lens that focuses on the value at the key

    - #### keys

          public static <K,V> Lens.Simple<Map<K,V>,Set<K>> keys()

      A lens that focuses on the keys of a map.
      Type Parameters:
        `K` - the key type
        `V` - the value type
      Returns:
        a lens that focuses on the keys of a map

    - #### values

          public static <K,V> Lens.Simple<Map<K,V>,Collection<V>> values()

      A lens that focuses on the values of a map. In the case of updating the map, only the entries with a value listed in the update collection of values are kept.

      Note that this lens is NOT lawful, since "you get back what you put in" fails for all values `B` that represent a non-surjective superset of the existing values in `S`.

      Type Parameters:
        `K` - the key type
        `V` - the value type
      Returns:
        a lens that focuses on the values of a map

    - #### inverted

          public static <K,V> Lens.Simple<Map<K,V>,Map<V,K>> inverted()

      A lens that focuses on the inverse of a map (keys and values swapped). In the case of multiple equal values becoming keys, the last one wins.

      Note that this lens is very likely to NOT be lawful, since "you get back what you put in" will fail for any keys that map to the same value.

      Type Parameters:
        `K` - the key type
        `V` - the value type
      Returns:
        a lens that focuses on the inverse of a map

    - #### mappingValues

          public static <K,V,V2> Lens.Simple<Map<K,V>,Map<K,V2>> mappingValues(Iso<V,V,V2,V2> iso)

      A lens that focuses on a map while mapping its values with the mapping `Iso`.

      Note that for this lens to be lawful, `iso` must be lawful.

      Type Parameters:
        `K` - the key type
        `V` - the unfocused map value type
        `V2` - the focused map value type
      Parameters:
        `iso` - the mapping `Iso`
      Returns:
        a lens that focuses on a map while mapping its values