From 46e7be67e5bcd5a788639fe5977e396475deb930 Mon Sep 17 00:00:00 2001 From: Luka Jacobowitz Date: Sat, 5 Aug 2017 19:13:38 +0200 Subject: [PATCH 1/5] Add NonEmptyTraverse documentation --- docs/src/main/tut/typeclasses/nonemptytraverse.md | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 docs/src/main/tut/typeclasses/nonemptytraverse.md diff --git a/docs/src/main/tut/typeclasses/nonemptytraverse.md b/docs/src/main/tut/typeclasses/nonemptytraverse.md new file mode 100644 index 0000000000..f4a322a950 --- /dev/null +++ b/docs/src/main/tut/typeclasses/nonemptytraverse.md @@ -0,0 +1,11 @@ +--- +layout: docs +title: "NonEmptyTraverse" +section: "typeclasses" +source: "core/src/main/scala/cats/NonEmptyTraverse.scala" +scaladoc: "#cats.NonEmptyTraverse" +--- + +# NonEmptyTraverse` + +`NonEmptyTraverse` From 74f67c12ab8c1370ad5b8f0798dcde953ac20357 Mon Sep 17 00:00:00 2001 From: Luka Jacobowitz Date: Sat, 5 Aug 2017 20:15:57 +0200 Subject: [PATCH 2/5] Initial version of nonEmptyTraverse docs --- .../main/tut/typeclasses/nonemptytraverse.md | 38 ++++++++++++++++++- 1 file changed, 37 insertions(+), 1 deletion(-) diff --git a/docs/src/main/tut/typeclasses/nonemptytraverse.md b/docs/src/main/tut/typeclasses/nonemptytraverse.md index f4a322a950..ad68f8d928 100644 --- a/docs/src/main/tut/typeclasses/nonemptytraverse.md +++ b/docs/src/main/tut/typeclasses/nonemptytraverse.md @@ -8,4 +8,40 @@ scaladoc: "#cats.NonEmptyTraverse" # NonEmptyTraverse` -`NonEmptyTraverse` +`NonEmptyTraverse` is a non-empty version of the `Traverse` type class, just like `Reducible` is a non-empty version of `Foldable`. +As such, it extends both `Reducible` and `Traverse` in the type class hierarchy. +It provides the `nonEmptyTraverse` and `nonEmptySequence` methods that require an instance of `Apply` instead of `Applicative`: + +```scala +def nonEmptyTraverse[G[_]: Apply, A, B](fa: F[A])(f: A => G[B]): G[F[B]] + +def nonEmptySequence[G[_]: Apply, A](fga: F[G[A]]): G[F[A]] +``` + +In the [Applicative tutorial](applicative.html) we learned of `Apply` as a weakened `Applicative` lacking the `pure` method. +One example type lacking an `Applicative` instance is `Map[K, ?]`, it's impossible to implement a `pure` method for it. + +Knowing this, we can make use of `NonEmptyTraverse`, to traverse over a sequence of `Map`s. +One example application one could think of is, when we have a list of text snippets, +count the occurrence of each word in each snippet and return all the common words and their occurrences in each snippet: + +```tut:book +import cats.implicits._ +import cats.data.NonEmptyList + +val snippets = NonEmptyList.of("What do you do", "What are you doing") + +def countWords(text: String): Map[String, Int] = + text.split(" ").groupBy(identity).mapValues(_.length) + +snippets.nonEmptyTraverse(countWords) +``` + +Note that, just like `traverse`, `nonEmptyTraverse(f)` is equivalent to `map(f).nonEmptySequence`, so the above could be rewritten as: + +```tut:book +snippets.map(countWords).nonEmptySequence +``` + +`NonEmptyTraverse` also offers `flatNonEmptyTraverse` and `flatNonEmptySequence` methods that are analogous to `flatTraverse` and `flatSequence` in `Traverse`. +Just like with `nonEmptyTraverse` these methods don't require a `Monad` instance, but only a `FlatMap`, which is the weakened version of `Monad` without `pure`. From 6b9c357b4cfc8fb35c17c83bbca04dd01de9f11f Mon Sep 17 00:00:00 2001 From: Luka Jacobowitz Date: Fri, 25 Aug 2017 22:01:05 +0200 Subject: [PATCH 3/5] Add menu entry --- docs/src/main/resources/microsite/data/menu.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/src/main/resources/microsite/data/menu.yml b/docs/src/main/resources/microsite/data/menu.yml index 081dfffe2a..a6452bbe14 100644 --- a/docs/src/main/resources/microsite/data/menu.yml +++ b/docs/src/main/resources/microsite/data/menu.yml @@ -100,6 +100,10 @@ options: url: typeclasses/show.html menu_type: typeclasses + - title: NonEmptyTraverse + url: typeclasses/nonemptytraverse.html + menu_type: typeclasses + ########################### # Data Types Menu Options # ########################### From 631c4fb215a5b23c800bd8da664f54db09f74a77 Mon Sep 17 00:00:00 2001 From: Luka Jacobowitz Date: Fri, 15 Sep 2017 16:59:56 +0200 Subject: [PATCH 4/5] Add links to other typeclasses --- docs/src/main/tut/typeclasses/nonemptytraverse.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/main/tut/typeclasses/nonemptytraverse.md b/docs/src/main/tut/typeclasses/nonemptytraverse.md index ad68f8d928..51939ad2ec 100644 --- a/docs/src/main/tut/typeclasses/nonemptytraverse.md +++ b/docs/src/main/tut/typeclasses/nonemptytraverse.md @@ -8,7 +8,7 @@ scaladoc: "#cats.NonEmptyTraverse" # NonEmptyTraverse` -`NonEmptyTraverse` is a non-empty version of the `Traverse` type class, just like `Reducible` is a non-empty version of `Foldable`. +`NonEmptyTraverse` is a non-empty version of the [Traverse](traverse.html) type class, just like [Reducible](reducible.html) is a non-empty version of [Foldable](foldable.html)`. As such, it extends both `Reducible` and `Traverse` in the type class hierarchy. It provides the `nonEmptyTraverse` and `nonEmptySequence` methods that require an instance of `Apply` instead of `Applicative`: From 156c14f04472ef7652104b184866c3f21ea54d64 Mon Sep 17 00:00:00 2001 From: Luka Jacobowitz Date: Wed, 20 Sep 2017 22:12:04 +0200 Subject: [PATCH 5/5] Remove misplaced backtick --- docs/src/main/tut/typeclasses/nonemptytraverse.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/main/tut/typeclasses/nonemptytraverse.md b/docs/src/main/tut/typeclasses/nonemptytraverse.md index 51939ad2ec..9e91774167 100644 --- a/docs/src/main/tut/typeclasses/nonemptytraverse.md +++ b/docs/src/main/tut/typeclasses/nonemptytraverse.md @@ -6,9 +6,9 @@ source: "core/src/main/scala/cats/NonEmptyTraverse.scala" scaladoc: "#cats.NonEmptyTraverse" --- -# NonEmptyTraverse` +# NonEmptyTraverse -`NonEmptyTraverse` is a non-empty version of the [Traverse](traverse.html) type class, just like [Reducible](reducible.html) is a non-empty version of [Foldable](foldable.html)`. +`NonEmptyTraverse` is a non-empty version of the [Traverse](traverse.html) type class, just like [Reducible](reducible.html) is a non-empty version of [Foldable](foldable.html). As such, it extends both `Reducible` and `Traverse` in the type class hierarchy. It provides the `nonEmptyTraverse` and `nonEmptySequence` methods that require an instance of `Apply` instead of `Applicative`: