1lists(3) Erlang Module Definition lists(3)
2
6 lists - List processing functions.
7
9 This module contains functions for list processing.
10 Unless otherwise stated, all functions assume that position numbering
12 starts at 1. That is, the first element of a list is at position 1.
13 Two terms T1 and T2 compare equal if T1 == T2 evaluates to true. They
15 match if T1 =:= T2 evaluates to true.
16 Whenever an ordering function F is expected as argument, it is assumed
18 that the following properties hold of F for all x, y, and z:
19 * If x F y and y F x, then x = y (F is antisymmetric).
21 * If x F y and y F z, then x F z (F is transitive).
23 * x F y or y F x (F is total).
25 An example of a typical ordering function is less than or equal to:
27 =</2.
28
30 all(Pred, List) -> boolean()
31 Types:
33 Pred = fun((Elem :: T) -> boolean())
35 List = [T]
36 T = term()
37 Returns true if Pred(Elem) returns true for all elements Elem in
39 List, otherwise false.
40 any(Pred, List) -> boolean()
42 Types:
44 Pred = fun((Elem :: T) -> boolean())
46 List = [T]
47 T = term()
48 Returns true if Pred(Elem) returns true for at least one element
50 Elem in List.
51 append(ListOfLists) -> List1
53 Types:
55 ListOfLists = [List]
57 List = List1 = [T]
58 T = term()
59 Returns a list in which all the sublists of ListOfLists have
61 been appended.
62 Example:
64 > lists:append([[1, 2, 3], [a, b], [4, 5, 6]]).
66 [1,2,3,a,b,4,5,6]
67 append(List1, List2) -> List3
69 Types:
71 List1 = List2 = List3 = [T]
73 T = term()
74 Returns a new list List3, which is made from the elements of
76 List1 followed by the elements of List2.
77 Example:
79 > lists:append("abc", "def").
81 "abcdef"
82 lists:append(A, B) is equivalent to A ++ B.
84 concat(Things) -> string()
86 Types:
88 Things = [Thing]
90 Thing = atom() | integer() | float() | string()
91 Concatenates the text representation of the elements of Things.
93 The elements of Things can be atoms, integers, floats, or
94 strings.
95 Example:
97 > lists:concat([doc, '/', file, '.', 3]).
99 "doc/file.3"
100 delete(Elem, List1) -> List2
102 Types:
104 Elem = T
106 List1 = List2 = [T]
107 T = term()
108 Returns a copy of List1 where the first element matching Elem is
110 deleted, if there is such an element.
111 droplast(List) -> InitList
113 Types:
115 List = [T, ...]
117 InitList = [T]
118 T = term()
119 Drops the last element of a List. The list is to be non-empty,
121 otherwise the function crashes with a function_clause.
122 dropwhile(Pred, List1) -> List2
124 Types:
126 Pred = fun((Elem :: T) -> boolean())
128 List1 = List2 = [T]
129 T = term()
130 Drops elements Elem from List1 while Pred(Elem) returns true and
132 returns the remaining list.
133 duplicate(N, Elem) -> List
135 Types:
137 N = integer() >= 0
139 Elem = T
140 List = [T]
141 T = term()
142 Returns a list containing N copies of term Elem.
144 Example:
146 > lists:duplicate(5, xx).
148 [xx,xx,xx,xx,xx]
149 filter(Pred, List1) -> List2
151 Types:
153 Pred = fun((Elem :: T) -> boolean())
155 List1 = List2 = [T]
156 T = term()
157 List2 is a list of all elements Elem in List1 for which
159 Pred(Elem) returns true.
160 filtermap(Fun, List1) -> List2
162 Types:
164 Fun = fun((Elem) -> boolean() | {true, Value})
166 List1 = [Elem]
167 List2 = [Elem | Value]
168 Elem = Value = term()
169 Calls Fun(Elem) on successive elements Elem of List1. Fun/1 must
171 return either a Boolean or a tuple {true, Value}. The function
172 returns the list of elements for which Fun returns a new value,
173 where a value of true is synonymous with {true, Elem}.
174 That is, filtermap behaves as if it had been defined as follows:
176 filtermap(Fun, List1) ->
178 lists:foldr(fun(Elem, Acc) ->
179 case Fun(Elem) of
180 false -> Acc;
181 true -> [Elem|Acc];
182 {true,Value} -> [Value|Acc]
183 end
184 end, [], List1).
185 Example:
187 > lists:filtermap(fun(X) -> case X rem 2 of 0 -> {true, X div 2}; _ -> false end end, [1,2,3,4,5]).
189 [1,2]
190 flatlength(DeepList) -> integer() >= 0
192 Types:
194 DeepList = [term() | DeepList]
196 Equivalent to length(flatten(DeepList)), but more efficient.
198 flatmap(Fun, List1) -> List2
200 Types:
202 Fun = fun((A) -> [B])
204 List1 = [A]
205 List2 = [B]
206 A = B = term()
207 Takes a function from As to lists of Bs, and a list of As
209 (List1) and produces a list of Bs by applying the function to
210 every element in List1 and appending the resulting lists.
211 That is, flatmap behaves as if it had been defined as follows:
213 flatmap(Fun, List1) ->
215 append(map(Fun, List1)).
216 Example:
218 > lists:flatmap(fun(X)->[X,X] end, [a,b,c]).
220 [a,a,b,b,c,c]
221 flatten(DeepList) -> List
223 Types:
225 DeepList = [term() | DeepList]
227 List = [term()]
228 Returns a flattened version of DeepList.
230 flatten(DeepList, Tail) -> List
232 Types:
234 DeepList = [term() | DeepList]
236 Tail = List = [term()]
237 Returns a flattened version of DeepList with tail Tail appended.
239 foldl(Fun, Acc0, List) -> Acc1
241 Types:
243 Fun = fun((Elem :: T, AccIn) -> AccOut)
245 Acc0 = Acc1 = AccIn = AccOut = term()
246 List = [T]
247 T = term()
248 Calls Fun(Elem, AccIn) on successive elements A of List, start‐
250 ing with AccIn == Acc0. Fun/2 must return a new accumulator,
251 which is passed to the next call. The function returns the final
252 value of the accumulator. Acc0 is returned if the list is empty.
253 Example:
255 > lists:foldl(fun(X, Sum) -> X + Sum end, 0, [1,2,3,4,5]).
257 15
258 > lists:foldl(fun(X, Prod) -> X * Prod end, 1, [1,2,3,4,5]).
259 120
260 foldr(Fun, Acc0, List) -> Acc1
262 Types:
264 Fun = fun((Elem :: T, AccIn) -> AccOut)
266 Acc0 = Acc1 = AccIn = AccOut = term()
267 List = [T]
268 T = term()
269 Like foldl/3, but the list is traversed from right to left.
271 Example:
273 > P = fun(A, AccIn) -> io:format("~p ", [A]), AccIn end.
275 #Fun<erl_eval.12.2225172>
276 > lists:foldl(P, void, [1,2,3]).
277 1 2 3 void
278 > lists:foldr(P, void, [1,2,3]).
279 3 2 1 void
280 foldl/3 is tail recursive and is usually preferred to foldr/3.
282 join(Sep, List1) -> List2
284 Types:
286 Sep = T
288 List1 = List2 = [T]
289 T = term()
290 Inserts Sep between each element in List1. Has no effect on the
292 empty list and on a singleton list. For example:
293 > lists:join(x, [a,b,c]).
295 [a,x,b,x,c]
296 > lists:join(x, [a]).
297 [a]
298 > lists:join(x, []).
299 []
300 foreach(Fun, List) -> ok
302 Types:
304 Fun = fun((Elem :: T) -> term())
306 List = [T]
307 T = term()
308 Calls Fun(Elem) for each element Elem in List. This function is
310 used for its side effects and the evaluation order is defined to
311 be the same as the order of the elements in the list.
312 keydelete(Key, N, TupleList1) -> TupleList2
314 Types:
316 Key = term()
318 N = integer() >= 1
319 1..tuple_size(Tuple)
320 TupleList1 = TupleList2 = [Tuple]
321 Tuple = tuple()
322 Returns a copy of TupleList1 where the first occurrence of a
324 tuple whose Nth element compares equal to Key is deleted, if
325 there is such a tuple.
326 keyfind(Key, N, TupleList) -> Tuple | false
328 Types:
330 Key = term()
332 N = integer() >= 1
333 1..tuple_size(Tuple)
334 TupleList = [Tuple]
335 Tuple = tuple()
336 Searches the list of tuples TupleList for a tuple whose Nth ele‐
338 ment compares equal to Key. Returns Tuple if such a tuple is
339 found, otherwise false.
340 keymap(Fun, N, TupleList1) -> TupleList2
342 Types:
344 Fun = fun((Term1 :: term()) -> Term2 :: term())
346 N = integer() >= 1
347 1..tuple_size(Tuple)
348 TupleList1 = TupleList2 = [Tuple]
349 Tuple = tuple()
350 Returns a list of tuples where, for each tuple in TupleList1,
352 the Nth element Term1 of the tuple has been replaced with the
353 result of calling Fun(Term1).
354 Examples:
356 > Fun = fun(Atom) -> atom_to_list(Atom) end.
358 #Fun<erl_eval.6.10732646>
359 2> lists:keymap(Fun, 2, [{name,jane,22},{name,lizzie,20},{name,lydia,15}]).
360 [{name,"jane",22},{name,"lizzie",20},{name,"lydia",15}]
361 keymember(Key, N, TupleList) -> boolean()
363 Types:
365 Key = term()
367 N = integer() >= 1
368 1..tuple_size(Tuple)
369 TupleList = [Tuple]
370 Tuple = tuple()
371 Returns true if there is a tuple in TupleList whose Nth element
373 compares equal to Key, otherwise false.
374 keymerge(N, TupleList1, TupleList2) -> TupleList3
376 Types:
378 N = integer() >= 1
380 1..tuple_size(Tuple)
381 TupleList1 = [T1]
382 TupleList2 = [T2]
383 TupleList3 = [T1 | T2]
384 T1 = T2 = Tuple
385 Tuple = tuple()
386 Returns the sorted list formed by merging TupleList1 and
388 TupleList2. The merge is performed on the Nth element of each
389 tuple. Both TupleList1 and TupleList2 must be key-sorted before
390 evaluating this function. When two tuples compare equal, the
391 tuple from TupleList1 is picked before the tuple from
392 TupleList2.
393 keyreplace(Key, N, TupleList1, NewTuple) -> TupleList2
395 Types:
397 Key = term()
399 N = integer() >= 1
400 1..tuple_size(Tuple)
401 TupleList1 = TupleList2 = [Tuple]
402 NewTuple = Tuple
403 Tuple = tuple()
404 Returns a copy of TupleList1 where the first occurrence of a T
406 tuple whose Nth element compares equal to Key is replaced with
407 NewTuple, if there is such a tuple T.
408 keysearch(Key, N, TupleList) -> {value, Tuple} | false
410 Types:
412 Key = term()
414 N = integer() >= 1
415 1..tuple_size(Tuple)
416 TupleList = [Tuple]
417 Tuple = tuple()
418 Searches the list of tuples TupleList for a tuple whose Nth ele‐
420 ment compares equal to Key. Returns {value, Tuple} if such a
421 tuple is found, otherwise false.
422 Note:
424 This function is retained for backward compatibility. Function
425 keyfind/3 is usually more convenient.
426 keysort(N, TupleList1) -> TupleList2
429 Types:
431 N = integer() >= 1
433 1..tuple_size(Tuple)
434 TupleList1 = TupleList2 = [Tuple]
435 Tuple = tuple()
436 Returns a list containing the sorted elements of list
438 TupleList1. Sorting is performed on the Nth element of the
439 tuples. The sort is stable.
440 keystore(Key, N, TupleList1, NewTuple) -> TupleList2
442 Types:
444 Key = term()
446 N = integer() >= 1
447 1..tuple_size(Tuple)
448 TupleList1 = [Tuple]
449 TupleList2 = [Tuple, ...]
450 NewTuple = Tuple
451 Tuple = tuple()
452 Returns a copy of TupleList1 where the first occurrence of a
454 tuple T whose Nth element compares equal to Key is replaced with
455 NewTuple, if there is such a tuple T. If there is no such tuple
456 T, a copy of TupleList1 where [NewTuple] has been appended to
457 the end is returned.
458 keytake(Key, N, TupleList1) -> {value, Tuple, TupleList2} | false
460 Types:
462 Key = term()
464 N = integer() >= 1
465 1..tuple_size(Tuple)
466 TupleList1 = TupleList2 = [tuple()]
467 Tuple = tuple()
468 Searches the list of tuples TupleList1 for a tuple whose Nth
470 element compares equal to Key. Returns {value, Tuple,
471 TupleList2} if such a tuple is found, otherwise false.
472 TupleList2 is a copy of TupleList1 where the first occurrence of
473 Tuple has been removed.
474 last(List) -> Last
476 Types:
478 List = [T, ...]
480 Last = T
481 T = term()
482 Returns the last element in List.
484 map(Fun, List1) -> List2
486 Types:
488 Fun = fun((A) -> B)
490 List1 = [A]
491 List2 = [B]
492 A = B = term()
493 Takes a function from As to Bs, and a list of As and produces a
495 list of Bs by applying the function to every element in the
496 list. This function is used to obtain the return values. The
497 evaluation order depends on the implementation.
498 mapfoldl(Fun, Acc0, List1) -> {List2, Acc1}
500 Types:
502 Fun = fun((A, AccIn) -> {B, AccOut})
504 Acc0 = Acc1 = AccIn = AccOut = term()
505 List1 = [A]
506 List2 = [B]
507 A = B = term()
508 Combines the operations of map/2 and foldl/3 into one pass.
510 Example:
512 Summing the elements in a list and double them at the same time:
514 > lists:mapfoldl(fun(X, Sum) -> {2*X, X+Sum} end,
516 0, [1,2,3,4,5]).
517 {[2,4,6,8,10],15}
518 mapfoldr(Fun, Acc0, List1) -> {List2, Acc1}
520 Types:
522 Fun = fun((A, AccIn) -> {B, AccOut})
524 Acc0 = Acc1 = AccIn = AccOut = term()
525 List1 = [A]
526 List2 = [B]
527 A = B = term()
528 Combines the operations of map/2 and foldr/3 into one pass.
530 max(List) -> Max
532 Types:
534 List = [T, ...]
536 Max = T
537 T = term()
538 Returns the first element of List that compares greater than or
540 equal to all other elements of List.
541 member(Elem, List) -> boolean()
543 Types:
545 Elem = T
547 List = [T]
548 T = term()
549 Returns true if Elem matches some element of List, otherwise
551 false.
552 merge(ListOfLists) -> List1
554 Types:
556 ListOfLists = [List]
558 List = List1 = [T]
559 T = term()
560 Returns the sorted list formed by merging all the sublists of
562 ListOfLists. All sublists must be sorted before evaluating this
563 function. When two elements compare equal, the element from the
564 sublist with the lowest position in ListOfLists is picked before
565 the other element.
566 merge(List1, List2) -> List3
568 Types:
570 List1 = [X]
572 List2 = [Y]
573 List3 = [X | Y]
574 X = Y = term()
575 Returns the sorted list formed by merging List1 and List2. Both
577 List1 and List2 must be sorted before evaluating this function.
578 When two elements compare equal, the element from List1 is
579 picked before the element from List2.
580 merge(Fun, List1, List2) -> List3
582 Types:
584 Fun = fun((A, B) -> boolean())
586 List1 = [A]
587 List2 = [B]
588 List3 = [A | B]
589 A = B = term()
590 Returns the sorted list formed by merging List1 and List2. Both
592 List1 and List2 must be sorted according to the ordering func‐
593 tion Fun before evaluating this function. Fun(A, B) is to return
594 true if A compares less than or equal to B in the ordering, oth‐
595 erwise false. When two elements compare equal, the element from
596 List1 is picked before the element from List2.
597 merge3(List1, List2, List3) -> List4
599 Types:
601 List1 = [X]
603 List2 = [Y]
604 List3 = [Z]
605 List4 = [X | Y | Z]
606 X = Y = Z = term()
607 Returns the sorted list formed by merging List1, List2, and
609 List3. All of List1, List2, and List3 must be sorted before
610 evaluating this function. When two elements compare equal, the
611 element from List1, if there is such an element, is picked
612 before the other element, otherwise the element from List2 is
613 picked before the element from List3.
614 min(List) -> Min
616 Types:
618 List = [T, ...]
620 Min = T
621 T = term()
622 Returns the first element of List that compares less than or
624 equal to all other elements of List.
625 nth(N, List) -> Elem
627 Types:
629 N = integer() >= 1
631 1..length(List)
632 List = [T, ...]
633 Elem = T
634 T = term()
635 Returns the Nth element of List.
637 Example:
639 > lists:nth(3, [a, b, c, d, e]).
641 c
642 nthtail(N, List) -> Tail
644 Types:
646 N = integer() >= 0
648 0..length(List)
649 List = [T, ...]
650 Tail = [T]
651 T = term()
652 Returns the Nth tail of List, that is, the sublist of List
654 starting at N+1 and continuing up to the end of the list.
655 Example
657 > lists:nthtail(3, [a, b, c, d, e]).
659 [d,e]
660 > tl(tl(tl([a, b, c, d, e]))).
661 [d,e]
662 > lists:nthtail(0, [a, b, c, d, e]).
663 [a,b,c,d,e]
664 > lists:nthtail(5, [a, b, c, d, e]).
665 []
666 partition(Pred, List) -> {Satisfying, NotSatisfying}
668 Types:
670 Pred = fun((Elem :: T) -> boolean())
672 List = Satisfying = NotSatisfying = [T]
673 T = term()
674 Partitions List into two lists, where the first list contains
676 all elements for which Pred(Elem) returns true, and the second
677 list contains all elements for which Pred(Elem) returns false.
678 Examples:
680 > lists:partition(fun(A) -> A rem 2 == 1 end, [1,2,3,4,5,6,7]).
682 {[1,3,5,7],[2,4,6]}
683 > lists:partition(fun(A) -> is_atom(A) end, [a,b,1,c,d,2,3,4,e]).
684 {[a,b,c,d,e],[1,2,3,4]}
685 For a different way to partition a list, see splitwith/2.
687 prefix(List1, List2) -> boolean()
689 Types:
691 List1 = List2 = [T]
693 T = term()
694 Returns true if List1 is a prefix of List2, otherwise false.
696 reverse(List1) -> List2
698 Types:
700 List1 = List2 = [T]
702 T = term()
703 Returns a list with the elements in List1 in reverse order.
705 reverse(List1, Tail) -> List2
707 Types:
709 List1 = [T]
711 Tail = term()
712 List2 = [T]
713 T = term()
714 Returns a list with the elements in List1 in reverse order, with
716 tail Tail appended.
717 Example:
719 > lists:reverse([1, 2, 3, 4], [a, b, c]).
721 [4,3,2,1,a,b,c]
722 search(Pred, List) -> {value, Value} | false
724 Types:
726 Pred = fun((T) -> boolean())
728 List = [T]
729 Value = T
730 If there is a Value in List such that Pred(Value) returns true,
732 returns {value, Value} for the first such Value, otherwise
733 returns false.
734 seq(From, To) -> Seq
736 seq(From, To, Incr) -> Seq
738 Types:
740 From = To = Incr = integer()
742 Seq = [integer()]
743 Returns a sequence of integers that starts with From and con‐
745 tains the successive results of adding Incr to the previous ele‐
746 ment, until To is reached or passed (in the latter case, To is
747 not an element of the sequence). Incr defaults to 1.
748 Failures:
750 * If To < From - Incr and Incr > 0.
752 * If To > From - Incr and Incr < 0.
754 * If Incr =:= 0 and From =/= To.
756 The following equalities hold for all sequences:
758 length(lists:seq(From, To)) =:= To - From + 1
760 length(lists:seq(From, To, Incr)) =:= (To - From + Incr) div Incr
761 Examples:
763 > lists:seq(1, 10).
765 [1,2,3,4,5,6,7,8,9,10]
766 > lists:seq(1, 20, 3).
767 [1,4,7,10,13,16,19]
768 > lists:seq(1, 0, 1).
769 []
770 > lists:seq(10, 6, 4).
771 []
772 > lists:seq(1, 1, 0).
773 [1]
774 sort(List1) -> List2
776 Types:
778 List1 = List2 = [T]
780 T = term()
781 Returns a list containing the sorted elements of List1.
783 sort(Fun, List1) -> List2
785 Types:
787 Fun = fun((A :: T, B :: T) -> boolean())
789 List1 = List2 = [T]
790 T = term()
791 Returns a list containing the sorted elements of List1, accord‐
793 ing to the ordering function Fun. Fun(A, B) is to return true if
794 A compares less than or equal to B in the ordering, otherwise
795 false.
796 split(N, List1) -> {List2, List3}
798 Types:
800 N = integer() >= 0
802 0..length(List1)
803 List1 = List2 = List3 = [T]
804 T = term()
805 Splits List1 into List2 and List3. List2 contains the first N
807 elements and List3 the remaining elements (the Nth tail).
808 splitwith(Pred, List) -> {List1, List2}
810 Types:
812 Pred = fun((T) -> boolean())
814 List = List1 = List2 = [T]
815 T = term()
816 Partitions List into two lists according to Pred. splitwith/2
818 behaves as if it is defined as follows:
819 splitwith(Pred, List) ->
821 {takewhile(Pred, List), dropwhile(Pred, List)}.
822 Examples:
824 > lists:splitwith(fun(A) -> A rem 2 == 1 end, [1,2,3,4,5,6,7]).
826 {[1],[2,3,4,5,6,7]}
827 > lists:splitwith(fun(A) -> is_atom(A) end, [a,b,1,c,d,2,3,4,e]).
828 {[a,b],[1,c,d,2,3,4,e]}
829 For a different way to partition a list, see partition/2.
831 sublist(List1, Len) -> List2
833 Types:
835 List1 = List2 = [T]
837 Len = integer() >= 0
838 T = term()
839 Returns the sublist of List1 starting at position 1 and with
841 (maximum) Len elements. It is not an error for Len to exceed the
842 length of the list, in that case the whole list is returned.
843 sublist(List1, Start, Len) -> List2
845 Types:
847 List1 = List2 = [T]
849 Start = integer() >= 1
850 1..(length(List1)+1)
851 Len = integer() >= 0
852 T = term()
853 Returns the sublist of List1 starting at Start and with (maxi‐
855 mum) Len elements. It is not an error for Start+Len to exceed
856 the length of the list.
857 Examples:
859 > lists:sublist([1,2,3,4], 2, 2).
861 [2,3]
862 > lists:sublist([1,2,3,4], 2, 5).
863 [2,3,4]
864 > lists:sublist([1,2,3,4], 5, 2).
865 []
866 subtract(List1, List2) -> List3
868 Types:
870 List1 = List2 = List3 = [T]
872 T = term()
873 Returns a new list List3 that is a copy of List1, subjected to
875 the following procedure: for each element in List2, its first
876 occurrence in List1 is deleted.
877 Example:
879 > lists:subtract("123212", "212").
881 "312".
882 lists:subtract(A, B) is equivalent to A -- B.
884 suffix(List1, List2) -> boolean()
886 Types:
888 List1 = List2 = [T]
890 T = term()
891 Returns true if List1 is a suffix of List2, otherwise false.
893 sum(List) -> number()
895 Types:
897 List = [number()]
899 Returns the sum of the elements in List.
901 takewhile(Pred, List1) -> List2
903 Types:
905 Pred = fun((Elem :: T) -> boolean())
907 List1 = List2 = [T]
908 T = term()
909 Takes elements Elem from List1 while Pred(Elem) returns true,
911 that is, the function returns the longest prefix of the list for
912 which all elements satisfy the predicate.
913 ukeymerge(N, TupleList1, TupleList2) -> TupleList3
915 Types:
917 N = integer() >= 1
919 1..tuple_size(Tuple)
920 TupleList1 = [T1]
921 TupleList2 = [T2]
922 TupleList3 = [T1 | T2]
923 T1 = T2 = Tuple
924 Tuple = tuple()
925 Returns the sorted list formed by merging TupleList1 and
927 TupleList2. The merge is performed on the Nth element of each
928 tuple. Both TupleList1 and TupleList2 must be key-sorted without
929 duplicates before evaluating this function. When two tuples com‐
930 pare equal, the tuple from TupleList1 is picked and the one from
931 TupleList2 is deleted.
932 ukeysort(N, TupleList1) -> TupleList2
934 Types:
936 N = integer() >= 1
938 1..tuple_size(Tuple)
939 TupleList1 = TupleList2 = [Tuple]
940 Tuple = tuple()
941 Returns a list containing the sorted elements of list TupleList1
943 where all except the first tuple of the tuples comparing equal
944 have been deleted. Sorting is performed on the Nth element of
945 the tuples.
946 umerge(ListOfLists) -> List1
948 Types:
950 ListOfLists = [List]
952 List = List1 = [T]
953 T = term()
954 Returns the sorted list formed by merging all the sublists of
956 ListOfLists. All sublists must be sorted and contain no dupli‐
957 cates before evaluating this function. When two elements compare
958 equal, the element from the sublist with the lowest position in
959 ListOfLists is picked and the other is deleted.
960 umerge(List1, List2) -> List3
962 Types:
964 List1 = [X]
966 List2 = [Y]
967 List3 = [X | Y]
968 X = Y = term()
969 Returns the sorted list formed by merging List1 and List2. Both
971 List1 and List2 must be sorted and contain no duplicates before
972 evaluating this function. When two elements compare equal, the
973 element from List1 is picked and the one from List2 is deleted.
974 umerge(Fun, List1, List2) -> List3
976 Types:
978 Fun = fun((A, B) -> boolean())
980 List1 = [A]
981 List2 = [B]
982 List3 = [A | B]
983 A = B = term()
984 Returns the sorted list formed by merging List1 and List2. Both
986 List1 and List2 must be sorted according to the ordering func‐
987 tion Fun and contain no duplicates before evaluating this func‐
988 tion. Fun(A, B) is to return true if A compares less than or
989 equal to B in the ordering, otherwise false. When two elements
990 compare equal, the element from List1 is picked and the one from
991 List2 is deleted.
992 umerge3(List1, List2, List3) -> List4
994 Types:
996 List1 = [X]
998 List2 = [Y]
999 List3 = [Z]
1000 List4 = [X | Y | Z]
1001 X = Y = Z = term()
1002 Returns the sorted list formed by merging List1, List2, and
1004 List3. All of List1, List2, and List3 must be sorted and contain
1005 no duplicates before evaluating this function. When two elements
1006 compare equal, the element from List1 is picked if there is such
1007 an element, otherwise the element from List2 is picked, and the
1008 other is deleted.
1009 unzip(List1) -> {List2, List3}
1011 Types:
1013 List1 = [{A, B}]
1015 List2 = [A]
1016 List3 = [B]
1017 A = B = term()
1018 "Unzips" a list of two-tuples into two lists, where the first
1020 list contains the first element of each tuple, and the second
1021 list contains the second element of each tuple.
1022 unzip3(List1) -> {List2, List3, List4}
1024 Types:
1026 List1 = [{A, B, C}]
1028 List2 = [A]
1029 List3 = [B]
1030 List4 = [C]
1031 A = B = C = term()
1032 "Unzips" a list of three-tuples into three lists, where the
1034 first list contains the first element of each tuple, the second
1035 list contains the second element of each tuple, and the third
1036 list contains the third element of each tuple.
1037 usort(List1) -> List2
1039 Types:
1041 List1 = List2 = [T]
1043 T = term()
1044 Returns a list containing the sorted elements of List1 where all
1046 except the first element of the elements comparing equal have
1047 been deleted.
1048 usort(Fun, List1) -> List2
1050 Types:
1052 Fun = fun((T, T) -> boolean())
1054 List1 = List2 = [T]
1055 T = term()
1056 Returns a list containing the sorted elements of List1 where all
1058 except the first element of the elements comparing equal accord‐
1059 ing to the ordering function Fun have been deleted. Fun(A, B) is
1060 to return true if A compares less than or equal to B in the
1061 ordering, otherwise false.
1062 zip(List1, List2) -> List3
1064 Types:
1066 List1 = [A]
1068 List2 = [B]
1069 List3 = [{A, B}]
1070 A = B = term()
1071 "Zips" two lists of equal length into one list of two-tuples,
1073 where the first element of each tuple is taken from the first
1074 list and the second element is taken from the corresponding ele‐
1075 ment in the second list.
1076 zip3(List1, List2, List3) -> List4
1078 Types:
1080 List1 = [A]
1082 List2 = [B]
1083 List3 = [C]
1084 List4 = [{A, B, C}]
1085 A = B = C = term()
1086 "Zips" three lists of equal length into one list of three-
1088 tuples, where the first element of each tuple is taken from the
1089 first list, the second element is taken from the corresponding
1090 element in the second list, and the third element is taken from
1091 the corresponding element in the third list.
1092 zipwith(Combine, List1, List2) -> List3
1094 Types:
1096 Combine = fun((X, Y) -> T)
1098 List1 = [X]
1099 List2 = [Y]
1100 List3 = [T]
1101 X = Y = T = term()
1102 Combines the elements of two lists of equal length into one
1104 list. For each pair X, Y of list elements from the two lists,
1105 the element in the result list is Combine(X, Y).
1106 zipwith(fun(X, Y) -> {X,Y} end, List1, List2) is equivalent to
1108 zip(List1, List2).
1109 Example:
1111 > lists:zipwith(fun(X, Y) -> X+Y end, [1,2,3], [4,5,6]).
1113 [5,7,9]
1114 zipwith3(Combine, List1, List2, List3) -> List4
1116 Types:
1118 Combine = fun((X, Y, Z) -> T)
1120 List1 = [X]
1121 List2 = [Y]
1122 List3 = [Z]
1123 List4 = [T]
1124 X = Y = Z = T = term()
1125 Combines the elements of three lists of equal length into one
1127 list. For each triple X, Y, Z of list elements from the three
1128 lists, the element in the result list is Combine(X, Y, Z).
1129 zipwith3(fun(X, Y, Z) -> {X,Y,Z} end, List1, List2, List3) is
1131 equivalent to zip3(List1, List2, List3).
1132 Examples:
1134 > lists:zipwith3(fun(X, Y, Z) -> X+Y+Z end, [1,2,3], [4,5,6], [7,8,9]).
1136 [12,15,18]
1137 > lists:zipwith3(fun(X, Y, Z) -> [X,Y,Z] end, [a,b,c], [x,y,z], [1,2,3]).
1138 [[a,x,1],[b,y,2],[c,z,3]]
1139Ericsson AB stdlib 3.12.1 lists(3)