lists(3erl)

📦
version 25.3.2.8 · 5 versions
, in ubuntu noble

💖 lists — the Erlang module that literally does your list homework 💖

okay so bestie, this is lists(3erl) from the Erlang Module Definition era, and it's giving the module for list processing functions. this is part 1 of 4 (yes there's more, don't leave yet), so grab a snack and let's get into it 🍓

✨ NAME ✨

lists — List processing functions. periodt. that's the whole vibe.

🌸 DESCRIPTION 🌸

This module contains functions for list processing. it's literally the main character of list modules, no cap.

Unless otherwise stated, all functions assume that position numbering starts at 1. That is, the first element of a list is at position 1. so not zero-indexed bestie, we're not doing that here 💅

Two terms T1 and T2 compare equal if T1 == T2 evaluates to true. They match if T1 =:= T2 evaluates to true. yes there's a difference between equal and match, and yes it matters, iykyk.

Whenever an ordering function F is expected as argument, it is assumed that the following properties hold of F for all x, y, and z:

  • If x F y and y F x, then x = y (F is antisymmetric).
  • If x F y and y F z, then x F z (F is transitive).
  • x F y or y F x (F is total).

An example of a typical ordering function is less than or equal to: =</2. iconic behavior honestly.

👑 EXPORTS 👑

all(Pred, List) -> boolean() 🌈

Types:

Pred = fun((Elem :: T) -> boolean())
List = [T]
T = term()

Returns true if Pred(Elem) returns true for all elements Elem in List, otherwise false. The Pred function must return a boolean. so if your predicate is out here returning vibes instead of booleans, it's gonna be a problem, just saying 🫶

any(Pred, List) -> boolean() ⭐

Types:

Pred = fun((Elem :: T) -> boolean())
List = [T]
T = term()

Returns true if Pred(Elem) returns true for at least one element Elem in List. The Pred function must return a boolean. literally just needs one match bestie, just one. it's giving "i only need one friend who gets me" energy 💀

append(ListOfLists) -> List1 🎀

Types:

ListOfLists = [List]
List = List1 = [T]
T = term()

Returns a list in which all the sublists of ListOfLists have been appended. it's giving merger energy, slay.

Example:

> lists:append([[1, 2, 3], [a, b], [4, 5, 6]]).
[1,2,3,a,b,4,5,6]

append(List1, List2) -> List3 💅

Types:

List1 = List2 = List3 = [T]
T = term()

Returns a new list List3, which is made from the elements of List1 followed by the elements of List2. it's the "you come first, then them" of list operations, we love a respectful king 👑

Example:

> lists:append("abc", "def").
"abcdef"

lists:append(A, B) is equivalent to A ++ B. no cap, same thing.

concat(Things) -> string() 🦋

Types:

Things = [Thing]
Thing = atom() | integer() | float() | string()

Concatenates the text representation of the elements of Things. The elements of Things can be atoms, integers, floats, or strings. it's literally the "make it make sense as a string" function, and it ate.

Example:

> lists:concat([doc, '/', file, '.', 3]).
"doc/file.3"

delete(Elem, List1) -> List2 🌸

Types:

Elem = T
List1 = List2 = [T]
T = term()

Returns a copy of List1 where the first element matching Elem is deleted, if there is such an element. just the FIRST one bestie, not all of them, don't get it twisted. it's giving "i'm removing you from the group chat but only once" energy 🙈

droplast(List) -> InitList 💜

Types:

List = [T, ...]
InitList = [T]
T = term()

Drops the last element of a List. The list is to be non-empty, otherwise the function crashes with a function_clause. so like, if you pass an empty list it's gonna be a whole situation, and not the cute kind 😭

⚠️ warning bestie: empty list = crash. do not pass go, do not collect $200.

dropwhile(Pred, List1) -> List2 ✨

Types:

Pred = fun((Elem :: T) -> boolean())
List1 = List2 = [T]
T = term()

Drops elements Elem from List1 while Pred(Elem) returns true and returns the remaining list. The Pred function must return a boolean. it's giving "keep dropping until the vibe check fails" and honestly same.

duplicate(N, Elem) -> List 🎀

Types:

N = integer() >= 0
Elem = T
List = [T]
T = term()

Returns a list containing N copies of term Elem. it's the "copy paste copy paste copy paste" function and it understood the assignment.

