diff --git a/build.sbt b/build.sbt index 548a3f0cbd..92362d3322 100644 --- a/build.sbt +++ b/build.sbt @@ -337,6 +337,7 @@ lazy val kernel = crossProject(JSPlatform, JVMPlatform, NativePlatform) .settings(includeGeneratedSrc) .jsSettings(commonJsSettings) .jvmSettings(commonJvmSettings ++ mimaSettings("cats-kernel")) + .settings(libraryDependencies += "org.scalacheck" %%% "scalacheck" % scalaCheckVersion(scalaVersion.value) % "test") lazy val kernelJVM = kernel.jvm diff --git a/kernel/src/main/scala/cats/kernel/Group.scala b/kernel/src/main/scala/cats/kernel/Group.scala index 8001de0752..31d019146f 100644 --- a/kernel/src/main/scala/cats/kernel/Group.scala +++ b/kernel/src/main/scala/cats/kernel/Group.scala @@ -11,6 +11,14 @@ trait Group[@sp(Int, Long, Float, Double) A] extends Any with Monoid[A] { * Find the inverse of `a`. * * `combine(a, inverse(a))` = `combine(inverse(a), a)` = `empty`. + * + * Example: + * {{{ + * scala> import cats.kernel.instances.int._ + * + * scala> Group[Int].inverse(5) + * res0: Int = -5 + * }}} */ def inverse(a: A): A @@ -18,6 +26,14 @@ trait Group[@sp(Int, Long, Float, Double) A] extends Any with Monoid[A] { * Remove the element `b` from `a`. * * Equivalent to `combine(a, inverse(b))` + * + * Example: + * {{{ + * scala> import cats.kernel.instances.int._ + * + * scala> Group[Int].remove(5, 2) + * res0: Int = 3 + * }}} */ def remove(a: A, b: A): A = combine(a, inverse(b)) diff --git a/kernel/src/main/scala/cats/kernel/Monoid.scala b/kernel/src/main/scala/cats/kernel/Monoid.scala index 73041e0d99..3dab5678af 100644 --- a/kernel/src/main/scala/cats/kernel/Monoid.scala +++ b/kernel/src/main/scala/cats/kernel/Monoid.scala @@ -12,17 +12,51 @@ trait Monoid[@sp(Int, Long, Float, Double) A] extends Any with Semigroup[A] { /** * Return the identity element for this monoid. + * + * Example: + * {{{ + * scala> import cats.kernel.instances.int._ + * scala> import cats.kernel.instances.string._ + * + * scala> Monoid[String].empty + * res0: String = "" + * + * scala> Monoid[Int].empty + * res1: Int = 0 + * }}} */ def empty: A /** * Tests if `a` is the identity. + * + * Example: + * {{{ + * scala> import cats.kernel.instances.string._ + * + * scala> Monoid[String].isEmpty("") + * res0: Boolean = true + * + * scala> Monoid[String].isEmpty("something") + * res1: Boolean = false + * }}} */ def isEmpty(a: A)(implicit ev: Eq[A]): Boolean = ev.eqv(a, empty) /** * Return `a` appended to itself `n` times. + * + * Example: + * {{{ + * scala> import cats.kernel.instances.string._ + * + * scala> Monoid[String].combineN("ha", 3) + * res0: String = hahaha + * + * scala> Monoid[String].combineN("ha", 0) + * res1: String = "" + * }}} */ override def combineN(a: A, n: Int): A = if (n < 0) throw new IllegalArgumentException("Repeated combining for monoids must have n >= 0") @@ -31,6 +65,17 @@ trait Monoid[@sp(Int, Long, Float, Double) A] extends Any with Semigroup[A] { /** * Given a sequence of `as`, sum them using the monoid and return the total. + * + * Example: + * {{{ + * scala> import cats.kernel.instances.string._ + * + * scala> Monoid[String].combineAll(List("One ", "Two ", "Three")) + * res0: String = One Two Three + * + * scala> Monoid[String].combineAll(List.empty) + * res1: String = "" + * }}} */ def combineAll(as: TraversableOnce[A]): A = as.foldLeft(empty)(combine) diff --git a/kernel/src/main/scala/cats/kernel/Semigroup.scala b/kernel/src/main/scala/cats/kernel/Semigroup.scala index 76169e8de5..5665324abc 100644 --- a/kernel/src/main/scala/cats/kernel/Semigroup.scala +++ b/kernel/src/main/scala/cats/kernel/Semigroup.scala @@ -1,6 +1,6 @@ package cats.kernel -import scala.{ specialized => sp } +import scala.{specialized => sp} import scala.annotation.tailrec /** * A semigroup is any set `A` with an associative operation (`combine`). @@ -9,11 +9,36 @@ trait Semigroup[@sp(Int, Long, Float, Double) A] extends Any with Serializable { /** * Associative operation which combines two values. + * + * Example: + * {{{ + * scala> import cats.kernel.instances.string._ + * scala> import cats.kernel.instances.int._ + * scala> import cats.kernel.instances.option._ + * + * scala> Semigroup[String].combine("Hello ", "World!") + * res0: String = Hello World! + * + * scala> Semigroup[Option[Int]].combine(None, Some(1)) + * res1: Option[Int] = Some(1) + * }}} */ def combine(x: A, y: A): A /** * Return `a` combined with itself `n` times. + * + * Example: + * {{{ + * scala> import cats.kernel.instances.int._ + * scala> import cats.kernel.instances.string._ + * + * scala> Semigroup[Int].combineN(1, 10) + * res0: Int = 10 + * + * scala> Semigroup[String].combineN("ha", 3) + * res1: String = hahaha + * }}} */ def combineN(a: A, n: Int): A = if (n <= 0) throw new IllegalArgumentException("Repeated combining for semigroups must have n > 0") @@ -35,6 +60,17 @@ trait Semigroup[@sp(Int, Long, Float, Double) A] extends Any with Serializable { * Given a sequence of `as`, combine them and return the total. * * If the sequence is empty, returns None. Otherwise, returns Some(total). + * + * Example: + * {{{ + * scala> import cats.kernel.instances.string._ + * + * scala> Semigroup[String].combineAllOption(List("One ", "Two ", "Three")) + * res0: Option[String] = Some(One Two Three) + * + * scala> Semigroup[String].combineAllOption(List.empty) + * res1: Option[String] = None + * }}} */ def combineAllOption(as: TraversableOnce[A]): Option[A] = cats.kernel.compat.TraversableOnce.reduceOption(as, combine)