Skip to content

Commit

Permalink
Add NonEmptyTraverse docs (typelevel#1787)
Browse files Browse the repository at this point in the history
* Add NonEmptyTraverse documentation

* Initial version of nonEmptyTraverse docs

* Add menu entry

* Add links to other typeclasses

* Remove misplaced backtick
  • Loading branch information
LukaJCB authored and peterneyens committed Oct 11, 2017
1 parent 8cce29c commit aaecd08
Show file tree
Hide file tree
Showing 2 changed files with 52 additions and 0 deletions.
5 changes: 5 additions & 0 deletions docs/src/main/resources/microsite/data/menu.yml
Original file line number Diff line number Diff line change
Expand Up @@ -96,6 +96,11 @@ options:
url: typeclasses/show.html
menu_type: typeclasses


- title: NonEmptyTraverse
url: typeclasses/nonemptytraverse.html
menu_type: typeclasses

- title: Arrow
url: typeclasses/arrow.html
menu_type: typeclasses
Expand Down
47 changes: 47 additions & 0 deletions docs/src/main/tut/typeclasses/nonemptytraverse.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
---
layout: docs
title: "NonEmptyTraverse"
section: "typeclasses"
source: "core/src/main/scala/cats/NonEmptyTraverse.scala"
scaladoc: "#cats.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).
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`.

0 comments on commit aaecd08

Please sign in to comment.