Example:

> lists:duplicate(5, xx).
[xx,xx,xx,xx,xx]

enumerate(List1) -> List2 🌈

Types:

List1 = [T]
List2 = [{Index, T}]
Index = integer()
T = term()

Returns List1 with each element H replaced by a tuple of form {I, H} where I is the position of H in List1. The enumeration starts with 1 and increases by 1 in each step. it's literally adding an index like a spreadsheet but make it functional, we love to see it.

That is, enumerate/1 behaves as if it had been defined as follows:

enumerate(List) ->
  {List1, _ } = lists:mapfoldl(fun(T, Acc) -> {{Acc, T}, Acc+1} end, 1, List),
  List1.

Example:

> lists:enumerate([a,b,c]).
[{1,a},{2,b},{3,c}]

enumerate(Index, List1) -> List2 🔥

Types:

List1 = [T]
List2 = [{Index, T}]
Index = integer()
T = term()

Returns List1 with each element H replaced by a tuple of form {I, H} where I is the position of H in List1. The enumeration starts with Index and increases by 1 in each step. so you can start wherever you want, it's giving customizable energy and we're obsessed.

That is, enumerate/2 behaves as if it had been defined as follows:

enumerate(I, List) ->
  {List1, _ } = lists:mapfoldl(fun(T, Acc) -> {{Acc, T}, Acc+1} end, I, List),
  List1.

Example:

> lists:enumerate(10, [a,b,c]).
[{10,a},{11,b},{12,c}]

filter(Pred, List1) -> List2 🧚

Types:

Pred = fun((Elem :: T) -> boolean())
List1 = List2 = [T]
T = term()

List2 is a list of all elements Elem in List1 for which Pred(Elem) returns true. The Pred function must return a boolean. it's the "keep only the ones that pass the vibe check" function and it ate, no crumbs.

filtermap(Fun, List1) -> List2 💀

Types:

Fun = fun((Elem) -> boolean() | {true, Value})
List1 = [Elem]
List2 = [Elem | Value]
Elem = Value = term()

Calls Fun(Elem) on successive elements Elem of List1. Fun/1 must return either a Boolean or a tuple {true, Value}. The function returns the list of elements for which Fun returns a new value, where a value of true is synonymous with {true, Elem}. so you can filter AND map at the same time, it's giving multitasking queen and honestly? iconic.

That is, filtermap behaves as if it had been defined as follows:

filtermap(Fun, List1) ->
    lists:foldr(fun(Elem, Acc) ->
                       case Fun(Elem) of
                           false -> Acc;
                           true -> [Elem|Acc];
                           {true,Value} -> [Value|Acc]
                       end
                end, [], List1).

Example:

> lists:filtermap(fun(X) -> case X rem 2 of 0 -> {true, X div 2}; _ -> false end end, [1,2,3,4,5]).
[1,2]

flatlength(DeepList) -> integer() >= 0 🦋

Types:

DeepList = [term() | DeepList]

Equivalent to length(flatten(DeepList)), but more efficient. so it's the same result but faster, it's giving "work smarter not harder" and we respect it.

flatmap(Fun, List1) -> List2 🌸

Types:

Fun = fun((A) -> [B])
List1 = [A]
List2 = [B]
A = B = term()

Takes a function from As to lists of Bs, and a list of As (List1) and produces a list of Bs by applying the function to every element in List1 and appending the resulting lists. it's giving "map then flatten" but as one function, and honestly that's efficiency.

That is, flatmap behaves as if it had been defined as follows:

flatmap(Fun, List1) ->
    append(map(Fun, List1)).

Example:

> lists:flatmap(fun(X)->[X,X] end, [a,b,c]).
[a,a,b,b,c,c]

flatten(DeepList) -> List 🎀

Types:

DeepList = [term() | DeepList]
List = [term()]

Returns a flattened version of DeepList. it's the "un-nest me please" function and honestly relatable.

flatten(DeepList, Tail) -> List 💜

Types:

DeepList = [term() | DeepList]
Tail = List = [term()]

Returns a flattened version of DeepList with tail Tail appended. same as above but you get to add a tail at the end, it's giving "flatten plus bonus content" and we love an overachiever.

foldl(Fun, Acc0, List) -> Acc1 ⭐

