com.jnape.palatable.lambda.adt.hlist

## Class Tuple2<_1,_2>

- java.lang.Object
- - com.jnape.palatable.lambda.adt.hlist.HList
  - - com.jnape.palatable.lambda.adt.hlist.HList.HCons<_1,SingletonHList<_2>>
    - - com.jnape.palatable.lambda.adt.hlist.Tuple2<_1,_2>

- Type Parameters:
    `_1` - The first slot element type
    `_2` - The second slot element type
  All Implemented Interfaces:
    Product2<_1,_2>, Applicative<_2,Tuple2<_1,?>>, Bifunctor<_1,_2,Tuple2<?,?>>, BoundedBifunctor<_1,_2,Object,Object,Tuple2<?,?>>, Functor<_2,Tuple2<_1,?>>, Monad<_2,Tuple2<_1,?>>, MonadRec<_2,Tuple2<_1,?>>, MonadWriter<_1,_2,Tuple2<_1,?>>, Traversable<_2,Tuple2<_1,?>>, Map.Entry<_1,_2>

      public class Tuple2<_1,_2>
      extends HList.HCons<_1,SingletonHList<_2>>
      implements Product2<_1,_2>, MonadRec<_2,Tuple2<_1,?>>, MonadWriter<_1,_2,Tuple2<_1,?>>, Bifunctor<_1,_2,Tuple2<?,?>>, Traversable<_2,Tuple2<_1,?>>

  A 2-element tuple product type, implemented as a specialized HList. Supports random access.
  See Also:
    `Product2`, `HList`, `SingletonHList`, `Tuple3`, `Tuple4`, `Tuple5`

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class com.jnape.palatable.lambda.adt.hlist.HList

      `HList.HCons<Head,Tail extends HList>, HList.HNil`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `_1` | `_1()` Retrieve the first element.
    `_2` | `_2()` Retrieve the second element.
    `<_1Prime,_2Prime> Tuple2<_1Prime,_2Prime>` | `biMap(Fn1<? super _1,? extends _1Prime> lFn, Fn1<? super _2,? extends _2Prime> rFn)` Dually map covariantly over both the left and right parameters.
    `<_1Prime> Tuple2<_1Prime,_2>` | `biMapL(Fn1<? super _1,? extends _1Prime> fn)` Covariantly map over the left parameter.
    `<_2Prime> Tuple2<_1,_2Prime>` | `biMapR(Fn1<? super _2,? extends _2Prime> fn)` Covariantly map over the right parameter.
    `Tuple2<_1,_2>` | `censor(Fn1<? super _1,? extends _1> fn)` Update the accumulated state.
    `<_0> Tuple3<_0,_1,_2>` | `cons(_0 _0)` Cons an element onto the front of this HList.
    `<_2Prime> Tuple2<_1,_2Prime>` | `discardL(Applicative<_2Prime,Tuple2<_1,?>> appB)` Sequence both this `Applicative` and `appB`, discarding this `Applicative's` result and returning `appB`.
    `<_2Prime> Tuple2<_1,_2>` | `discardR(Applicative<_2Prime,Tuple2<_1,?>> appB)` Sequence both this `Applicative` and `appB`, discarding `appB's` result and returning this `Applicative`.
    `static <A> Tuple2<A,A>` | `fill(A a)` Given a value of type `A`, produce an instance of this tuple with each slot set to that value.
    `<_2Prime> Tuple2<_1,_2Prime>` | `flatMap(Fn1<? super _2,? extends Monad<_2Prime,Tuple2<_1,?>>> f)` Chain dependent computations that may continue or short-circuit based on previous results.
    `<_2Prime> Tuple2<_1,_2Prime>` | `fmap(Fn1<? super _2,? extends _2Prime> fn)` Covariantly transmute this functor's parameter using the given mapping function.
    `static <K,V> Tuple2<K,V>` | `fromEntry(Map.Entry<K,V> entry)` Static factory method for creating `Tuple2`s from `Map.Entry`s.
    `static <A> Maybe<Tuple2<A,A>>` | `fromIterable(Iterable<A> as)` Return `just` the first two elements from the given `Iterable`, or `nothing` if there are less than two elements.
    `_1` | `getKey()`
    `_2` | `getValue()`
    `Tuple2<_2,_1>` | `invert()` Rotate the first two slots of this product.
    `<_2Prime> Lazy<Tuple2<_1,_2Prime>>` | `lazyZip(Lazy<? extends Applicative<Fn1<? super _2,? extends _2Prime>,Tuple2<_1,?>>> lazyAppFn)` Given a `lazy` instance of this applicative over a mapping function, "zip" the two instances together using whatever application semantics the current applicative supports.
    `<_3> Tuple2<_1,Tuple2<_2,_3>>` | `listens(Fn1<? super _1,? extends _3> fn)` Map the accumulation into a value and pair it with the current output.
    `<_2Prime> Tuple2<_1,_2Prime>` | `pure(_2Prime _2Prime)` Lift the value `b` into this applicative functor.
    `static <_1> Pure<Tuple2<_1,?>>` | `pureTuple(_1 _1)` The canonical `Pure` instance for `Tuple2`.
    `_2` | `setValue(_2 value)`
    `<_2Prime> Tuple2<_1,_2Prime>` | `trampolineM(Fn1<? super _2,? extends MonadRec<RecursiveResult<_2,_2Prime>,Tuple2<_1,?>>> fn)` Given some operation yielding a `RecursiveResult` inside this `MonadRec`, internally trampoline the operation until it yields a `termination` instruction.
    `<_2Prime,App extends Applicative<?,App>,TravB extends Traversable<_2Prime,Tuple2<_1,?>>,AppTrav extends Applicative<TravB,App>> AppTrav` | `traverse(Fn1<? super _2,? extends Applicative<_2Prime,App>> fn, Fn1<? super TravB,? extends AppTrav> pure)` Apply `fn` to each element of this traversable from left to right, and collapse the results into a single resulting applicative, potentially with the assistance of the applicative's pure function.
    `<_2Prime> Tuple2<_1,_2Prime>` | `zip(Applicative<Fn1<? super _2,? extends _2Prime>,Tuple2<_1,?>> appFn)` Given another instance of this applicative over a mapping function, "zip" the two instances together using whatever application semantics the current applicative supports.

    - ### Methods inherited from class com.jnape.palatable.lambda.adt.hlist.HList.HCons

      `equals, hashCode, head, tail`

    - ### Methods inherited from class com.jnape.palatable.lambda.adt.hlist.HList

      `cons, nil, singletonHList, toString, tuple, tuple, tuple, tuple, tuple, tuple, tuple`

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

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

    - ### Methods inherited from interface com.jnape.palatable.lambda.adt.product.Product2

      `into, product`

    - ### Methods inherited from interface java.util.Map.Entry

      `comparingByKey, comparingByKey, comparingByValue, comparingByValue, equals, hashCode`

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

      `join`

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

      `coerce`

