mgold / elm-nonempty-list / List.Nonempty

A list that cannot be empty. The head and tail can be accessed without Maybes. Most other list functions are available.

Definition


type Nonempty a
    = Nonempty a (List a)

The Nonempty type. If you have both a head and tail, you can construct a nonempty list directly. Otherwise use the helpers below instead.

Create

singleton : a -> Nonempty a

Create a singleton list with the given element.

fromList : List a -> Maybe (Nonempty a)

Create a nonempty list from an ordinary list, failing on the empty list.

Access

head : Nonempty a -> a

Return the head of the list.

tail : Nonempty a -> List a

Return the tail of the list.

toList : Nonempty a -> List a

Convert to an ordinary list.

get : Basics.Int -> Nonempty a -> a

Get the item at the specified index. The head has index 0. Indices are modulused by the length so out-of-range errors can't happen. This means that negative indices are supported, e.g. -1 to get the last element.

last : Nonempty a -> a

Return the last element of the list.

take : Basics.Int -> Nonempty a -> Nonempty a

Create a nonempty list consisting of the first n elements. If n < 1, returns a nonempty list consiting of just the first element

take 2 (Nonempty 1 [ 2, 3 ]) --> Nonempty 1 [ 2 ]

take 0 (Nonempty 1 [ 2, 3 ]) --> fromElement 1

take -3 (Nonempty 1 [ 2, 3 ]) --> fromElement 1

sample : Nonempty a -> Random.Generator a

Create a random generator that returns a value of the nonempty list chosen uniformly at random.

Inspect

Nonempty lists support equality with the usual (==) operator (provided their contents also support equality).

isSingleton : Nonempty a -> Basics.Bool

Determine if the nonempty list has exactly one element.

length : Nonempty a -> Basics.Int

Find the length of the nonempty list.

member : a -> Nonempty a -> Basics.Bool

Determine if an element is present in the nonempty list.

all : (a -> Basics.Bool) -> Nonempty a -> Basics.Bool

Determine if all elements satisfy the predicate.

any : (a -> Basics.Bool) -> Nonempty a -> Basics.Bool

Determine if any elements satisfy the predicate.

Convert

cons : a -> Nonempty a -> Nonempty a

Add another element as the head of the list, pushing the previous head to the tail.

append : Nonempty a -> Nonempty a -> Nonempty a

Append two nonempty lists together. (++) is not supported.

pop : Nonempty a -> Nonempty a

Pop and discard the head, or do nothing for a singleton list. Useful if you want to exhaust a list but hang on to the last item indefinitely.

pop (Nonempty 3 [ 2, 1 ]) --> Nonempty 2 [1]

pop (Nonempty 1 []) --> Nonempty 1 []

reverse : Nonempty a -> Nonempty a

Reverse a nonempty list.

concat : Nonempty (Nonempty a) -> Nonempty a

Flatten a nonempty list of nonempty lists into a single nonempty list.

Swap

replaceHead : a -> Nonempty a -> Nonempty a

Exchange the head element while leaving the tail alone.

replaceTail : List a -> Nonempty a -> Nonempty a

Exchange the tail for another while leaving the head alone.

dropTail : Nonempty a -> Nonempty a

Replace the tail with the empty list while leaving the head alone.

Map

map : (a -> b) -> Nonempty a -> Nonempty b

Map a function over a nonempty list.

indexedMap : (Basics.Int -> a -> b) -> Nonempty a -> Nonempty b

Same as map but the function is also applied to the index of each element (starting at zero).

map2 : (a -> b -> c) -> Nonempty a -> Nonempty b -> Nonempty c

Map a function over two nonempty lists.

andMap : Nonempty a -> Nonempty (a -> b) -> Nonempty b

Map over an arbitrary number of nonempty lists.

map2 (,) xs ys == map (,) xs |> andMap ys

head (map (,,) xs |> andMap ys |> andMap zs) == ( head xs, head ys, head zs )

concatMap : (a -> Nonempty b) -> Nonempty a -> Nonempty b

Map a given function onto a nonempty list and flatten the resulting nonempty lists. If you're chaining, you can define andThen = flip concatMap.

Filter

filter : (a -> Basics.Bool) -> a -> Nonempty a -> Nonempty a

Filter a nonempty list. If all values are filtered out, return the singleton list containing the default value provided. If any value is retained, the default value is not used. If you want to deal with a Maybe instead, use toList >> List.filter yourPredicate >> fromList.

isEven : Int -> Bool
isEven n = modBy 2 n == 0

filter isEven 0 (Nonempty 7 [2, 5]) --> fromElement 2

filter isEven 0 (Nonempty 7 []) --> fromElement 0

Fold

To fold or scan from the right, reverse the list first.

foldl : (a -> b -> b) -> b -> Nonempty a -> b

Reduce a nonempty list from the left with a base case.

foldl (++) "" (Nonempty "a" [ "b", "c" ]) --> "cba"

foldl1 : (a -> a -> a) -> Nonempty a -> a

Reduce a nonempty list from the left without a base case. As per Elm convention, the first argument is the current element and the second argument is the accumulated value. The function is first invoked on the second element, using the first element as the accumulated value, except for singleton lists in which has the head is returned.

foldl1 (++) (Nonempty "a" ["b", "c"]) --> "cba"

foldl1 (++) (fromElement "a") --> "a"

findMe : Int
findMe = 42

minimizeMe : Int -> Int
minimizeMe n = abs (n-findMe)

nearest : Int
nearest = foldl1 (\a b -> if minimizeMe a < minimizeMe b then a else b) (Nonempty 10 [20,30,40,50,60])

nearest --> 40

Zipping

zip : Nonempty a -> Nonempty b -> Nonempty ( a, b )

Take two nonempty lists and compose them into a nonempty list of corresponding pairs.

The length of the new list equals the length of the smallest list given.

unzip : Nonempty ( a, b ) -> ( Nonempty a, Nonempty b )

Decompose a nonempty list of tuples into a tuple of nonempty lists.

batters : Nonempty (String, Int)
batters = Nonempty ("Barry Bonds", 762) [("Hank Aaron", 755), ("Babe Ruth", 714)]

unzip batters --> (Nonempty "Barry Bonds" ["Hank Aaron", "Babe Ruth"], Nonempty 762 [755, 714])

Sort

sort : Nonempty comparable -> Nonempty comparable

Sort a nonempty list of comparable things, lowest to highest.

sortBy : (a -> comparable) -> Nonempty a -> Nonempty a

Sort a nonempty list of things by a derived property.

sortWith : (a -> a -> Basics.Order) -> Nonempty a -> Nonempty a

Sort a nonempty list of things by a custom comparison function.

Deduplicate

The nonempty list's elements must support equality (e.g. not functions). Otherwise you will get a runtime error.

dedup : Nonempty a -> Nonempty a

Remove adjacent duplicate elements from the nonempty list.

dedup (Nonempty 1 [ 2, 2, 1 ]) --> Nonempty 1 [2, 1]

uniq : Nonempty a -> Nonempty a

Remove all duplicate elements from the nonempty list, with the remaining elements ordered by first occurrence.

uniq (Nonempty 1 [ 2, 2, 1 ]) --> Nonempty 1 [2]

Deprecated

fromElement : a -> Nonempty a

Create a singleton list with the given element. Deprecated in favor of singleton, which is what elm-lang/core uses.