Types:

Fun = fun((Elem :: T, AccIn) -> AccOut)
Acc0 = Acc1 = AccIn = AccOut = term()
List = [T]
T = term()

Calls Fun(Elem, AccIn) on successive elements A of List, starting with AccIn == Acc0. Fun/2 must return a new accumulator, which is passed to the next call. The function returns the final value of the accumulator. Acc0 is returned if the list is empty. it's the "fold it left" function, going from left to right like a little caterpillar, and it's giving main character energy.

Example:

> lists:foldl(fun(X, Sum) -> X + Sum end, 0, [1,2,3,4,5]).
15
> lists:foldl(fun(X, Prod) -> X * Prod end, 1, [1,2,3,4,5]).
120

foldr(Fun, Acc0, List) -> Acc1 🌈

Types:

Fun = fun((Elem :: T, AccIn) -> AccOut)
Acc0 = Acc1 = AccIn = AccOut = term()
List = [T]
T = term()

Like foldl/3, but the list is traversed from right to left. so same energy but backwards, it's giving "i do things my own way" and honestly same.

Example:

> P = fun(A, AccIn) -> io:format("~p ", [A]), AccIn end.
#Fun<erl_eval.12.2225172>
> lists:foldl(P, void, [1,2,3]).
1 2 3 void
> lists:foldr(P, void, [1,2,3]).
3 2 1 void

foldl/3 is tail recursive and is usually preferred to foldr/3. so bestie, if you have to choose, go with foldl/3 unless you have a specific reason not to, okay? 🫶

join(Sep, List1) -> List2 ✨

Types:

Sep = T
List1 = List2 = [T]
T = term()

Inserts Sep between each element in List1. Has no effect on the empty list and on a singleton list. it's giving "placing little separators between your friends so they don't get too close" and honestly same.

Example:

> lists:join(x, [a,b,c]).
[a,x,b,x,c]
> lists:join(x, [a]).
[a]
> lists:join(x, []).
[]

foreach(Fun, List) -> ok 💅

Types:

Fun = fun((Elem :: T) -> term())
List = [T]
T = term()

Calls Fun(Elem) for each element Elem in List. This function is used for its side effects and the evaluation order is defined to be the same as the order of the elements in the list. it's giving "do the thing for each one, in order, no skipping" and it ate.

keydelete(Key, N, TupleList1) -> TupleList2 🔥

Types:

Key = term()
N = integer() >= 1
   1..tuple_size(Tuple)
TupleList1 = TupleList2 = [Tuple]
Tuple = tuple()

Returns a copy of TupleList1 where the first occurrence of a tuple whose Nth element compares equal to Key is deleted, if there is such a tuple. just the FIRST one bestie, not all of them, don't get it twisted. it's giving "i'm removing you from the tuple group chat but only once" energy 🙈

keyfind(Key, N, TupleList) -> Tuple | false 💀

Types:

Key = term()
N = integer() >= 1
   1..tuple_size(Tuple)
TupleList = [Tuple]
Tuple = tuple()

Searches the list of tuples TupleList for a tuple whose Nth element compares equal to Key. Returns Tuple if such a tuple is found, otherwise false. it's the "find your person by their number" function and it's giving detective energy, we love a good search.

keymap(Fun, N, TupleList1) -> TupleList2 🎀

Types:

Fun = fun((Term1 :: term()) -> Term2 :: term())
N = integer() >= 1
   1..tuple_size(Tuple)
TupleList1 = TupleList2 = [Tuple]
Tuple = tuple()

...and bestie that's where part 1 wraps up! the keymap function definition is literally cut off here mid-types, but don't worry, part 2 is coming with the rest of it and honestly? we're obsessed with a cliffhanger. see you in the next part 💖

...and it hands you back a list of tuples where, for every tuple in TupleList1, the Nth element Term1 got swapped out for whatever Fun(Term1) gave back ✨

Example, live and in color:

> Fun = fun(Atom) -> atom_to_list(Atom) end.
#Fun<erl_eval.6.10732646>
2> lists:keymap(Fun, 2, [{name,jane,22},{name,lizzie,20},{name,lydia,15}]).
[{name,"jane",22},{name,"lizzie",20},{name,"lydia",15}]

🎀 keymember(Key, N, TupleList) -> boolean()

