fabiommendes / elm-sized-list / SizedList

A list with at least one element


type SizedList a

A list of a`s with at least 2 elements.

Meta information can be associated to each segment pair.

Construction

empty : SizedList a

Create a list with only one element

cons : a -> SizedList a -> SizedList a

Add an element to the front of a list.

singleton : a -> SizedList a

Create a list with only one element

repeat : Basics.Int -> a -> SizedList a

Create a list with n (at least 2) copies of a value

range : Basics.Int -> Basics.Int -> SizedList Basics.Int

Create list from a range of values.

The first value is guaranteed to appear in the list.

fromList : List a -> SizedList a

Try to create sequence from a list

Transform

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

Apply a function to every element of a list.

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

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

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

Reduce a list from the left.

foldr : (a -> b -> b) -> b -> SizedList a -> b

Reduce a list from the right.

Filtering

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

Keep elements that satisfy the test.

Return a list, since result might be empty.

filterMap : (a -> Maybe b) -> SizedList a -> SizedList b

Filter out certain values.

Return a list, since result might be empty.

Combine

append : SizedList a -> SizedList a -> SizedList a

Put two lists together.

append (range 1 3) (range 4 5) == range 1 5

concat : SizedList (SizedList a) -> SizedList a

Concatenate a bunch of lists into a single list

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

Map a given function onto a list and flatten the resulting lists.

concatMap f xs == concat (map f xs)

intersperse : a -> SizedList a -> SizedList a

Places the given value between all members of the given list.

map2 : (a -> b -> r) -> SizedList a -> SizedList b -> SizedList r

Apply a two argument function pairwise to elements of both lists

map3 : (a -> b -> c -> r) -> SizedList a -> SizedList b -> SizedList c -> SizedList r

Apply a 3 argument function tuples of elements from all lists

map4 : (a -> b -> c -> d -> r) -> SizedList a -> SizedList b -> SizedList c -> SizedList d -> SizedList r

Apply a 4 argument function tuples of elements from all lists

map5 : (a -> b -> c -> d -> e -> r) -> SizedList a -> SizedList b -> SizedList c -> SizedList d -> SizedList e -> SizedList r

Apply a 5 argument function tuples of elements from all lists

Sort

sort : SizedList comparable -> SizedList comparable

Sort values from lowest to highest

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

Sort values by a derived property.

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

Sort values with a custom comparison function.

This is also the most general sort function, allowing you to define any other: sort == sortWith compare

Deconstruct

isEmpty : SizedList a -> Basics.Bool

Always return False, since SizedList is never empty :)

head : SizedList a -> Maybe a

Return the first element

head (range 1 5) == 1

tail : SizedList a -> Maybe (SizedList a)

Extract the rest of the list.

head (range 1 5) == [ 2, 3, 4, 5 ]

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

Take (at most) the first n elements.

The number of elements n must be n >= 1, otherwise it returns the singleton list.

take 2 (range 1 5)
    |> toList
    == [ 1, 2 ]

WARNING: differently from lists, append (take n lst) (drop n lst) do not always recover the original list.

drop : Basics.Int -> SizedList a -> SizedList a

Drop (at most) the first n elements.

The resulting list will have at least one element

drop 2 (range 1 5)
    |> toList
    == [ 3, 4, 5 ]

partition : (a -> Basics.Bool) -> SizedList a -> ( SizedList a, SizedList a )

Partition a list based on some test.

The first list contains all values that satisfy the test, and the second list contains all the value that do not.

uncons : SizedList a -> Maybe ( a, SizedList a )

Deconstruct list into the head and tail parts

uncons (range 1 5)
    == ( 1, [ 2, 3, 4, 5 ] )

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

Decompose a list of tuples into a tuple of lists.

unzip (create ( "a", 1 ) [ ( "b", 2 ), ( "c", 3 ) ])
    == ( SizedList "a" [ "b", "c" ], SizedList 1 [ 2, 3 ] )

Utilities

length : SizedList a -> Basics.Int

Determine the length of a list.

length (range 1 5) == 5

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

Determine if all elements satisfy some test.

all (\x -> modBy 2 == 0) (range 1 5) == False

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

Determine if any elements satisfy some test.

any (\x -> modBy 2 == 0) (range 1 5) == True

minimum : SizedList comparable -> Maybe comparable

Find the minimum element in a non-empty list.

minimum (range 1 5) == 5

maximum : SizedList comparable -> Maybe comparable

Find the maximum element in a non-empty list.

maximum (range 1 5) == 5

sum : SizedList number -> number

Get the sum of the list elements.

sum (range 1 5) == 1 + 2 + 3 + 4 + 5

product : SizedList number -> number

Get the product of the list elements.

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

Figure out whether a list contains a value.

member 42 (range 1 3) == False

reverse : SizedList a -> SizedList a

Reverse a list.

reverse (range 1 3)
    |> toList
    == [ 5, 4, 3, 2, 1 ]

toList : SizedList a -> List a

Convert data to list

Indexed operations

getAt : Basics.Int -> SizedList a -> Maybe a

Returns Just the element at the given index in the list, or Nothing if the index is out of range.

getAt 1 (range 1 5) == Just 2

removeAt : Basics.Int -> SizedList a -> SizedList a

Remove the element at an index from a list.

Return the original list if the index is out of range or if the resulting list would be empty.

removeAt 2 negate (range 1 5)
    |> toList
    == [ 1, 2, 4, 5 ]

updateAt : Basics.Int -> (a -> a) -> SizedList a -> SizedList a

Update element at the given index

updateAt 2 negate (range 1 5)
    |> toList
    == [ 1, 2, -3, 4, 5 ]

Unsafe operations

unsafeFromList : Basics.Int -> List a -> SizedList a

Unsafe version of fromList.

WARNING: Use it only when you know the list length for sure.

Using this function, we can wrap a regular list without scanning for its length, which is considerably faster. However, it can also create inconsistent objects with a reported size is different from the actual data length.