# NonEmptyList

class NonEmptyList<out A>(val head: A, val tail: List<A>) : AbstractList<A>

`NonEmptyList` is a data type used in Λrrow to model ordered lists that guarantee to have at least one value.

## Constructing NonEmptyList

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

``import arrow.core.nonEmptyListOfimport arrow.core.toNonEmptyListOrNullfun main() { println(nonEmptyListOf(1, 2, 3, 4, 5)) println(listOf(1, 2, 3).toNonEmptyListOrNull()) println(emptyList<Int>().toNonEmptyListOrNull())}``
``NonEmptyList(1, 2, 3, 4, 5)NonEmptyList(1, 2, 3)null``

Unlike `List`, `NonEmptyList.head` it's a safe operation that guarantees no exception throwing.

``import arrow.core.nonEmptyListOfval value =//sampleStart nonEmptyListOf(1, 2, 3, 4, 5).head//sampleEndfun 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.NonEmptyListimport arrow.core.nonEmptyListOf//sampleStartfun sumNel(nel: NonEmptyList<Int>): Int = nel.foldLeft(0) { acc, n -> acc + n }val value = sumNel(nonEmptyListOf(1, 1, 1, 1))//sampleEndfun main() { println("value = \$value")}``

## map

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

``import arrow.core.nonEmptyListOfval value =//sampleStart nonEmptyListOf(1, 1, 1, 1).map { it + 1 }//sampleEndfun main() { println(value)}``

## Combining NonEmptyLists

### flatMap

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

``import arrow.core.NonEmptyListimport arrow.core.nonEmptyListOf//sampleStartval nelOne: NonEmptyList<Int> = nonEmptyListOf(1, 2, 3)val nelTwo: NonEmptyList<Int> = nonEmptyListOf(4, 5)val value = nelOne.flatMap { one -> nelTwo.map { two ->   one + two }}//sampleEndfun main() { println("value = \$value")}``

### zip

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

``import arrow.core.NonEmptyListimport arrow.core.nonEmptyListOfimport arrow.core.zipimport java.util.UUID//sampleStartdata class Person(val id: UUID, val name: String, val year: Int)// Note each NonEmptyList is of a different typeval nelId: NonEmptyList<UUID> = nonEmptyListOf(UUID.randomUUID(), UUID.randomUUID())val nelName: NonEmptyList<String> = nonEmptyListOf("William Alvin Howard", "Haskell Curry")val nelYear: NonEmptyList<Int> = nonEmptyListOf(1926, 1900)val value = nelId.zip(nelName, nelYear) { id, name, year -> Person(id, name, year)}//sampleEndfun 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 `nonEmptyListOf`

• `foldLeft`, `map`, `flatMap` and others are used to compute over the internal contents of a `NonEmptyList` value.

• `a.zip(b, c) { ... }` can be used to compute over multiple `NonEmptyList` values preserving type information and abstracting over arity with `zip`

## Constructors

fun <out A> NonEmptyList(head: A, tail: List<A>)

object Companion

## Functions