Types:

Key = term()
N = integer() >= 1
  1..tuple_size(Tuple)
TupleList = [Tuple]
Tuple = tuple()

gives you true if some tuple in TupleList has an Nth element that compares equal to Key, and false if literally nobody does 🙈

🔑 keymerge(N, TupleList1, TupleList2) -> TupleList3

Types:

N = integer() >= 1
  1..tuple_size(Tuple)
TupleList1 = [T1]
TupleList2 = [T2]
TupleList3 = [T1 | T2]
T1 = T2 = Tuple
Tuple = tuple()

merges TupleList1 and TupleList2 into one sorted list, and the merge key is the Nth element of each tuple 💅

⚠️ both TupleList1 and TupleList2 must already be key-sorted before you call this. No exceptions, bestie.

When two tuples compare equal, the one from TupleList1 wins and gets picked before the one from TupleList2. Loyalty!

🩹 keyreplace(Key, N, TupleList1, NewTuple) -> TupleList2

Types:

Key = term()
N = integer() >= 1
  1..tuple_size(Tuple)
TupleList1 = TupleList2 = [Tuple]
NewTuple = Tuple
Tuple = tuple()

hands you a copy of TupleList1 where the first tuple T whose Nth element compares equal to Key gets replaced with NewTuple — but only if such a tuple T actually exists, otherwise it just... doesn't ✨

🔍 keysearch(Key, N, TupleList) -> {value, Tuple} | false

Types:

Key = term()
N = integer() >= 1
  1..tuple_size(Tuple)
TupleList = [Tuple]
Tuple = tuple()

digs through the list of tuples TupleList looking for a tuple whose Nth element compares equal to Key. Found it? You get {value, Tuple}. Didn't find it? false, sorry babe 😭

Note: this function is kept around for backward compatibility only. keyfind/3 is usually more convenient — like, it's the upgrade, iykyk 🦋

📊 keysort(N, TupleList1) -> TupleList2

Types:

N = integer() >= 1
  1..tuple_size(Tuple)
TupleList1 = TupleList2 = [Tuple]
Tuple = tuple()

returns a list with the sorted elements of TupleList1, and the sorting happens on the Nth element of the tuples. And the sort is stable — meaning equal elements keep their original order, no chaos, no drama 👑

💾 keystore(Key, N, TupleList1, NewTuple) -> TupleList2

Types:

Key = term()
N = integer() >= 1
  1..tuple_size(Tuple)
TupleList1 = [Tuple]
TupleList2 = [Tuple, ...]
NewTuple = Tuple
Tuple = tuple()

returns a copy of TupleList1 where the first tuple T whose Nth element compares equal to Key gets replaced with NewTuple — same energy as keyreplace, but with a glow-up: if there is no such tuple T, you get a copy of TupleList1 with [NewTuple] appended to the end instead 🫶

🍒 keytake(Key, N, TupleList1) -> {value, Tuple, TupleList2} | false

Types:

Key = term()
N = integer() >= 1
  1..tuple_size(Tuple)
TupleList1 = TupleList2 = [tuple()]
Tuple = tuple()

searches TupleList1 for a tuple whose Nth element compares equal to Key. If it finds one you get {value, Tuple, TupleList2} — where TupleList2 is a copy of TupleList1 with the first occurrence of Tuple removed. If not, false 💀

🌙 last(List) -> Last

Types:

List = [T, ...]
Last = T
T = term()

the final element of List. The end. Periodt.

🗺️ map(Fun, List1) -> List2

Types:

Fun = fun((A) -> B)
List1 = [A]
List2 = [B]
A = B = term()

takes a function from As to Bs plus a list of As, and produces a list of Bs by applying the function to every single element. It's the return values you're collecting 💖

The evaluation order depends on the implementation — so don't go assuming anything about order, bestie.

🌀 mapfoldl(Fun, Acc0, List1) -> {List2, Acc1}

Types:

Fun = fun((A, AccIn) -> {B, AccOut})
Acc0 = Acc1 = AccIn = AccOut = term()
List1 = [A]
List2 = [B]
A = B = term()

map/2 and foldl/3 combined into one single pass — literally two birds, one iconic stone 🦋

Example — summing the elements in a list and doubling them at the same time:

