List.Nonempty.Ancillary

The List.Nonempty.Ancillary module provides additional convenience functions not found in mgold/elm-nonempty-list for dealing with non-empty lists.

Getting, Setting, and Updating

setAt : Int -> a -> Nonempty a -> Nonempty a

Given an index and a value, replace the element at that index with the given value. Indices are modulus the length of the list, so out-of-range errors cannot occur; this means that negative indices are supported, e.g. -1 to set the last element. This is consistent with the behavior of List.Nonempty.get

Note that this is not particularly efficient (iterating over the entire list multiple times) and should probably not be used for very large lists. Arrays are of course preferable in such cases.

updateAt : Int -> (a -> a) -> Nonempty a -> Nonempty a

Given an index and an update function, replace the value at that index by calling the update function. Indices are modulus the length of the list, so out-of-range errors cannot occur; this means that negative indices are supported, e.g. -1 to update the last element. This is consistent with the behavior of List.Nonempty.get

Note that this is not particularly efficient (iterating over the entire list multiple times) and should probably not be used for very large lists. Arrays are of course preferable in such cases.

Finding Extrema

Find minimum/maximum elements without Maybes.

maximum : Nonempty comparable -> comparable

Find the maximum element in a non-empty list.

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

Given a function to map a type to a comparable type, find the first maximum element in a non-empty list.

maximumWith : (a -> a -> Order) -> Nonempty a -> a

Given a comparison function, find the first maximum element in a non-empty list.

minimum : Nonempty comparable -> comparable

Find the minimum element in a non-empty list.

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

Given a function to map a type to a comparable type, find the first minimum element in a non-empty list.

minimumWith : (a -> a -> Order) -> Nonempty a -> a

Given a comparison function, find the first minimum element in a non-empty list.

Finding Extrema With Indices

Find minimum/maximum elements and their indices without Maybes.

indexedMaximum : Nonempty comparable -> ( Int, comparable )

Find the first maximum element in a non-empty list and its index.

indexedMaximumBy : (a -> comparable) -> Nonempty a -> ( Int, a )

Given a function to map a type to a comparable type, find the first maximum element in a non-empty list and its index.

indexedMaximumWith : (a -> a -> Order) -> Nonempty a -> ( Int, a )

Given a comparison function, find the first maximum element in a non-empty list and its index.

indexedMinimum : Nonempty comparable -> ( Int, comparable )

Find the first minimum element in a non-empty list and its index.

indexedMinimumBy : (a -> comparable) -> Nonempty a -> ( Int, a )

Given a function to map a type to a comparable type, find the first minimum element in a non-empty list and its index.

indexedMinimumWith : (a -> a -> Order) -> Nonempty a -> ( Int, a )

Given a comparison function, find the first minimum element in a non-empty list and its index.

`Maybe`s

combine : Nonempty (Maybe a) -> Maybe (Nonempty a)

If every Maybe in the non-empty list is Just a, then return a list of all the unwrapped values. If one or more elements are Nothing, then the entire output will be Nothing.

combine (Nonempty (Just 1) [ Just 2, Just 3 ])
--> Just (Nonempty 1 [ 2, 3 ])
combine (Nonempty (Just 1) [ Nothing, Just 3 ])
--> Nothing

traverse : (a -> Maybe b) -> Nonempty a -> Maybe (Nonempty b)

Map a function over every element in the non-empty list. If every function call returns Just a, then return a list of all the values. If one or more function call returns Nothing, then the entire output will be Nothing.

traverse List.head (Nonempty [ 1 ] [ [2], [ 3, 4 ] ])
--> Just (Nonempty 1 [ 2, 3 ])
traverse List.head (Nonempty [ 1 ] [ [], [ 3, 4 ] ])
--> Nothing

JSON Decoders/Encoders

The module provides two sets of JSON decoder/encodes. In the first, decodeArray/encodeArray, the non-empty list is represented as a standard JSON array. Decoding an empty array will fail, and encoding to an empty array will never happen.

In the second, decodeObject/encodeObject, the non-empty list is explicitly represented as an object with two keys: "head" (containing the first element) and "tail", containing a (possibly empty) array of the rest of the elements:

{ "head": x1
, "tail": [x2, x3]
}

decodeArray : Decoder a -> Decoder (Nonempty a)

Decode a non-empty list from a JSON array, failing if it is empty.

encodeArray : (a -> Value) -> Nonempty a -> Value

Turn a non-empty list into a JSON array.

decodeObject : Decoder a -> Decoder (Nonempty a)

Decode a non-empty list from a JSON object of the form:

{ "head": x1
, "tail": [x2, x3]
}

encodeObject : (a -> Value) -> Nonempty a -> Value

Encode a non-empty list into a JSON object of the form:

{ "head": x1
, "tail": [x2, x3]
}

Random

shuffle : Nonempty a -> Generator (Nonempty a)

Shuffle the non-empty list. This of course has no effect on a list of one element.

Modules