fun <B> align(b: NonEmptyList<B>): NonEmptyList<Ior<A, B>>
fun <B> coflatMap(f: (NonEmptyList<A>) -> B): NonEmptyList<B>
open operator override fun contains(element: A): Boolean
open override fun containsAll(elements: Collection<A>): Boolean
open operator override fun equals(other: Any?): Boolean
fun extract(): A
inline fun <B> flatMap(f: (A) -> NonEmptyList<B>): NonEmptyList<B>
inline fun <B> foldLeft(b: B, f: (B, A) -> B): B
open operator override fun get(index: Int): A
open override fun hashCode(): Int
open override fun indexOf(element: A): Int
open override fun isEmpty(): Boolean
open operator override fun iterator(): Iterator<A>
open override fun lastIndexOf(element: A): Int
open override fun listIterator(): ListIterator<A>
open override fun listIterator(index: Int): ListIterator<A>
inline fun <B> map(f: (A) -> B): NonEmptyList<B>
fun <B> padZip(other: NonEmptyList<B>): NonEmptyList<Pair<A?, B?>>
operator fun plus(): NonEmptyList<A>
operator fun plus(): NonEmptyList<A>
operator fun plus(l: List<A>): NonEmptyList<A>
fun salign(SA: Semigroup<A>, ): NonEmptyList<A>
open override fun subList(fromIndex: Int, toIndex: Int): List<A>
fun toList(): List<A>
open override fun toString(): String
fun <B> zip(fb: NonEmptyList<B>): NonEmptyList<Pair<A, B>>
inline fun <B, Z> zip(b: NonEmptyList<B>, map: (A, B) -> Z): NonEmptyList<Z>
inline fun <B, C, Z> zip(    b: NonEmptyList<B>,     c: NonEmptyList<C>,     map: (A, B, C) -> Z): NonEmptyList<Z>
inline fun <B, C, D, Z> zip(    b: NonEmptyList<B>,     c: NonEmptyList<C>,     d: NonEmptyList<D>,     map: (A, B, C, D) -> Z): NonEmptyList<Z>
inline fun <B, C, D, E, Z> zip(    b: NonEmptyList<B>,     c: NonEmptyList<C>,     d: NonEmptyList<D>,     e: NonEmptyList<E>,     map: (A, B, C, D, E) -> Z): NonEmptyList<Z>
inline fun <B, C, D, E, F, Z> zip(    b: NonEmptyList<B>,     c: NonEmptyList<C>,     d: NonEmptyList<D>,     e: NonEmptyList<E>,     f: NonEmptyList<F>,     map: (A, B, C, D, E, F) -> Z): NonEmptyList<Z>
inline fun <B, C, D, E, F, G, Z> zip(    b: NonEmptyList<B>,     c: NonEmptyList<C>,     d: NonEmptyList<D>,     e: NonEmptyList<E>,     f: NonEmptyList<F>,     g: NonEmptyList<G>,     map: (A, B, C, D, E, F, G) -> Z): NonEmptyList<Z>
inline fun <B, C, D, E, F, G, H, Z> zip(    b: NonEmptyList<B>,     c: NonEmptyList<C>,     d: NonEmptyList<D>,     e: NonEmptyList<E>,     f: NonEmptyList<F>,     g: NonEmptyList<G>,     h: NonEmptyList<H>,     map: (A, B, C, D, E, F, G, H) -> Z): NonEmptyList<Z>
inline fun <B, C, D, E, F, G, H, I, Z> zip(    b: NonEmptyList<B>,     c: NonEmptyList<C>,     d: NonEmptyList<D>,     e: NonEmptyList<E>,     f: NonEmptyList<F>,     g: NonEmptyList<G>,     h: NonEmptyList<H>,     i: NonEmptyList<I>,     map: (A, B, C, D, E, F, G, H, I) -> Z): NonEmptyList<Z>
inline fun <B, C, D, E, F, G, H, I, J, Z> zip(    b: NonEmptyList<B>,     c: NonEmptyList<C>,     d: NonEmptyList<D>,     e: NonEmptyList<E>,     f: NonEmptyList<F>,     g: NonEmptyList<G>,     h: NonEmptyList<H>,     i: NonEmptyList<I>,     j: NonEmptyList<J>,     map: (A, B, C, D, E, F, G, H, I, J) -> Z): NonEmptyList<Z>

## Properties

val all: List<A>
open override val size: Int
val tail: List<A>

## Extensions

open override fun NonEmptyList<Any?>.combine(b: NonEmptyList<Any?>): NonEmptyList<Any?>

Combine two A values.

operator fun <A : Comparable<A>> NonEmptyList<A>.compareTo(other: NonEmptyList<A>): Int
fun <A> NonEmptyList<NonEmptyList<A>>.flatten(): NonEmptyList<A>
open fun NonEmptyList<Any?>.maybeCombine(b: NonEmptyList<Any?>?): NonEmptyList<Any?>
open operator fun NonEmptyList<Any?>.plus(b: NonEmptyList<Any?>): NonEmptyList<Any?>
fun <E, A> NonEmptyList<Either<E, A>>.sequence(): Either<E, NonEmptyList<A>>
fun <E, A> NonEmptyList<Validated<E, A>>.sequence(semigroup: Semigroup<E>): Validated<E, NonEmptyList<A>>
fun <A> NonEmptyList<Option<A>>.sequence(): Option<NonEmptyList<A>>
fun <E, A> NonEmptyList<Either<E, A>>.sequenceEither(): Either<E, NonEmptyList<A>>
fun <A> NonEmptyList<Option<A>>.sequenceOption(): Option<NonEmptyList<A>>
fun <E, A> NonEmptyList<Validated<E, A>>.sequenceValidated(semigroup: Semigroup<E>): Validated<E, NonEmptyList<A>>