> lists:mapfoldl(fun(X, Sum) -> {2*X, X+Sum} end,
0, [1,2,3,4,5]).
{[2,4,6,8,10],15}

🍃 mapfoldr(Fun, Acc0, List1) -> {List2, Acc1}

Types:

Fun = fun((A, AccIn) -> {B, AccOut})
Acc0 = Acc1 = AccIn = AccOut = term()
List1 = [A]
List2 = [B]
A = B = term()

same deal, but it's map/2 and foldr/3 in one pass instead 💫

👑 max(List) -> Max

Types:

List = [T, ...]
Max = T
T = term()

returns the first element of List that compares greater than or equal to all the other elements. Not the biggest-and-only — the first one to hit that bar 🌈

🫶 member(Elem, List) -> boolean()

Types:

Elem = T
List = [T]
T = term()

true if Elem matches some element of List, false otherwise. Does what it says on the tin, no cap 💅

🧚 merge(ListOfLists) -> List1

Types:

ListOfLists = [List]
List = List1 = [T]
T = term()

merges all the sublists of ListOfLists into one sorted list 🎀

All the sublists must be sorted before you call this, fr fr.

When two elements compare equal, the element from the sublist with the lowest position in ListOfLists gets picked before the other one. First come, first served!

🌸 merge(List1, List2) -> List3

Types:

List1 = [X]
List2 = [Y]
List3 = [X | Y]
X = Y = term()

merges List1 and List2 into one sorted list. Both of them must be sorted before you call it. When two elements compare equal, the element from List1 beats the element from List2 💖

🦋 merge(Fun, List1, List2) -> List3

Types:

Fun = fun((A, B) -> boolean())
List1 = [A]
List2 = [B]
List3 = [A | B]
A = B = term()

same merge, but you bring your own ordering 💫 Both List1 and List2 must be sorted according to the ordering function Fun before you call this. Fun(A, B) should return true if A compares less than or equal to B in your ordering, and false otherwise. Ties? Element from List1 wins over the one from List2 👑

🌈 merge3(List1, List2, List3) -> List4

Types:

List1 = [X]
List2 = [Y]
List3 = [Z]
List4 = [X | Y | Z]
X = Y = Z = term()

three-way merge, because why merge two when you can merge three 😤 List1, List2, and List3 must all be sorted before you call this. When two elements compare equal: the element from List1 gets picked first if there is one; otherwise the element from List2 gets picked before the element from List3 🎀

🍓 min(List) -> Min

Types:

List = [T, ...]
Min = T
T = term()

returns the first element of List that compares less than or equal to all the other elements 💜

🔢 nth(N, List) -> Elem

Types:

N = integer() >= 1
  1..length(List)
List = [T, ...]
Elem = T
T = term()

element number N of List. Counting starts at 1, obviously 💅

Example:

> lists:nth(3, [a, b, c, d, e]).
c

🌿 nthtail(N, List) -> Tail

Types:

N = integer() >= 0
  0..length(List)
List = [T, ...]
Tail = [T]
T = term()

returns the Nth tail of List — aka the sublist of List starting at N+1 and running all the way to the end of the list ✨

Example

> lists:nthtail(3, [a, b, c, d, e]).
[d,e]
> tl(tl(tl([a, b, c, d, e]))).
[d,e]
> lists:nthtail(0, [a, b, c, d, e]).
[a,b,c,d,e]
> lists:nthtail(5, [a, b, c, d, e]).
[]

🎀 partition(Pred, List) -> {Satisfying, NotSatisfying}

Types:

Pred = fun((Elem :: T) -> boolean())
List = Satisfying = NotSatisfying = [T]
T = term()

splits List into two lists: the first one holds every element where Pred(Elem) returned true, the second holds every element where Pred(Elem) returned false. It's giving "sorted into two friend groups" 🙈

Examples:

> lists:partition(fun(A) -> A rem 2 == 1 end, [1,2,3,4,5,6,7]).
{[1,3,5,7],[2,4,6]}
> lists:partition(fun(A) -> is_atom(A) end, [a,b,1,c,d,2,3,4,e]).
{[a,b,c,d,e],[1,2,3,4]}

For a different way to partition a list, see splitwith/2 🦋

🧵 prefix(List1, List2) -> boolean()

Types:

List1 = List2 = [T]
T = term()