- - ### Method Detail

    - #### listens

          public <_3> Tuple2<_1,Tuple2<_2,_3>> listens(Fn1<? super _1,? extends _3> fn)

      Map the accumulation into a value and pair it with the current output.
      Specified by:
        `listens` in interface `MonadWriter<_1,_2,Tuple2<_1,?>>`
      Type Parameters:
        `_3` - the mapped output
      Parameters:
        `fn` - the mapping function
      Returns:
        the updated `MonadWriter`

    - #### censor

          public Tuple2<_1,_2> censor(Fn1<? super _1,? extends _1> fn)

      Update the accumulated state.
      Specified by:
        `censor` in interface `MonadWriter<_1,_2,Tuple2<_1,?>>`
      Parameters:
        `fn` - the update function
      Returns:
        the updated `MonadWriter`

    - #### cons

          public <_0> Tuple3<_0,_1,_2> cons(_0 _0)

      Cons an element onto the front of this HList.
      Overrides:
        `cons` in class `HList.HCons<_1,SingletonHList<_2>>`
      Type Parameters:
        `_0` - the new head type
      Parameters:
        `_0` - the new head element
      Returns:
        the updated HList

    - #### _1

          public _1 _1()

      Retrieve the first element.
      Specified by:
        `_1` in interface `Product2<_1,_2>`
      Returns:
        the first element

    - #### _2

          public _2 _2()

      Retrieve the second element.
      Specified by:
        `_2` in interface `Product2<_1,_2>`
      Returns:
        the second element

    - #### getKey

          public _1 getKey()

      Specified by:
        `getKey` in interface `Product2<_1,_2>`
      Specified by:
        `getKey` in interface `Map.Entry<_1,_2>`

    - #### getValue

          public _2 getValue()

      Specified by:
        `getValue` in interface `Product2<_1,_2>`
      Specified by:
        `getValue` in interface `Map.Entry<_1,_2>`

    - #### setValue

          public _2 setValue(_2 value)

      Specified by:
        `setValue` in interface `Product2<_1,_2>`
      Specified by:
        `setValue` in interface `Map.Entry<_1,_2>`

    - #### invert

          public Tuple2<_2,_1> invert()

      Rotate the first two slots of this product.
      Specified by:
        `invert` in interface `Product2<_1,_2>`
      Returns:
        the rotated product

    - #### fmap

          public <_2Prime> Tuple2<_1,_2Prime> fmap(Fn1<? super _2,? extends _2Prime> fn)

      Covariantly transmute this functor's parameter using the given mapping function. Generally this method is specialized to return an instance of the class implementing Functor.
      Specified by:
        `fmap` in interface `Applicative<_2,Tuple2<_1,?>>`
      Specified by:
        `fmap` in interface `Functor<_2,Tuple2<_1,?>>`
      Specified by:
        `fmap` in interface `Monad<_2,Tuple2<_1,?>>`
      Specified by:
        `fmap` in interface `MonadRec<_2,Tuple2<_1,?>>`
      Specified by:
        `fmap` in interface `MonadWriter<_1,_2,Tuple2<_1,?>>`
      Specified by:
        `fmap` in interface `Traversable<_2,Tuple2<_1,?>>`
      Type Parameters:
        `_2Prime` - the new parameter type
      Parameters:
        `fn` - the mapping function
      Returns:
        a functor over B (the new parameter type)

    - #### biMapL

          public <_1Prime> Tuple2<_1Prime,_2> biMapL(Fn1<? super _1,? extends _1Prime> fn)

      Covariantly map over the left parameter.
      Specified by:
        `biMapL` in interface `Bifunctor<_1,_2,Tuple2<?,?>>`
      Specified by:
        `biMapL` in interface `BoundedBifunctor<_1,_2,Object,Object,Tuple2<?,?>>`
      Type Parameters:
        `_1Prime` - the new left parameter type
      Parameters:
        `fn` - the mapping function
      Returns:
        a bifunctor over C (the new left parameter) and B (the same right parameter)

    - #### biMapR

          public <_2Prime> Tuple2<_1,_2Prime> biMapR(Fn1<? super _2,? extends _2Prime> fn)

      Covariantly map over the right parameter. For all bifunctors that are also functors, it should hold that `biMapR(f) == fmap(f)`.
      Specified by:
        `biMapR` in interface `Bifunctor<_1,_2,Tuple2<?,?>>`
      Specified by:
        `biMapR` in interface `BoundedBifunctor<_1,_2,Object,Object,Tuple2<?,?>>`
      Type Parameters:
        `_2Prime` - the new right parameter type
      Parameters:
        `fn` - the mapping function
      Returns:
        a bifunctor over A (the same left parameter) and C (the new right parameter)

    - #### biMap

          public <_1Prime,_2Prime> Tuple2<_1Prime,_2Prime> biMap(Fn1<? super _1,? extends _1Prime> lFn,
                                                                 Fn1<? super _2,? extends _2Prime> rFn)

      Dually map covariantly over both the left and right parameters. This is isomorphic to `biMapL(lFn).biMapR(rFn)`.
      Specified by:
        `biMap` in interface `Bifunctor<_1,_2,Tuple2<?,?>>`
      Specified by:
        `biMap` in interface `BoundedBifunctor<_1,_2,Object,Object,Tuple2<?,?>>`
      Type Parameters:
        `_1Prime` - the new left parameter type
        `_2Prime` - the new right parameter type
      Parameters:
        `lFn` - the left parameter mapping function
        `rFn` - the right parameter mapping function
      Returns:
        a bifunctor over C (the new left parameter type) and D (the new right parameter type)

    - #### pure

          public <_2Prime> Tuple2<_1,_2Prime> pure(_2Prime _2Prime)

      Lift the value `b` into this applicative functor.
      Specified by:
        `pure` in interface `Applicative<_2,Tuple2<_1,?>>`
      Specified by:
        `pure` in interface `Monad<_2,Tuple2<_1,?>>`
      Specified by:
        `pure` in interface `MonadRec<_2,Tuple2<_1,?>>`
      Specified by:
        `pure` in interface `MonadWriter<_1,_2,Tuple2<_1,?>>`
      Type Parameters:
        `_2Prime` - the type of the returned applicative's parameter
      Parameters:
        `_2Prime` - the value
      Returns:
        an instance of this applicative over b

    - #### zip

          public <_2Prime> Tuple2<_1,_2Prime> zip(Applicative<Fn1<? super _2,? extends _2Prime>,Tuple2<_1,?>> appFn)

      Given another instance of this applicative over a mapping function, "zip" the two instances together using whatever application semantics the current applicative supports.
      Specified by:
        `zip` in interface `Applicative<_2,Tuple2<_1,?>>`
      Specified by:
        `zip` in interface `Monad<_2,Tuple2<_1,?>>`
      Specified by:
        `zip` in interface `MonadRec<_2,Tuple2<_1,?>>`
      Specified by:
        `zip` in interface `MonadWriter<_1,_2,Tuple2<_1,?>>`
      Type Parameters:
        `_2Prime` - the resulting applicative parameter type
      Parameters:
        `appFn` - the other applicative instance
      Returns:
        the mapped applicative

    - #### lazyZip

          public <_2Prime> Lazy<Tuple2<_1,_2Prime>> lazyZip(Lazy<? extends Applicative<Fn1<? super _2,? extends _2Prime>,Tuple2<_1,?>>> lazyAppFn)

      Given a `lazy` instance of this applicative over a mapping function, "zip" the two instances together using whatever application semantics the current applicative supports. This is useful for applicatives that support lazy evaluation and early termination.
      Specified by:
        `lazyZip` in interface `Applicative<_2,Tuple2<_1,?>>`
      Specified by:
        `lazyZip` in interface `Monad<_2,Tuple2<_1,?>>`
      Specified by:
        `lazyZip` in interface `MonadRec<_2,Tuple2<_1,?>>`
      Specified by:
        `lazyZip` in interface `MonadWriter<_1,_2,Tuple2<_1,?>>`
      Type Parameters:
        `_2Prime` - the resulting applicative parameter type
      Parameters:
        `lazyAppFn` - the lazy other applicative instance
      Returns:
        the mapped applicative
      See Also:
        `Maybe`, `Either`

    - #### discardL

          public <_2Prime> Tuple2<_1,_2Prime> discardL(Applicative<_2Prime,Tuple2<_1,?>> appB)

      Sequence both this `Applicative` and `appB`, discarding this `Applicative's` result and returning `appB`. This is generally useful for sequentially performing side-effects.
      Specified by:
        `discardL` in interface `Applicative<_2,Tuple2<_1,?>>`
      Specified by:
        `discardL` in interface `Monad<_2,Tuple2<_1,?>>`
      Specified by:
        `discardL` in interface `MonadRec<_2,Tuple2<_1,?>>`
      Specified by:
        `discardL` in interface `MonadWriter<_1,_2,Tuple2<_1,?>>`
      Type Parameters:
        `_2Prime` - the type of the returned Applicative's parameter
      Parameters:
        `appB` - the other Applicative
      Returns:
        appB

    - #### discardR

          public <_2Prime> Tuple2<_1,_2> discardR(Applicative<_2Prime,Tuple2<_1,?>> appB)

      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<_2,Tuple2<_1,?>>`
      Specified by:
        `discardR` in interface `Monad<_2,Tuple2<_1,?>>`
      Specified by:
        `discardR` in interface `MonadRec<_2,Tuple2<_1,?>>`
      Specified by:
        `discardR` in interface `MonadWriter<_1,_2,Tuple2<_1,?>>`
      Type Parameters:
        `_2Prime` - the type of appB's parameter
      Parameters:
        `appB` - the other Applicative
      Returns:
        this Applicative

    - #### flatMap

          public <_2Prime> Tuple2<_1,_2Prime> flatMap(Fn1<? super _2,? extends Monad<_2Prime,Tuple2<_1,?>>> f)

      Chain dependent computations that may continue or short-circuit based on previous results.
      Specified by:
        `flatMap` in interface `Monad<_2,Tuple2<_1,?>>`
      Specified by:
        `flatMap` in interface `MonadRec<_2,Tuple2<_1,?>>`
      Specified by:
        `flatMap` in interface `MonadWriter<_1,_2,Tuple2<_1,?>>`
      Type Parameters:
        `_2Prime` - the resulting monad parameter type
      Parameters:
        `f` - the dependent computation over A
      Returns:
        the new monad instance

    - #### trampolineM

          public <_2Prime> Tuple2<_1,_2Prime> trampolineM(Fn1<? super _2,? extends MonadRec<RecursiveResult<_2,_2Prime>,Tuple2<_1,?>>> fn)

      Given some operation yielding a `RecursiveResult` inside this `MonadRec`, internally trampoline the operation until it yields a `termination` instruction.

      Stack-safety depends on implementations guaranteeing that the growth of the call stack is a constant factor independent of the number of invocations of the operation. For various examples of how this can be achieved in stereotypical circumstances, see the referenced types.

      Specified by:
        `trampolineM` in interface `MonadRec<_2,Tuple2<_1,?>>`
      Type Parameters:
        `_2Prime` - the ultimate resulting carrier type
      Parameters:
        `fn` - the function to internally trampoline
      Returns:
        the trampolined `MonadRec`
      See Also:
        `for a basic implementation`, `for a {@link CoProduct2 coproduct} implementation`, `for an implementation leveraging an already stack-safe {@link Monad#flatMap(Fn1)}`, `for a {@link MonadT monad transformer} implementation`

    - #### traverse

          public <_2Prime,App extends Applicative<?,App>,TravB extends Traversable<_2Prime,Tuple2<_1,?>>,AppTrav extends Applicative<TravB,App>> AppTrav traverse(Fn1<? super _2,? extends Applicative<_2Prime,App>> fn,
                                                                                                                                                                  Fn1<? super TravB,? extends AppTrav> pure)

      Apply `fn` to each element of this traversable from left to right, and collapse the results into a single resulting applicative, potentially with the assistance of the applicative's pure function.
      Specified by:
        `traverse` in interface `Traversable<_2,Tuple2<_1,?>>`
      Type Parameters:
        `_2Prime` - the resulting element type
        `App` - the result applicative type
        `TravB` - this Traversable instance over B
        `AppTrav` - the full inferred resulting type from the traversal
      Parameters:
        `fn` - the function to apply
        `pure` - the applicative pure function
      Returns:
        the traversed Traversable, wrapped inside an applicative

    - #### fromEntry

          public static <K,V> Tuple2<K,V> fromEntry(Map.Entry<K,V> entry)

      Static factory method for creating `Tuple2`s from `Map.Entry`s.
      Type Parameters:
        `K` - the key parameter type, and first (head) element type
        `V` - the value parameter type, and second element type
      Parameters:
        `entry` - the map entry
      Returns:
        the newly created Tuple2

    - #### fill

          public static <A> Tuple2<A,A> fill(A a)

      Given a value of type `A`, produce an instance of this tuple with each slot set to that value.
      Type Parameters:
        `A` - the value type
      Parameters:
        `a` - the value to fill the tuple with
      Returns:
        the filled tuple

    - #### fromIterable

          public static <A> Maybe<Tuple2<A,A>> fromIterable(Iterable<A> as)

      Return `just` the first two elements from the given `Iterable`, or `nothing` if there are less than two elements.
      Type Parameters:
        `A` - the `Iterable` element type
      Parameters:
        `as` - the `Iterable`
      Returns:
        `Maybe` the first two elements of the given `Iterable`

    - #### pureTuple

          public static <_1> Pure<Tuple2<_1,?>> pureTuple(_1 _1)

      The canonical `Pure` instance for `Tuple2`.
      Type Parameters:
        `_1` - the head element type
      Parameters:
        `_1` - the head element
      Returns:
        the `Pure` instance