SemigroupK/MonoidK methods

core/src/main/scala-2.12/cats/instances/stream.scala

@@ -2,10 +2,12 @@ package cats
 package instances
 
 import cats.data.{Ior, ZipStream}
+import cats.kernel.compat.scalaVersionSpecific._
 import cats.syntax.show._
 
 import scala.annotation.tailrec
 
+@suppressUnusedImportWarningForScalaVersionSpecific
 trait StreamInstances extends cats.kernel.instances.StreamInstances {
 
   implicit val catsStdInstancesForStream
@@ -16,6 +18,8 @@ trait StreamInstances extends cats.kernel.instances.StreamInstances {
 
       def combineK[A](x: Stream[A], y: Stream[A]): Stream[A] = x #::: y
 
+      override def fromIterableOnce[A](as: IterableOnce[A]): Stream[A] = as.iterator.toStream
+
       override def prependK[A](a: A, fa: Stream[A]): Stream[A] = a #:: fa
 
       def pure[A](x: A): Stream[A] = Stream(x)

core/src/main/scala-2.13+/cats/instances/arraySeq.scala

@@ -34,6 +34,8 @@ private[cats] object ArraySeqInstances {
       def combineK[A](xs: ArraySeq[A], ys: ArraySeq[A]): ArraySeq[A] =
         xs.concat(ys)
 
+      override def fromIterableOnce[A](as: IterableOnce[A]): ArraySeq[A] = ArraySeq.untagged.from(as)
+
       override def prependK[A](a: A, fa: ArraySeq[A]): ArraySeq[A] = fa.prepended(a)
 
       override def appendK[A](fa: ArraySeq[A], a: A): ArraySeq[A] = fa.appended(a)

core/src/main/scala-2.13+/cats/instances/lazyList.scala

@@ -2,12 +2,14 @@ package cats
 package instances
 
 import cats.kernel
+import cats.kernel.compat.scalaVersionSpecific._
 import cats.syntax.show._
 import cats.data.Ior
 import cats.data.ZipLazyList
 
 import scala.annotation.tailrec
 
+@suppressUnusedImportWarningForScalaVersionSpecific
 trait LazyListInstances extends cats.kernel.instances.LazyListInstances {
 
   implicit val catsStdInstancesForLazyList
@@ -22,6 +24,13 @@ trait LazyListInstances extends cats.kernel.instances.LazyListInstances {
 
       def combineK[A](x: LazyList[A], y: LazyList[A]): LazyList[A] = x.lazyAppendedAll(y)
 
+      override def combineAllOptionK[A](as: IterableOnce[LazyList[A]]): Option[LazyList[A]] = {
+        val iter = as.iterator
+        if (iter.isEmpty) None else Some(LazyList.from(iter.flatMap(_.iterator)))
+      }
+
+      override def fromIterableOnce[A](as: IterableOnce[A]): LazyList[A] = LazyList.from(as)
+
       override def prependK[A](a: A, fa: LazyList[A]): LazyList[A] = fa.prepended(a)
 
       override def appendK[A](fa: LazyList[A], a: A): LazyList[A] = fa.appended(a)

core/src/main/scala-2.13+/cats/instances/stream.scala

@@ -2,10 +2,12 @@ package cats
 package instances
 
 import cats.data.{Ior, ZipStream}
+import cats.kernel.compat.scalaVersionSpecific._
 import cats.syntax.show._
 
 import scala.annotation.tailrec
 
+@suppressUnusedImportWarningForScalaVersionSpecific
 trait StreamInstances extends cats.kernel.instances.StreamInstances {
 
   @deprecated("Use cats.instances.lazyList", "2.0.0-RC2")
@@ -17,6 +19,8 @@ trait StreamInstances extends cats.kernel.instances.StreamInstances {
 
       def combineK[A](x: Stream[A], y: Stream[A]): Stream[A] = x #::: y
 
+      override def fromIterableOnce[A](as: IterableOnce[A]): Stream[A] = Stream.from(as)
+
       override def prependK[A](a: A, fa: Stream[A]): Stream[A] = a #:: fa
 
       def pure[A](x: A): Stream[A] = Stream(x)

core/src/main/scala/cats/Alternative.scala

@@ -1,6 +1,7 @@
 package cats
 
 import simulacrum.typeclass
+import cats.kernel.compat.scalaVersionSpecific._
 
 @typeclass trait Alternative[F[_]] extends NonEmptyAlternative[F] with MonoidK[F] { self =>
 
@@ -99,8 +100,15 @@ import simulacrum.typeclass
       val F = self
       val G = Applicative[G]
     }
+
+  def fromIterableOnce[A](as: IterableOnce[A]): F[A] =
+    combineAllK(as.iterator.map(pure(_)))
+
+  final def fromFoldable[G[_]: Foldable, A](as: G[A]): F[A] =
+    fromIterableOnce(Foldable[G].toIterable(as))
 }
 
+@suppressUnusedImportWarningForScalaVersionSpecific
 object Alternative {
 
   /* ======================================================================== */

core/src/main/scala/cats/MonoidK.scala

@@ -1,5 +1,7 @@
 package cats
 
+import cats.kernel.compat.scalaVersionSpecific._
+
 import simulacrum.typeclass
 
 /**
@@ -36,6 +38,21 @@ import simulacrum.typeclass
    */
   def empty[A]: F[A]
 
+  /**
+   * Tests if `a` is the identity.
+   *
+   * Example:
+   * {{{
+   * scala> MonoidK[List].isEmpty(List.empty[String])
+   * res0: Boolean = true
+   *
+   * scala> MonoidK[List].isEmpty(List("something"))
+   * res1: Boolean = false
+   * }}}
+   */
+  def isEmpty[A](a: F[A])(implicit ev: Eq[F[A]]): Boolean =
+    ev.eqv(a, empty)
+
   /**
    * Given a type A, create a concrete Monoid[F[A]].
    *
@@ -67,8 +84,54 @@ import simulacrum.typeclass
     new ComposedMonoidK[F, G] {
       val F: MonoidK[F] = self
     }
+
+  /**
+   * Return `a` combined with itself `n` times.
+   *
+   * Example:
+   * {{{
+   * scala> SemigroupK[List].combineNK(List(1), 5)
+   * res0: List[Int] = List(1, 1, 1, 1, 1)
+
+   * scala> MonoidK[List].combineNK(List("ha"), 0)
+   * res1: List[String] = List()
+   *
+   * }}}
+   */
+  override def combineNK[A](a: F[A], n: Int): F[A] =
+    if (n < 0) throw new IllegalArgumentException("Repeated combining for monoidKs must have n >= 0")
+    else if (n == 0) empty[A]
+    else repeatedCombineNK(a, n)
+
+  /**
+   * Given a sequence of `as`, sum them using the monoidK and return the total.
+   *
+   * Example:
+   * {{{
+   * scala> MonoidK[List].combineAllK(List(List("One"), List("Two"), List("Three")))
+   * res0: List[String] = List(One, Two, Three)
+   *
+   * scala> MonoidK[List].combineAllK[String](List.empty)
+   * res1: List[String] = List()
+   * }}}
+   */
+  def combineAllK[A](as: IterableOnce[F[A]]): F[A] =
+    combineAllOptionK(as) match {
+      case Some(fa) => fa
+      case None     => empty[A]
+    }
+
+  override def reverse: MonoidK[F] =
+    new MonoidK[F] {
+      def empty[A] = self.empty
+      def combineK[A](a: F[A], b: F[A]) = self.combineK(b, a)
+      // a + a + a + ... is the same when reversed
+      override def combineNK[A](a: F[A], n: Int): F[A] = self.combineNK(a, n)
+      override def reverse = self
+    }
 }
 
+@suppressUnusedImportWarningForScalaVersionSpecific
 object MonoidK {
 
   /* ======================================================================== */

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

@@ -1,8 +1,10 @@
 package cats
 
+import scala.annotation.tailrec
 import scala.collection.immutable.{Seq, SortedMap, SortedSet}
 import simulacrum.typeclass
 import cats.data.Ior
+import cats.kernel.compat.scalaVersionSpecific._
 
 /**
  * SemigroupK is a universal semigroup which operates on kinds.
@@ -108,8 +110,66 @@ import cats.data.Ior
    */
   def sum[A, B](fa: F[A], fb: F[B])(implicit F: Functor[F]): F[Either[A, B]] =
     combineK(F.map(fa)(Left(_)), F.map(fb)(Right(_)))
+
+  /**
+   * Return `a` combined with itself `n` times.
+   *
+   * Example:
+   * {{{
+   * scala> SemigroupK[List].combineNK(List(1), 5)
+   * res0: List[Int] = List(1, 1, 1, 1, 1)
+   *
+   * }}}
+   */
+  def combineNK[A](a: F[A], n: Int): F[A] =
+    if (n <= 0) throw new IllegalArgumentException("Repeated combining for semigroupKs must have n > 0")
+    else repeatedCombineNK(a, n)
+
+  /**
+   * Return `a` combined with itself more than once.
+   */
+  protected[this] def repeatedCombineNK[A](a: F[A], n: Int): F[A] = {
+    @tailrec def loop(b: F[A], k: Int, extra: F[A]): F[A] =
+      if (k == 1) combineK(b, extra)
+      else {
+        val x = if ((k & 1) == 1) combineK(b, extra) else extra
+        loop(combineK(b, b), k >>> 1, x)
+      }
+    if (n == 1) a else loop(a, n - 1, a)
+  }
+
+  /**
+   * Given a sequence of `as`, combine them and return the total.
+   *
+   * If the sequence is empty, returns None. Otherwise, returns Some(total).
+   *
+   * Example:
+   * {{{
+   * scala> SemigroupK[List].combineAllOptionK(List(List("One"), List("Two"), List("Three")))
+   * res0: Option[List[String]] = Some(List(One, Two, Three))
+   *
+   * scala> SemigroupK[List].combineAllOptionK[String](List.empty)
+   * res1: Option[List[String]] = None
+   * }}}
+   */
+  def combineAllOptionK[A](as: IterableOnce[F[A]]): Option[F[A]] =
+    as.iterator.reduceOption(combineK[A])
+
+  /**
+   * return a semigroupK that reverses the order
+   * so combineK(a, b) == reverse.combineK(b, a)
+   */
+  def reverse: SemigroupK[F] =
+    new SemigroupK[F] {
+      def combineK[A](a: F[A], b: F[A]): F[A] = self.combineK(b, a)
+      // a + a + a + ... is the same when reversed
+      override def combineNK[A](a: F[A], n: Int): F[A] = self.combineNK(a, n)
+      override def reverse = self
+    }
+
 }
 
+@suppressUnusedImportWarningForScalaVersionSpecific
 object SemigroupK extends ScalaVersionSpecificMonoidKInstances with SemigroupKInstances0 {
   def align[F[_]: SemigroupK: Functor]: Align[F] =
     new Align[F] {

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

@@ -3,6 +3,7 @@ package data
 
 import Chain._
 import cats.kernel.instances.StaticMethods
+import cats.kernel.compat.scalaVersionSpecific._
 
 import scala.annotation.tailrec
 import scala.collection.immutable.{IndexedSeq => ImIndexedSeq, SortedMap, TreeSet}
@@ -678,6 +679,7 @@ sealed abstract class Chain[+A] {
     }
 }
 
+@suppressUnusedImportWarningForScalaVersionSpecific
 object Chain extends ChainInstances {
 
   private val sentinel: Function1[Any, Any] = new scala.runtime.AbstractFunction1[Any, Any] { def apply(a: Any) = this }
@@ -1029,6 +1031,7 @@ sealed abstract private[data] class ChainInstances extends ChainInstances1 {
 
       def empty[A]: Chain[A] = Chain.nil
       def combineK[A](c: Chain[A], c2: Chain[A]): Chain[A] = Chain.concat(c, c2)
+      override def fromIterableOnce[A](as: IterableOnce[A]): Chain[A] = Chain.fromSeq(as.iterator.toSeq)
       def pure[A](a: A): Chain[A] = Chain.one(a)
       def flatMap[A, B](fa: Chain[A])(f: A => Chain[B]): Chain[B] =
         fa.flatMap(f)

core/src/main/scala/cats/instances/list.scala

@@ -2,6 +2,8 @@ package cats
 package instances
 
 import cats.data.{Chain, ZipList}
+import cats.instances.instances.appendAll
+import cats.kernel.compat.scalaVersionSpecific._
 import cats.kernel.instances.StaticMethods.wrapMutableIndexedSeq
 import cats.syntax.show._
 
@@ -19,6 +21,13 @@ trait ListInstances extends cats.kernel.instances.ListInstances {
 
       def combineK[A](x: List[A], y: List[A]): List[A] = x ::: y
 
+      override def combineAllOptionK[A](as: IterableOnce[List[A]]): Option[List[A]] = {
+        val iter = as.iterator
+        if (iter.isEmpty) None else Some(appendAll(iter, List.newBuilder[A]).result())
+      }
+
+      override def fromIterableOnce[A](as: IterableOnce[A]): List[A] = as.iterator.toList
+
       override def prependK[A](a: A, fa: List[A]): List[A] = a :: fa
 
       override def appendK[A](fa: List[A], a: A): List[A] = fa :+ a
@@ -262,6 +271,7 @@ trait ListInstances extends cats.kernel.instances.ListInstances {
     }
 }
 
+@suppressUnusedImportWarningForScalaVersionSpecific
 private[instances] trait ListInstancesBinCompat0 {
   implicit val catsStdTraverseFilterForList: TraverseFilter[List] = new TraverseFilter[List] {
     val traverse: Traverse[List] = cats.instances.list.catsStdInstancesForList

core/src/main/scala/cats/instances/option.scala

@@ -3,6 +3,7 @@ package instances
 
 import scala.annotation.tailrec
 import cats.data.Ior
+import cats.kernel.compat.scalaVersionSpecific._
 
 trait OptionInstances extends cats.kernel.instances.OptionInstances {
 
@@ -25,6 +26,25 @@ trait OptionInstances extends cats.kernel.instances.OptionInstances {
 
       def combineK[A](x: Option[A], y: Option[A]): Option[A] = if (x.isDefined) x else y
 
+      override def combineAllOptionK[A](as: IterableOnce[Option[A]]): Option[Option[A]] = {
+        val it = as.iterator
+        if (it.hasNext) {
+          while (true) {
+            val o = it.next()
+            if (o.isDefined) return Some(o)
+            if (!it.hasNext) return Some(None)
+          }
+          sys.error("unreachable")
+        } else {
+          return None
+        }
+      }
+
+      override def fromIterableOnce[A](as: IterableOnce[A]): Option[A] = {
+        val iter = as.iterator
+        if (iter.hasNext) Some(iter.next()) else None
+      }
+
       override def prependK[A](a: A, fa: Option[A]): Option[A] = Some(a)
       override def appendK[A](fa: Option[A], a: A): Option[A] = if (fa.isDefined) fa else Some(a)
 
@@ -212,6 +232,7 @@ trait OptionInstances extends cats.kernel.instances.OptionInstances {
     }
 }
 
+@suppressUnusedImportWarningForScalaVersionSpecific
 private[instances] trait OptionInstancesBinCompat0 {
   implicit val catsStdTraverseFilterForOption: TraverseFilter[Option] = new TraverseFilter[Option] {
     val traverse: Traverse[Option] = cats.instances.option.catsStdInstancesForOption

core/src/main/scala/cats/instances/package.scala

@@ -0,0 +1,14 @@
+package cats.instances
+
+import scala.collection.mutable.Builder
+
+private[instances] object instances {
+
+  def appendAll[F <: Iterable[A], A](it: Iterator[F], bldr: Builder[A, F]): bldr.type = {
+    while (it.hasNext) {
+      bldr ++= it.next()
+    }
+    bldr
+  }
+
+}