true if List1 is a prefix of List2, otherwise false 💫

🔄 reverse(List1) -> List2

Types:

List1 = List2 = [T]
T = term()

returns a list with the elements of List1 in reverse order. Flip it and reverse it 💅

🌪️ reverse(List1, Tail) -> List2

Types:

List1 = [T]
Tail = term()
List2 = [T]
T = term()

reverse of List1, but with Tail appended on the end — the efficient glow-up version 😌

Example:

> lists:reverse([1, 2, 3, 4], [a, b, c]).
[4,3,2,1,a,b,c]

🔎 search(Pred, List) -> {value, Value} | false

Types:

Pred = fun((T) -> boolean())
List = [T]
Value = T

okay so if there’s a Value in List where Pred(Value) returns true, you get {value, Value} for the first one that matches — otherwise it’s false, bestie. and yes, Pred has to return a boolean, no cap. 💅

seq(From, To) -> Seq / seq(From, To, Incr) -> Seq

Types:

From = To = Incr = integer()
Seq = [integer()]

this one hands you a sequence of integers, starting at From and adding Incr to the previous element over and over until To is reached or passed. if it gets passed, To is not an element of the sequence — tragic but true. Incr defaults to 1. ✨

Failures:

  • if To < From - Incr and Incr > 0.
  • if To > From - Incr and Incr < 0.
  • if Incr =:= 0 and From =/= To.

these equalities hold for all sequences, periodt:

length(lists:seq(From, To)) =:= To - From + 1
length(lists:seq(From, To, Incr)) =:= (To - From + Incr) div Incr

Examples:

> lists:seq(1, 10).
[1,2,3,4,5,6,7,8,9,10]
> lists:seq(1, 20, 3).
[1,4,7,10,13,16,19]
> lists:seq(1, 0, 1).
[]
> lists:seq(10, 6, 4).
[]
> lists:seq(1, 1, 0).
[1]

sort(List1) -> List2

Types:

List1 = List2 = [T]
T = term()

returns a list containing the sorted elements of List1. slay. ✨

sort(Fun, List1) -> List2

Types:

Fun = fun((A :: T, B :: T) -> boolean())
List1 = List2 = [T]
T = term()

returns a list containing the sorted elements of List1, according to the ordering function Fun. Fun(A, B) is to return true if A compares less than or equal to B in the ordering, otherwise false. no cap. 🫶

split(N, List1) -> {List2, List3}

Types:

N = integer() >= 0
   0..length(List1)
List1 = List2 = List3 = [T]
T = term()

splits List1 into List2 and List3. List2 contains the first N elements, and List3 contains the remaining elements — aka the Nth tail. 💜

splitwith(Pred, List) -> {List1, List2}

Types:

Pred = fun((T) -> boolean())
List = List1 = List2 = [T]
T = term()

partitions List into two lists according to Pred. splitwith/2 behaves as if it is defined as follows:

splitwith(Pred, List) ->
    {takewhile(Pred, List), dropwhile(Pred, List)}.

Examples:

> lists:splitwith(fun(A) -> A rem 2 == 1 end, [1,2,3,4,5,6,7]).
{[1],[2,3,4,5,6,7]}
> lists:splitwith(fun(A) -> is_atom(A) end, [a,b,1,c,d,2,3,4,e]).
{[a,b],[1,c,d,2,3,4,e]}

the Pred function must return a boolean. for a different way to partition a list, see partition/2. 🌸

sublist(List1, Len) -> List2

Types:

List1 = List2 = [T]
Len = integer() >= 0
T = term()

returns the sublist of List1 starting at position 1 and with (maximum) Len elements. it is not an error for Len to exceed the length of the list — in that case the whole list is returned. iconic. 🎀

sublist(List1, Start, Len) -> List2

Types:

List1 = List2 = [T]
Start = integer() >= 1
   1..(length(List1)+1)
Len = integer() >= 0
T = term()

returns the sublist of List1 starting at Start and with (maximum) Len elements. it is not an error for Start+Len to exceed the length of the list. ✨

Examples:

> lists:sublist([1,2,3,4], 2, 2).
[2,3]
> lists:sublist([1,2,3,4], 2, 5).
[2,3,4]
> lists:sublist([1,2,3,4], 5, 2).
[]

