Backport #3076 Add Align typeclass

.gitignore

@@ -17,6 +17,7 @@ TAGS
 .idea/*
 .idea_modules
 .DS_Store
+.vscode
 .sbtrc
 *.sublime-project
 *.sublime-workspace

binCompatTest/src/main/scala/catsBC/MimaExceptions.scala

@@ -1,4 +1,5 @@
 package catsBC
+import cats.InjectK
 import cats.implicits._
 
 object MimaExceptions {
@@ -27,6 +28,12 @@ object MimaExceptions {
     true.iterateUntilM(Option(_))(identity _),
     Either.catchOnly[NumberFormatException] { "foo".toInt },
     (1.validNel[String], 2.validNel[String], 3.validNel[String]) mapN (_ + _ + _),
-    (1.asRight[String], 2.asRight[String], 3.asRight[String]) parMapN (_ + _ + _)
+    (1.asRight[String], 2.asRight[String], 3.asRight[String]) parMapN (_ + _ + _),
+    InjectK.catsReflexiveInjectKInstance[Option],
+    (
+      cats.Bimonad[cats.data.NonEmptyChain],
+      cats.NonEmptyTraverse[cats.data.NonEmptyChain],
+      cats.SemigroupK[cats.data.NonEmptyChain]
+    )
   )
 }

core/src/main/scala/cats/Align.scala

@@ -0,0 +1,90 @@
+package cats
+
+import simulacrum.typeclass
+
+import cats.data.Ior
+
+/**
+ * `Align` supports zipping together structures with different shapes,
+ * holding the results from either or both structures in an `Ior`.
+ *
+ * Must obey the laws in cats.laws.AlignLaws
+ */
+@typeclass trait Align[F[_]] {
+
+  def functor: Functor[F]
+
+  /**
+   * Pairs elements of two structures along the union of their shapes, using `Ior` to hold the results.
+   *
+   * Example:
+   * {{{
+   * scala> import cats.implicits._
+   * scala> import cats.data.Ior
+   * scala> Align[List].align(List(1, 2), List(10, 11, 12))
+   * res0: List[Ior[Int, Int]] = List(Both(1,10), Both(2,11), Right(12))
+   * }}}
+   */
+  def align[A, B](fa: F[A], fb: F[B]): F[Ior[A, B]]
+
+  /**
+   * Combines elements similarly to `align`, using the provided function to compute the results.
+   *
+   * Example:
+   * {{{
+   * scala> import cats.implicits._
+   * scala> Align[List].alignWith(List(1, 2), List(10, 11, 12))(_.mergeLeft)
+   * res0: List[Int] = List(1, 2, 12)
+   * }}}
+   */
+  def alignWith[A, B, C](fa: F[A], fb: F[B])(f: Ior[A, B] => C): F[C] =
+    functor.map(align(fa, fb))(f)
+
+  /**
+   * Align two structures with the same element, combining results according to their semigroup instances.
+   *
+   * Example:
+   * {{{
+   * scala> import cats.implicits._
+   * scala> Align[List].alignCombine(List(1, 2), List(10, 11, 12))
+   * res0: List[Int] = List(11, 13, 12)
+   * }}}
+   */
+  def alignCombine[A: Semigroup](fa1: F[A], fa2: F[A]): F[A] =
+    alignWith(fa1, fa2)(_.merge)
+
+  /**
+   * Same as `align`, but forgets from the type that one of the two elements must be present.
+   *
+   * Example:
+   * {{{
+   * scala> import cats.implicits._
+   * scala> Align[List].padZip(List(1, 2), List(10))
+   * res0: List[(Option[Int], Option[Int])] = List((Some(1),Some(10)), (Some(2),None))
+   * }}}
+   */
+  def padZip[A, B](fa: F[A], fb: F[B]): F[(Option[A], Option[B])] =
+    alignWith(fa, fb)(_.pad)
+
+  /**
+   * Same as `alignWith`, but forgets from the type that one of the two elements must be present.
+   *
+   * Example:
+   * {{{
+   * scala> import cats.implicits._
+   * scala> Align[List].padZipWith(List(1, 2), List(10, 11, 12))(_ |+| _)
+   * res0: List[Option[Int]] = List(Some(11), Some(13), Some(12))
+   * }}}
+   */
+  def padZipWith[A, B, C](fa: F[A], fb: F[B])(f: (Option[A], Option[B]) => C): F[C] =
+    alignWith(fa, fb) { ior =>
+      val (oa, ob) = ior.pad
+      f(oa, ob)
+    }
+}
+
+object Align {
+  def semigroup[F[_], A](implicit F: Align[F], A: Semigroup[A]): Semigroup[F[A]] = new Semigroup[F[A]] {
+    def combine(x: F[A], y: F[A]): F[A] = Align[F].alignCombine(x, y)
+  }
+}

