arrow-core-data / arrow.core / NonEmptyList

NonEmptyList

class NonEmptyList<out A> : NonEmptyListOf<A>, AbstractList<A>

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

nonEmptyListOf

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

import arrow.core.nonEmptyListOf

val value =
//sampleStart
 // nonEmptyListOf() // does not compile
 nonEmptyListOf(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.nonEmptyListOf

val value =
//sampleStart
 nonEmptyListOf(1, 2, 3, 4, 5).head
//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
import arrow.core.nonEmptyListOf

//sampleStart
fun sumNel(nel: NonEmptyList<Int>): Int =
 nel.foldLeft(0) { acc, n -> acc + n }
val value = sumNel(nonEmptyListOf(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.nonEmptyListOf

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

Combining NonEmptyLists

flatMap

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

import arrow.core.NonEmptyList
import arrow.core.nonEmptyListOf

//sampleStart
val nelOne: NonEmptyList<Int> = nonEmptyListOf(1, 2, 3)
val nelTwo: NonEmptyList<Int> = nonEmptyListOf(4, 5)

val value = nelOne.flatMap { one ->
 nelTwo.map { two ->
   one + two
 }
}
//sampleEnd
fun 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.NonEmptyList
import arrow.core.nonEmptyListOf
import arrow.core.zip
import java.util.UUID

//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> = 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)
}
//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 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

<init> 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.NonEmptyListNonEmptyList(head: A, tail: List<A>)

Properties

all val all: List<A>
head val head: A
size val size: Int
tail val tail: List<A>

Functions

align fun <B> align(b: NonEmptyList<B>): NonEmptyList<Ior<A, B>>
ap fun <B> ~~ap~~(ff: NonEmptyListOf<(A) -> B>): NonEmptyList<B>
coflatMap fun <B> ~~coflatMap~~(f: (NonEmptyListOf<A>) -> B): NonEmptyList<B>
fun <B> coflatMap(f: (NonEmptyList<A>) -> B): NonEmptyList<B>
equals fun equals(other: Any?): Boolean
extract fun extract(): A
flatMap fun <B> ~~flatMap~~(f: (A) -> NonEmptyListOf<B>): NonEmptyList<B>
fun <B> flatMap(f: (A) -> NonEmptyList<B>): NonEmptyList<B>
foldLeft fun <B> foldLeft(b: B, f: (B, A) -> B): B
foldRight fun <B> ~~foldRight~~(lb: Eval<B>, f: (A, Eval<B>) -> Eval<B>): Eval<B>
get operator fun get(index: Int): A
hashCode fun hashCode(): Int
isEmpty fun isEmpty(): Boolean
map fun <B> map(f: (A) -> B): NonEmptyList<B>
padZip fun <B> padZip(other: NonEmptyList<B>): NonEmptyList<Pair<A?, B?>>
plus operator fun plus(l: NonEmptyList<A>): NonEmptyList<A>
operator fun plus(l: List<A>): NonEmptyList<A>
operator fun plus(a: A): NonEmptyList<A>
salign fun salign(SA: Semigroup<A>, b: NonEmptyList<A>): NonEmptyList<A>
show fun ~~show~~(SA: Show<A>): String
toList fun toList(): List<A>
toString fun toString(): String
traverse fun <G, B> traverse(AG: Applicative<G>, f: (A) -> Kind<G, B>): Kind<G, NonEmptyList<B>>
zip fun <B> zip(fb: NonEmptyList<B>): NonEmptyList<Pair<A, B>>
fun <B, Z> zip(b: NonEmptyList<B>, map: (A, B) -> Z): NonEmptyList<Z>
fun <B, C, Z> zip(b: NonEmptyList<B>, c: NonEmptyList<C>, map: (A, B, C) -> Z): NonEmptyList<Z>
fun <B, C, D, Z> zip(b: NonEmptyList<B>, c: NonEmptyList<C>, d: NonEmptyList<D>, map: (A, B, C, D) -> Z): NonEmptyList<Z>
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>
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>
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>
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>
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>
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>

Companion Object Functions

fromList fun <A> fromList(l: List<A>): Option<NonEmptyList<A>>
fromListUnsafe fun <A> fromListUnsafe(l: List<A>): NonEmptyList<A>
invoke operator fun <A> ~~invoke~~(head: A, vararg t: A): NonEmptyList<A>
just fun <A> ~~just~~(a: A): NonEmptyList<A>
of fun <A> ~~of~~(head: A, vararg t: A): NonEmptyList<A>
tailRecM fun <A, B> ~~tailRecM~~(a: A, f: (A) -> Kind<ForNonEmptyList, Either<A, B>>): NonEmptyList<B>

Extension Functions

altFold fun <T, F, A> Kind<T, A>.altFold(AF: Alternative<F>, FT: Foldable<T>): Kind<F, A>
altSum fun <T, F, A> Kind<T, Kind<F, A>>.altSum(AF: Alternative<F>, FT: Foldable<T>): Kind<F, A>
combineK fun <A> NonEmptyListOf<A>.~~combineK~~(y: NonEmptyListOf<A>): NonEmptyList<A>
compareTo operator fun <A : Comparable<A>> NonEmptyList<A>.compareTo(other: NonEmptyList<A>): Int
fix fun <A> NonEmptyListOf<A>.~~fix~~(): NonEmptyList<A>
flatten fun <A> NonEmptyList<NonEmptyList<A>>.flatten(): NonEmptyList<A>
sequence fun <A, G> NonEmptyListOf<Kind<G, A>>.sequence(GA: Applicative<G>): Kind<G, NonEmptyList<A>>
sequenceEither fun <E, A> NonEmptyList<Either<E, A>>.sequenceEither(): Either<E, NonEmptyList<A>>
sequenceValidated fun <E, A> NonEmptyList<Validated<E, A>>.sequenceValidated(semigroup: Semigroup<E>): Validated<E, NonEmptyList<A>>
traverseEither fun <E, A, B> NonEmptyList<A>.traverseEither(f: (A) -> Either<E, B>): Either<E, NonEmptyList<B>>
traverseValidated fun <E, A, B> NonEmptyList<A>.traverseValidated(semigroup: Semigroup<E>, f: (A) -> Validated<E, B>): Validated<E, NonEmptyList<B>>
unzip fun <A, B> NonEmptyList<Pair<A, B>>.unzip(): Pair<NonEmptyList<A>, NonEmptyList<B>>
fun <A, B, C> NonEmptyList<C>.unzip(f: (C) -> Pair<A, B>): Pair<NonEmptyList<A>, NonEmptyList<B>>

Do you like Arrow?

Arrow Org
<