subtract(List1, List2) -> List3

Types:

List1 = List2 = List3 = [T]
T = term()

returns a new list List3 that is a copy of List1, subjected to the following procedure: for each element in List2, its first occurrence in List1 is deleted. yes bestie, first occurrence only. 💅

Example:

> lists:subtract("123212", "212").
"312".

lists:subtract(A, B) is equivalent to A -- B. periodt.

suffix(List1, List2) -> boolean()

Types:

List1 = List2 = [T]
T = term()

returns true if List1 is a suffix of List2, otherwise false. simple as. 🦋

sum(List) -> number()

Types:

List = [number()]

returns the sum of the elements in List. math girlie behavior. 🔥

takewhile(Pred, List1) -> List2

Types:

Pred = fun((Elem :: T) -> boolean())
List1 = List2 = [T]
T = term()

takes elements Elem from List1 while Pred(Elem) returns true. that means it returns the longest prefix of the list for which all elements satisfy the predicate. the Pred function must return a boolean. no cap. 🌺

ukeymerge(N, TupleList1, TupleList2) -> TupleList3

Types:

N = integer() >= 1
   1..tuple_size(Tuple)
TupleList1 = [T1]
TupleList2 = [T2]
TupleList3 = [T1 | T2]
T1 = T2 = Tuple
Tuple = tuple()

returns the sorted list formed by merging TupleList1 and TupleList2. the merge is performed on the Nth element of each tuple. both TupleList1 and TupleList2 must be key-sorted without duplicates before evaluating this function. when two tuples compare equal, the tuple from TupleList1 is picked and the one from TupleList2 is deleted. 💅

ukeysort(N, TupleList1) -> TupleList2

Types:

N = integer() >= 1
   1..tuple_size(Tuple)
TupleList1 = TupleList2 = [Tuple]
Tuple = tuple()

returns a list containing the sorted elements of list TupleList1 where all except the first tuple of the tuples comparing equal have been deleted. sorting is performed on the Nth element of the tuples. ✨

umerge(ListOfLists) -> List1

Types:

ListOfLists = [List]
List = List1 = [T]
T = term()

returns the sorted list formed by merging all the sublists of ListOfLists. all sublists must be sorted and contain no duplicates before evaluating this function. when two elements compare equal, the element from the sublist with the lowest position in ListOfLists is picked and the other is deleted. 👑

umerge(List1, List2) -> List3

Types:

List1 = [X]
List2 = [Y]
List3 = [X | Y]
X = Y = term()

returns the sorted list formed by merging List1 and List2. both List1 and List2 must be sorted and contain no duplicates before evaluating this function. when two elements compare equal, the element from List1 is picked and the one from List2 is deleted. 🫶

umerge(Fun, List1, List2) -> List3

Types:

Fun = fun((A, B) -> boolean())
List1 = [A]
List2 = [B]
List3 = [A | B]
A = B = term()

returns the sorted list formed by merging List1 and List2. both List1 and List2 must be sorted according to the ordering function Fun and contain no duplicates before evaluating this function. Fun(A, B) is to return true if A compares less than or equal to B in the ordering, otherwise false. when two elements compare equal, the element from List1 is picked and the one from List2 is deleted. 😭

umerge3(List1, List2, List3) -> List4

Types:

List1 = [X]
List2 = [Y]
List3 = [Z]
List4 = [X | Y | Z]
X = Y = Z = term()

returns the sorted list formed by merging List1, List2, and List3. all of List1, List2, and List3 must be sorted and contain no duplicates before evaluating this function. when two elements compare equal, the element from List1 is picked if there is such an element, otherwise the element from List2 is picked, and the other is deleted. 💀

unzip(List1) -> {List2, List3}

Types:

List1 = [{A, B}]
List2 = [A]
List3 = [B]
A = B = term()

“unzips” a list of two-tuples into two lists, where the first list contains the first element of each tuple, and the second list contains the second element of each tuple. slay. 🎀

unzip3(List1) -> {List2, List3, List4}

Types:

List1 = [{A, B, C}]
List2 = [A]
List3 = [B]
List4 = [C]
A = B = C = term()

“unzips” a list of three-tuples into three lists, where the first list contains the first element of each tuple, the second list contains the second element of each tuple, and the third list contains the third element of each tuple. iconic. 🌈