core/src/main/scala/cats/Apply.scala

@@ -2,6 +2,7 @@ package cats
 
 import simulacrum.typeclass
 import simulacrum.noop
+import cats.data.Ior
 
 /**
  * Weaker version of Applicative[F]; has apply but not pure.
@@ -225,6 +226,11 @@ object Apply {
    */
   def semigroup[F[_], A](implicit f: Apply[F], sg: Semigroup[A]): Semigroup[F[A]] =
     new ApplySemigroup[F, A](f, sg)
+
+  def align[F[_]: Apply]: Align[F] = new Align[F] {
+    def align[A, B](fa: F[A], fb: F[B]): F[Ior[A, B]] = Apply[F].map2(fa, fb)(Ior.both)
+    def functor: Functor[F] = Apply[F]
+  }
 }
 
 private[cats] class ApplySemigroup[F[_], A](f: Apply[F], sg: Semigroup[A]) extends Semigroup[F[A]] {

core/src/main/scala/cats/SemigroupK.scala

@@ -1,6 +1,7 @@
 package cats
 
 import simulacrum.typeclass
+import cats.data.Ior
 
 /**
  * SemigroupK is a universal semigroup which operates on kinds.
@@ -68,3 +69,11 @@ import simulacrum.typeclass
       val F = self
     }
 }
+
+object SemigroupK {
+  def align[F[_]: SemigroupK: Functor]: Align[F] = new Align[F] {
+    def align[A, B](fa: F[A], fb: F[B]): F[Ior[A, B]] =
+      SemigroupK[F].combineK(Functor[F].map(fa)(Ior.left), Functor[F].map(fb)(Ior.right))
+    def functor: Functor[F] = Functor[F]
+  }
+}

core/src/main/scala/cats/data/AbstractNonEmptyInstances.scala

@@ -77,5 +77,4 @@ abstract private[data] class AbstractNonEmptyInstances[F[_], NonEmptyF[_]](impli
 
   override def collectFirstSome[A, B](fa: NonEmptyF[A])(f: A => Option[B]): Option[B] =
     traverseInstance.collectFirstSome(fa)(f)
-
 }

core/src/main/scala/cats/data/Chain.scala

@@ -681,8 +681,8 @@ sealed abstract private[data] class ChainInstances extends ChainInstances1 {
   }
 
   implicit val catsDataInstancesForChain
-    : Traverse[Chain] with Alternative[Chain] with Monad[Chain] with CoflatMap[Chain] =
-    new Traverse[Chain] with Alternative[Chain] with Monad[Chain] with CoflatMap[Chain] {
+    : Traverse[Chain] with Alternative[Chain] with Monad[Chain] with CoflatMap[Chain] with Align[Chain] =
+    new Traverse[Chain] with Alternative[Chain] with Monad[Chain] with CoflatMap[Chain] with Align[Chain] {
       def foldLeft[A, B](fa: Chain[A], b: B)(f: (B, A) => B): B =
         fa.foldLeft(b)(f)
       def foldRight[A, B](fa: Chain[A], lb: Eval[B])(f: (A, Eval[B]) => Eval[B]): Eval[B] =
@@ -743,6 +743,27 @@ sealed abstract private[data] class ChainInstances extends ChainInstances1 {
       }
 
       override def get[A](fa: Chain[A])(idx: Long): Option[A] = fa.get(idx)
+
+      def functor: Functor[Chain] = this
+
+      def align[A, B](fa: Chain[A], fb: Chain[B]): Chain[Ior[A, B]] =
+        alignWith(fa, fb)(identity)
+
+      override def alignWith[A, B, C](fa: Chain[A], fb: Chain[B])(f: Ior[A, B] => C): Chain[C] = {
+        val iterA = fa.iterator
+        val iterB = fb.iterator
+
+        var result: Chain[C] = Chain.empty
+
+        while (iterA.hasNext || iterB.hasNext) {
+          val ior =
+            if (iterA.hasNext && iterB.hasNext) Ior.both(iterA.next(), iterB.next())
+            else if (iterA.hasNext) Ior.left(iterA.next())
+            else Ior.right(iterB.next())
+          result = result :+ f(ior)
+        }
+        result
+      }
     }
 
   implicit def catsDataShowForChain[A](implicit A: Show[A]): Show[Chain[A]] =

core/src/main/scala/cats/data/Const.scala

@@ -74,6 +74,12 @@ sealed abstract private[data] class ConstInstances extends ConstInstances0 {
       x.compare(y)
   }
 
+  implicit def catsDataAlignForConst[A: Semigroup]: Align[Const[A, *]] = new Align[Const[A, *]] {
+    def align[B, C](fa: Const[A, B], fb: Const[A, C]): Const[A, Ior[B, C]] =
+      Const(Semigroup[A].combine(fa.getConst, fb.getConst))
+    def functor: Functor[Const[A, *]] = catsDataFunctorForConst
+  }
+
   implicit def catsDataShowForConst[A: Show, B]: Show[Const[A, B]] = new Show[Const[A, B]] {
     def show(f: Const[A, B]): String = f.show
   }

core/src/main/scala/cats/data/NonEmptyChain.scala

@@ -418,9 +418,11 @@ class NonEmptyChainOps[A](private val value: NonEmptyChain[A]) extends AnyVal {
 
 sealed abstract private[data] class NonEmptyChainInstances extends NonEmptyChainInstances1 {
 
-  implicit val catsDataInstancesForNonEmptyChain
-    : SemigroupK[NonEmptyChain] with NonEmptyTraverse[NonEmptyChain] with Bimonad[NonEmptyChain] =
-    new AbstractNonEmptyInstances[Chain, NonEmptyChain] {
+  implicit val catsDataInstancesForNonEmptyChain: SemigroupK[NonEmptyChain]
+    with NonEmptyTraverse[NonEmptyChain]
+    with Bimonad[NonEmptyChain]
+    with Align[NonEmptyChain] =
+    new AbstractNonEmptyInstances[Chain, NonEmptyChain] with Align[NonEmptyChain] {
       def extract[A](fa: NonEmptyChain[A]): A = fa.head
 
       def nonEmptyTraverse[G[_]: Apply, A, B](fa: NonEmptyChain[A])(f: A => G[B]): G[NonEmptyChain[B]] =
@@ -451,6 +453,16 @@ sealed abstract private[data] class NonEmptyChainInstances extends NonEmptyChain
 
       override def get[A](fa: NonEmptyChain[A])(idx: Long): Option[A] =
         if (idx == 0) Some(fa.head) else fa.tail.get(idx - 1)
+
+      private val alignInstance = Align[Chain].asInstanceOf[Align[NonEmptyChain]]
+
+      def functor: Functor[NonEmptyChain] = alignInstance.functor
+
+      def align[A, B](fa: NonEmptyChain[A], fb: NonEmptyChain[B]): NonEmptyChain[Ior[A, B]] =
+        alignInstance.align(fa, fb)
+
+      override def alignWith[A, B, C](fa: NonEmptyChain[A], fb: NonEmptyChain[B])(f: Ior[A, B] => C): NonEmptyChain[C] =
+        alignInstance.alignWith(fa, fb)(f)
     }
 
   implicit def catsDataOrderForNonEmptyChain[A: Order]: Order[NonEmptyChain[A]] =

core/src/main/scala/cats/data/NonEmptyList.scala

@@ -510,11 +510,12 @@ object NonEmptyList extends NonEmptyListInstances {
 sealed abstract private[data] class NonEmptyListInstances extends NonEmptyListInstances0 {
 
   implicit val catsDataInstancesForNonEmptyList
-    : SemigroupK[NonEmptyList] with Bimonad[NonEmptyList] with NonEmptyTraverse[NonEmptyList] =
+    : SemigroupK[NonEmptyList] with Bimonad[NonEmptyList] with NonEmptyTraverse[NonEmptyList] with Align[NonEmptyList] =
     new NonEmptyReducible[NonEmptyList, List]
       with SemigroupK[NonEmptyList]
       with Bimonad[NonEmptyList]
-      with NonEmptyTraverse[NonEmptyList] {
+      with NonEmptyTraverse[NonEmptyList]
+      with Align[NonEmptyList] {
 
       def combineK[A](a: NonEmptyList[A], b: NonEmptyList[A]): NonEmptyList[A] =
         a.concatNel(b)
@@ -619,6 +620,25 @@ sealed abstract private[data] class NonEmptyListInstances extends NonEmptyListIn
 
       override def get[A](fa: NonEmptyList[A])(idx: Long): Option[A] =
         if (idx == 0) Some(fa.head) else Foldable[List].get(fa.tail)(idx - 1)
+
+      def functor: Functor[NonEmptyList] = this
+
+      def align[A, B](fa: NonEmptyList[A], fb: NonEmptyList[B]): NonEmptyList[Ior[A, B]] =
+        alignWith(fa, fb)(identity)
+
+      override def alignWith[A, B, C](fa: NonEmptyList[A], fb: NonEmptyList[B])(f: Ior[A, B] => C): NonEmptyList[C] = {
+
+        @tailrec
+        def go(as: List[A], bs: List[B], acc: List[C]): List[C] = (as, bs) match {
+          case (Nil, Nil)         => acc
+          case (Nil, y :: ys)     => go(Nil, ys, f(Ior.right(y)) :: acc)
+          case (x :: xs, Nil)     => go(xs, Nil, f(Ior.left(x)) :: acc)
+          case (x :: xs, y :: ys) => go(xs, ys, f(Ior.both(x, y)) :: acc)
+        }
+
+        NonEmptyList(f(Ior.both(fa.head, fb.head)), go(fa.tail, fb.tail, Nil).reverse)
+      }
+
     }
 
   implicit def catsDataShowForNonEmptyList[A](implicit A: Show[A]): Show[NonEmptyList[A]] =

core/src/main/scala/cats/data/NonEmptyMapImpl.scala

@@ -268,8 +268,8 @@ sealed class NonEmptyMapOps[K, A](val value: NonEmptyMap[K, A]) {
 sealed abstract private[data] class NonEmptyMapInstances extends NonEmptyMapInstances0 {
 
   implicit def catsDataInstancesForNonEmptyMap[K: Order]
-    : SemigroupK[NonEmptyMap[K, *]] with NonEmptyTraverse[NonEmptyMap[K, *]] =
-    new SemigroupK[NonEmptyMap[K, *]] with NonEmptyTraverse[NonEmptyMap[K, *]] {
+    : SemigroupK[NonEmptyMap[K, *]] with NonEmptyTraverse[NonEmptyMap[K, *]] with Align[NonEmptyMap[K, *]] =
+    new SemigroupK[NonEmptyMap[K, *]] with NonEmptyTraverse[NonEmptyMap[K, *]] with Align[NonEmptyMap[K, *]] {
 
       override def map[A, B](fa: NonEmptyMap[K, A])(f: A => B): NonEmptyMap[K, B] =
         fa.map(f)
@@ -316,6 +316,11 @@ sealed abstract private[data] class NonEmptyMapInstances extends NonEmptyMapInst
 
       override def toNonEmptyList[A](fa: NonEmptyMap[K, A]): NonEmptyList[A] =
         NonEmptyList(fa.head._2, fa.tail.toList.map(_._2))
+
+      def functor: Functor[NonEmptyMap[K, *]] = this
+
+      def align[A, B](fa: NonEmptyMap[K, A], fb: NonEmptyMap[K, B]): NonEmptyMap[K, Ior[A, B]] =
+        NonEmptyMap.fromMapUnsafe(Align[SortedMap[K, *]].align(fa.toSortedMap, fb.toSortedMap))
     }
 
   implicit def catsDataHashForNonEmptyMap[K: Hash: Order, A: Hash]: Hash[NonEmptyMap[K, A]] =

core/src/main/scala/cats/data/NonEmptyVector.scala

@@ -238,12 +238,15 @@ final class NonEmptyVector[+A] private (val toVector: Vector[A]) extends AnyVal
 @suppressUnusedImportWarningForScalaVersionSpecific
 sealed abstract private[data] class NonEmptyVectorInstances {
 
-  implicit val catsDataInstancesForNonEmptyVector
-    : SemigroupK[NonEmptyVector] with Bimonad[NonEmptyVector] with NonEmptyTraverse[NonEmptyVector] =
+  implicit val catsDataInstancesForNonEmptyVector: SemigroupK[NonEmptyVector]
+    with Bimonad[NonEmptyVector]
+    with NonEmptyTraverse[NonEmptyVector]
+    with Align[NonEmptyVector] =
     new NonEmptyReducible[NonEmptyVector, Vector]
       with SemigroupK[NonEmptyVector]
       with Bimonad[NonEmptyVector]
-      with NonEmptyTraverse[NonEmptyVector] {
+      with NonEmptyTraverse[NonEmptyVector]
+      with Align[NonEmptyVector] {
 
       def combineK[A](a: NonEmptyVector[A], b: NonEmptyVector[A]): NonEmptyVector[A] =
         a.concatNev(b)
@@ -360,6 +363,15 @@ sealed abstract private[data] class NonEmptyVectorInstances {
 
       override def toNonEmptyList[A](fa: NonEmptyVector[A]): NonEmptyList[A] =
         NonEmptyList(fa.head, fa.tail.toList)
+
+      def functor: Functor[NonEmptyVector] = this
+
+      def align[A, B](fa: NonEmptyVector[A], fb: NonEmptyVector[B]): NonEmptyVector[Ior[A, B]] =
+        NonEmptyVector.fromVectorUnsafe(Align[Vector].align(fa.toVector, fb.toVector))
+
+      override def alignWith[A, B, C](fa: NonEmptyVector[A],
+                                      fb: NonEmptyVector[B])(f: Ior[A, B] => C): NonEmptyVector[C] =
+        NonEmptyVector.fromVectorUnsafe(Align[Vector].alignWith(fa.toVector, fb.toVector)(f))
     }
 
   implicit def catsDataEqForNonEmptyVector[A](implicit A: Eq[A]): Eq[NonEmptyVector[A]] =

core/src/main/scala/cats/data/Validated.scala

@@ -371,6 +371,27 @@ sealed abstract private[data] class ValidatedInstances extends ValidatedInstance
       }
     }
 
+  implicit def catsDataAlignForValidated[E: Semigroup]: Align[Validated[E, *]] =
+    new Align[Validated[E, *]] {
+      def functor: Functor[Validated[E, *]] = catsDataTraverseFunctorForValidated
+      def align[A, B](fa: Validated[E, A], fb: Validated[E, B]): Validated[E, Ior[A, B]] =
+        alignWith(fa, fb)(identity)
+
+      override def alignWith[A, B, C](fa: Validated[E, A], fb: Validated[E, B])(f: Ior[A, B] => C): Validated[E, C] =
+        fa match {
+          case Invalid(e) =>
+            fb match {
+              case Invalid(e2) => Invalid(Semigroup[E].combine(e, e2))
+              case Valid(b)    => Valid(f(Ior.right(b)))
+            }
+          case Valid(a) =>
+            fb match {
+              case Invalid(e) => Valid(f(Ior.left(a)))
+              case Valid(b)   => Valid(f(Ior.both(a, b)))
+            }
+        }
+    }
+
   implicit def catsDataMonoidForValidated[A, B](implicit A: Semigroup[A], B: Monoid[B]): Monoid[Validated[A, B]] =
     new Monoid[Validated[A, B]] {
       def empty: Validated[A, B] = Valid(B.empty)