com.jnape.palatable.lambda.adt.hmap

## Interface TypeSafeKey<A,B>

- Type Parameters:
    `A` - The raw type of the value that this key maps to inside an `HMap`
    `B` - The mapped type of the value that this key maps to inside an `HMap`
  All Superinterfaces:
    Applicative<A,Iso<A,?,B,B>>, Contravariant<A,Profunctor<?,A,Iso<?,?,B,B>>>, Functor<A,Iso<A,?,B,B>>, Iso<A,A,B,B>, Iso.Simple<A,B>, Monad<A,Iso<A,?,B,B>>, MonadRec<A,Iso<A,?,B,B>>, Optic<Profunctor<?,?,?>,Functor<?,?>,A,A,B,B>, Optic.Simple<Profunctor<?,?,?>,Functor<?,?>,A,B>, Profunctor<A,A,Iso<?,?,B,B>>
  All Known Subinterfaces:
    TypeSafeKey.Simple<A>

      public interface TypeSafeKey<A,B>
      extends Iso.Simple<A,B>

  An interface representing a parametrized key for use in `HMap`s. Additionally, every `TypeSafeKey` is an `Iso` from the type the value is stored as to the type it's viewed and set as (on the way in / on the way out). This allows multiple keys to map to the same value, but to view the value as different types.

  This is intentionally an interface so user-defined implementations are possible; however, it's important to note that all hopes of type-safety hinge on equality being implemented such that no two `TypeSafeKey`s with differing value-type parameters may be considered equal. Reference equality is used here as the default, as that is sufficient.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static interface` | `TypeSafeKey.Simple<A>` A simplified `TypeSafeKey` that can only view a value of type `A` as an `A`.

  - ### Method Summary

    All Methods Static Methods Instance Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `default <C> TypeSafeKey<A,C>` | `andThen(Iso.Simple<B,C> f)` Left-to-right composition of this `TypeSafeKey` with some other `Iso`.
    `default <U> TypeSafeKey<A,B>` | `discardR(Applicative<U,Iso<A,?,B,B>> appB)` Sequence both this `Applicative` and `appB`, discarding `appB's` result and returning this `Applicative`.
    `static <A> TypeSafeKey.Simple<A>` | `typeSafeKey()` Static factory method for creating a simple type-safe key

    - ### Methods inherited from interface com.jnape.palatable.lambda.optics.Iso.Simple

      `adapt, andThen, compose, compose, mirror, toLens`

    - ### Methods inherited from interface com.jnape.palatable.lambda.optics.Iso

      `andThen, compose, contraMap, diMap, diMapL, diMapR, discardL, flatMap, fmap, iso, iso, mapA, mapB, mapS, mapT, pure, pureIso, simpleIso, trampolineM, unIso, zip`

    - ### Methods inherited from interface com.jnape.palatable.lambda.monad.MonadRec

      `lazyZip`

    - ### Methods inherited from interface com.jnape.palatable.lambda.monad.Monad

      `join`

    - ### Methods inherited from interface com.jnape.palatable.lambda.functor.Functor

      `coerce`

    - ### Methods inherited from interface com.jnape.palatable.lambda.optics.Optic.Simple

      `adapt`

    - ### Methods inherited from interface com.jnape.palatable.lambda.optics.Optic

      `apply, monomorphize, optic, reframe`

- - ### Method Detail

    - #### discardR

          default <U> TypeSafeKey<A,B> discardR(Applicative<U,Iso<A,?,B,B>> appB)

      Description copied from interface: `Iso.Simple`
      Sequence both this `Applicative` and `appB`, discarding `appB's` result and returning this `Applicative`. This is generally useful for sequentially performing side-effects.
      Specified by:
        `discardR` in interface `Applicative<A,Iso<A,?,B,B>>`
      Specified by:
        `discardR` in interface `Iso<A,A,B,B>`
      Specified by:
        `discardR` in interface `Iso.Simple<A,B>`
      Specified by:
        `discardR` in interface `Monad<A,Iso<A,?,B,B>>`
      Specified by:
        `discardR` in interface `MonadRec<A,Iso<A,?,B,B>>`
      Type Parameters:
        `U` - the type of appB's parameter
      Parameters:
        `appB` - the other Applicative
      Returns:
        this Applicative

    - #### andThen

          default <C> TypeSafeKey<A,C> andThen(Iso.Simple<B,C> f)

      Left-to-right composition of this `TypeSafeKey` with some other `Iso`. Because the first parameter fundamentally represents an already stored value type, this is the only composition that is possible for `TypeSafeKey`, which is why only this (and not `Iso.compose(Optic)`) is overridden.

      Particularly of note is the fact that values stored at this key are still stored as their original manifest type, and are not duplicated - which is to say, putting a value at a key, yielding a new key via composition, and putting a new value at the new key still only results in a single entry in the `HMap`. Additionally, all previous keys involved in the new key's composition are still able to resolve the value in their native type.

      Specified by:
        `andThen` in interface `Iso.Simple<A,B>`
      Type Parameters:
        `C` - the new value type
      Parameters:
        `f` - the other simple iso
      Returns:
        the new `TypeSafeKey`

    - #### typeSafeKey

          static <A> TypeSafeKey.Simple<A> typeSafeKey()

      Static factory method for creating a simple type-safe key
      Type Parameters:
        `A` - the type of value stored at this key
      Returns:
        a unique type-safe key