usort(List1) -> List2

Types:

List1 = List2 = [T]
T = term()

returns a list containing the sorted elements of List1 where all except the first element of the elements comparing equal have been deleted. no duplicates energy. ✨

usort(Fun, List1) -> List2

Types:

Fun = fun((T, T) -> boolean())
List1 = List2 = [T]
T = term()

returns a list containing the sorted elements of List1 where all except the first element of the elements comparing equal according to the ordering function Fun have been deleted. Fun(A, B) is to return true if A compares less than or equal to B in the ordering, otherwise false. 💜

zip(List1, List2) -> List3

Types:

List1 = [A]
List2 = [B]
List3 = [{A, B}]
A = B = term()

“zips” two lists of equal length into one list of two-tuples, where the first element of each tuple is taken from the first list and the second element is taken from the corresponding element in the second list. 🦋

zip3(List1, List2, List3) -> List4

Types:

List1 = [A]
List2 = [B]
List3 = [C]
List4 = [{A, B, C}]
A = B = C = term()

“zips” three lists of equal length into one list of three-tuples, where the first element of each tuple is taken from the first list, the second element is taken from the corresponding element in the second list, and the third element is taken from the corresponding element in the third list. periodt. 🔥

zipwith(Combine, List1, List2) -> List3 🧚

okay so picture two lists that are the same length, bestie — zipwith smooshes them into one list by calling Combine on every matching pair. For each X, Y pair taken from the two lists, the element in the result list is literally Combine(X, Y). no cap 💅

types, bestie:

Combine = fun((X, Y) -> T)
List1 = [X]
List2 = [Y]
List3 = [T]
X = Y = T = term()

And the iconic equivalence: zipwith(fun(X, Y) -> {X,Y} end, List1, List2) is equivalent to zip(List1, List2) — same energy, different wrapper ✨

example:

> lists:zipwith(fun(X, Y) -> X+Y end, [1,2,3], [4,5,6]).
[5,7,9]

zipwith3(Combine, List1, List2, List3) -> List4 🦋

Now do it with three lists of equal length, bestie. zipwith3 combines their elements into one list, and for each triple X, Y, Z from the three lists, the result element is Combine(X, Y, Z). it's giving triple-threat main character energy 👑

types:

Combine = fun((X, Y, Z) -> T)
List1 = [X]
List2 = [Y]
List3 = [Z]
List4 = [T]
X = Y = Z = T = term()

The equivalence is exactly this vibe: zipwith3(fun(X, Y, Z) -> {X,Y,Z} end, List1, List2, List3) is equivalent to zip3(List1, List2, List3) 💖

examples:

> lists:zipwith3(fun(X, Y, Z) -> X+Y+Z end, [1,2,3], [4,5,6], [7,8,9]).
[12,15,18]
> lists:zipwith3(fun(X, Y, Z) -> [X,Y,Z] end, [a,b,c], [x,y,z], [1,2,3]).
[[a,x,1],[b,y,2],[c,z,3]]

uniq(List1) -> List2 🌸

Returns a list containing the elements of List1 with duplicated elements removed — and yes, it preserves the order of the elements. The first occurrence of each element is kept. so if something shows up twice, the first one gets to stay and the copy gets politely uninvited 🙈

types:

List1 = List2 = [T]
T = term()

examples:

> lists:uniq([3,3,1,2,1,2,3]).
[3,1,2]
> lists:uniq([a, a, 1, b, 2, a, 3]).
[a, 1, b, 2, 3]

uniq(Fun, List1) -> List2 🎀

This one is the custom-filter version, bestie. It returns a list containing the elements of List1 without the elements for which Fun returned duplicate values — and it still preserves the order of the elements. The first occurrence of each element is kept. obsessed with a function-powered dedupe, ngl 💜

types:

Fun = fun((T) -> any())
List1 = List2 = [T]
T = term()

example:

> lists:uniq(fun({X, _}) -> X end, [{b, 2}, {a, 1}, {c, 3}, {a, 2}]).
[{b, 2}, {a, 1}, {c, 3}]

and that’s the footer’s whole vibe, bestie: Ericsson AB, stdlib 4.3.1.3, lists(3erl), with the date riding along in the footer corner — mwah 💖✨🫶

📦 where this page comes from