## NonEmptyList

beginner

`NonEmptyList` is a data type used in Λrrow to model ordered lists that guarantee to have at least one value. `NonEmptyList` is available in the `arrow-core-data` module under the `import arrow.core.NonEmptyList`

## of

A `NonEmptyList` guarantees the list always has at least 1 element.

``````
import arrow.core.NonEmptyList

val value =
//sampleStart
// NonEmptyList.of() // does not compile
NonEmptyList.of(1, 2, 3, 4, 5) // NonEmptyList<Int>
//sampleEnd
fun main() {
println(value)
}
``````

Unlike `List[0]`, `NonEmptyList.head` it’s a safe operation that guarantees no exception throwing.

``````
import arrow.core.NonEmptyList

val value =
//sampleStart
//sampleEnd
fun main() {
println(value)
}
``````

## foldLeft

When we fold over a `NonEmptyList`, we turn a `NonEmptyList< A >` into `B` by providing a seed value and a function that carries the state on each iteration over the elements of the list. The first argument is a function that addresses the seed value, this can be any object of any type which will then become the resulting typed value. The second argument is a function that takes the current state and element in the iteration and returns the new state after transformations have been applied.

``````
import arrow.core.NonEmptyList

//sampleStart
fun sumNel(nel: NonEmptyList<Int>): Int =
nel.foldLeft(0) { acc, n -> acc + n }
val value = sumNel(NonEmptyList.of(1, 1, 1, 1))
//sampleEnd
fun main() {
println("value = \$value")
}
``````

## map

`map` allows us to transform `A` into `B` in `NonEmptyList< A >`

``````
import arrow.core.NonEmptyList

val value =
//sampleStart
NonEmptyList.of(1, 1, 1, 1).map { it + 1 }
//sampleEnd
fun main() {
println(value)
}
``````

## flatMap

`flatMap` allows us to compute over the contents of multiple `NonEmptyList< * >` values

``````
import arrow.core.NonEmptyList

//sampleStart
val nelOne: NonEmptyList<Int> = NonEmptyList.of(1)
val nelTwo: NonEmptyList<Int> = NonEmptyList.of(2)

val value = nelOne.flatMap { one ->
nelTwo.map { two ->
one + two
}
}
//sampleEnd
fun main() {
println("value = \$value")
}
``````

Λrrow allows imperative style comprehensions to make computing over `NonEmptyList` values easy.

``````
import arrow.core.NonEmptyList
import arrow.core.extensions.fx

//sampleStart
val nelOne: NonEmptyList<Int> = NonEmptyList.of(1)
val nelTwo: NonEmptyList<Int> = NonEmptyList.of(2)
val nelThree: NonEmptyList<Int> = NonEmptyList.of(3)

val value = NonEmptyList.fx {
val (one) = nelOne
val (two) = nelTwo
val (three) = nelThree
one + two + three
}
//sampleEnd
fun main() {
println("value = \$value")
}
``````

Monad binding in `NonEmptyList` and other collection related data type can be used as generators

``````
import arrow.core.NonEmptyList
import arrow.core.extensions.fx

val value =
//sampleStart
NonEmptyList.fx {
val (x) = NonEmptyList.of(1, 2, 3)
val (y) = NonEmptyList.of(1, 2, 3)
x + y
}
//sampleEnd
fun main() {
println(value)
}
``````

## Applicative Builder

Λrrow contains methods that allow you to preserve type information when computing over different `NonEmptyList` typed values.

``````
import arrow.core.NonEmptyList
import java.util.UUID
import arrow.core.extensions.nonemptylist.apply.map

//sampleStart
data class Person(val id: UUID, val name: String, val year: Int)

// Note each NonEmptyList is of a different type
val nelId: NonEmptyList<UUID> = NonEmptyList.of(UUID.randomUUID(), UUID.randomUUID())
val nelName: NonEmptyList<String> = NonEmptyList.of("William Alvin Howard", "Haskell Curry")
val nelYear: NonEmptyList<Int> = NonEmptyList.of(1926, 1900)

val value = map(nelId, nelName, nelYear) { (id, name, year) ->
Person(id, name, year)
}
//sampleEnd
fun main() {
println("value = \$value")
}
``````

### Summary

• `NonEmptyList` is used to model lists that guarantee at least one element
• We can easily construct values of `NonEmptyList` with `NonEmptyList.of`
• `foldLeft`, `map`, `flatMap` and others are used to compute over the internal contents of a `NonEmptyList` value.
• `fx { ... } comprehensions` can be used to imperatively compute over multiple `NonEmptyList` values in sequence.
• `NonEmptyList.applicative().map { ... }` can be used to compute over multiple `NonEmptyList` values preserving type information and abstracting over arity with `map`

### Supported type classes

 Module Type classes arrow.aql Count, From, GroupBy, Max, Min, OrderBy, Select, Sum, Union arrow.optics.typeclasses Each, FilterIndex, Index arrow.typeclasses Applicative, Apply, Bimonad, Comonad, Eq, Foldable, Functor, Hash, Monad, Semigroup, SemigroupK, Show, Traverse