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 tu‐
324 ple whose Nth element compares equal to Key is deleted, if there
325 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 Tu‐
388 pleList2. The merge is performed on the Nth element of each tu‐
389 ple. Both TupleList1 and TupleList2 must be key-sorted before
390 evaluating this function. When two tuples compare equal, the tu‐
391 ple from TupleList1 is picked before the tuple from TupleList2.
392 keyreplace(Key, N, TupleList1, NewTuple) -> TupleList2
394 Types:
396 Key = term()
398 N = integer() >= 1
399 1..tuple_size(Tuple)
400 TupleList1 = TupleList2 = [Tuple]
401 NewTuple = Tuple
402 Tuple = tuple()
403 Returns a copy of TupleList1 where the first occurrence of a T
405 tuple whose Nth element compares equal to Key is replaced with
406 NewTuple, if there is such a tuple T.
407 keysearch(Key, N, TupleList) -> {value, Tuple} | false
409 Types:
411 Key = term()
413 N = integer() >= 1
414 1..tuple_size(Tuple)
415 TupleList = [Tuple]
416 Tuple = tuple()
417 Searches the list of tuples TupleList for a tuple whose Nth ele‐
419 ment compares equal to Key. Returns {value, Tuple} if such a tu‐
420 ple is found, otherwise false.
421 Note:
423 This function is retained for backward compatibility. Function
424 keyfind/3 is usually more convenient.
425 keysort(N, TupleList1) -> TupleList2
428 Types:
430 N = integer() >= 1
432 1..tuple_size(Tuple)
433 TupleList1 = TupleList2 = [Tuple]
434 Tuple = tuple()
435 Returns a list containing the sorted elements of list Tu‐
437 pleList1. Sorting is performed on the Nth element of the tuples.
438 The sort is stable.
439 keystore(Key, N, TupleList1, NewTuple) -> TupleList2
441 Types:
443 Key = term()
445 N = integer() >= 1
446 1..tuple_size(Tuple)
447 TupleList1 = [Tuple]
448 TupleList2 = [Tuple, ...]
449 NewTuple = Tuple
450 Tuple = tuple()
451 Returns a copy of TupleList1 where the first occurrence of a tu‐
453 ple T whose Nth element compares equal to Key is replaced with
454 NewTuple, if there is such a tuple T. If there is no such tuple
455 T, a copy of TupleList1 where [NewTuple] has been appended to
456 the end is returned.
457 keytake(Key, N, TupleList1) -> {value, Tuple, TupleList2} | false
459 Types:
461 Key = term()
463 N = integer() >= 1
464 1..tuple_size(Tuple)
465 TupleList1 = TupleList2 = [tuple()]
466 Tuple = tuple()
467 Searches the list of tuples TupleList1 for a tuple whose Nth el‐
469 ement compares equal to Key. Returns {value, Tuple, TupleList2}
470 if such a tuple is found, otherwise false. TupleList2 is a copy
471 of TupleList1 where the first occurrence of Tuple has been re‐
472 moved.
473 last(List) -> Last
475 Types:
477 List = [T, ...]
479 Last = T
480 T = term()
481 Returns the last element in List.
483 map(Fun, List1) -> List2
485 Types:
487 Fun = fun((A) -> B)
489 List1 = [A]
490 List2 = [B]
491 A = B = term()
492 Takes a function from As to Bs, and a list of As and produces a
494 list of Bs by applying the function to every element in the
495 list. This function is used to obtain the return values. The
496 evaluation order depends on the implementation.
497 mapfoldl(Fun, Acc0, List1) -> {List2, Acc1}
499 Types:
501 Fun = fun((A, AccIn) -> {B, AccOut})
503 Acc0 = Acc1 = AccIn = AccOut = term()
504 List1 = [A]
505 List2 = [B]
506 A = B = term()
507 Combines the operations of map/2 and foldl/3 into one pass.
509 Example:
511 Summing the elements in a list and double them at the same time:
513 > lists:mapfoldl(fun(X, Sum) -> {2*X, X+Sum} end,
515 0, [1,2,3,4,5]).
516 {[2,4,6,8,10],15}
517 mapfoldr(Fun, Acc0, List1) -> {List2, Acc1}
519 Types:
521 Fun = fun((A, AccIn) -> {B, AccOut})
523 Acc0 = Acc1 = AccIn = AccOut = term()
524 List1 = [A]
525 List2 = [B]
526 A = B = term()
527 Combines the operations of map/2 and foldr/3 into one pass.
529 max(List) -> Max
531 Types:
533 List = [T, ...]
535 Max = T
536 T = term()
537 Returns the first element of List that compares greater than or
539 equal to all other elements of List.
540 member(Elem, List) -> boolean()
542 Types:
544 Elem = T
546 List = [T]
547 T = term()
548 Returns true if Elem matches some element of List, otherwise
550 false.
551 merge(ListOfLists) -> List1
553 Types:
555 ListOfLists = [List]
557 List = List1 = [T]
558 T = term()
559 Returns the sorted list formed by merging all the sublists of
561 ListOfLists. All sublists must be sorted before evaluating this
562 function. When two elements compare equal, the element from the
563 sublist with the lowest position in ListOfLists is picked before
564 the other element.
565 merge(List1, List2) -> List3
567 Types:
569 List1 = [X]
571 List2 = [Y]
572 List3 = [X | Y]
573 X = Y = term()
574 Returns the sorted list formed by merging List1 and List2. Both
576 List1 and List2 must be sorted before evaluating this function.
577 When two elements compare equal, the element from List1 is
578 picked before the element from List2.
579 merge(Fun, List1, List2) -> List3
581 Types:
583 Fun = fun((A, B) -> boolean())
585 List1 = [A]
586 List2 = [B]
587 List3 = [A | B]
588 A = B = term()
589 Returns the sorted list formed by merging List1 and List2. Both
591 List1 and List2 must be sorted according to the ordering func‐
592 tion Fun before evaluating this function. Fun(A, B) is to return
593 true if A compares less than or equal to B in the ordering, oth‐
594 erwise false. When two elements compare equal, the element from
595 List1 is picked before the element from List2.
596 merge3(List1, List2, List3) -> List4
598 Types:
600 List1 = [X]
602 List2 = [Y]
603 List3 = [Z]
604 List4 = [X | Y | Z]
605 X = Y = Z = term()
606 Returns the sorted list formed by merging List1, List2, and
608 List3. All of List1, List2, and List3 must be sorted before
609 evaluating this function. When two elements compare equal, the
610 element from List1, if there is such an element, is picked be‐
611 fore the other element, otherwise the element from List2 is
612 picked before the element from List3.
613 min(List) -> Min
615 Types:
617 List = [T, ...]
619 Min = T
620 T = term()
621 Returns the first element of List that compares less than or
623 equal to all other elements of List.
624 nth(N, List) -> Elem
626 Types:
628 N = integer() >= 1
630 1..length(List)
631 List = [T, ...]
632 Elem = T
633 T = term()
634 Returns the Nth element of List.
636 Example:
638 > lists:nth(3, [a, b, c, d, e]).
640 c
641 nthtail(N, List) -> Tail
643 Types:
645 N = integer() >= 0
647 0..length(List)
648 List = [T, ...]
649 Tail = [T]
650 T = term()
651 Returns the Nth tail of List, that is, the sublist of List
653 starting at N+1 and continuing up to the end of the list.
654 Example
656 > lists:nthtail(3, [a, b, c, d, e]).
658 [d,e]
659 > tl(tl(tl([a, b, c, d, e]))).
660 [d,e]
661 > lists:nthtail(0, [a, b, c, d, e]).
662 [a,b,c,d,e]
663 > lists:nthtail(5, [a, b, c, d, e]).
664 []
665 partition(Pred, List) -> {Satisfying, NotSatisfying}
667 Types:
669 Pred = fun((Elem :: T) -> boolean())
671 List = Satisfying = NotSatisfying = [T]
672 T = term()
673 Partitions List into two lists, where the first list contains
675 all elements for which Pred(Elem) returns true, and the second
676 list contains all elements for which Pred(Elem) returns false.
677 Examples:
679 > lists:partition(fun(A) -> A rem 2 == 1 end, [1,2,3,4,5,6,7]).
681 {[1,3,5,7],[2,4,6]}
682 > lists:partition(fun(A) -> is_atom(A) end, [a,b,1,c,d,2,3,4,e]).
683 {[a,b,c,d,e],[1,2,3,4]}
684 For a different way to partition a list, see splitwith/2.
686 prefix(List1, List2) -> boolean()
688 Types:
690 List1 = List2 = [T]
692 T = term()
693 Returns true if List1 is a prefix of List2, otherwise false.
695 reverse(List1) -> List2
697 Types:
699 List1 = List2 = [T]
701 T = term()
702 Returns a list with the elements in List1 in reverse order.
704 reverse(List1, Tail) -> List2
706 Types:
708 List1 = [T]
710 Tail = term()
711 List2 = [T]
712 T = term()
713 Returns a list with the elements in List1 in reverse order, with
715 tail Tail appended.
716 Example:
718 > lists:reverse([1, 2, 3, 4], [a, b, c]).
720 [4,3,2,1,a,b,c]
721 search(Pred, List) -> {value, Value} | false
723 Types:
725 Pred = fun((T) -> boolean())
727 List = [T]
728 Value = T
729 If there is a Value in List such that Pred(Value) returns true,
731 returns {value, Value} for the first such Value, otherwise re‐
732 turns false.
733 seq(From, To) -> Seq
735 seq(From, To, Incr) -> Seq
737 Types:
739 From = To = Incr = integer()
741 Seq = [integer()]
742 Returns a sequence of integers that starts with From and con‐
744 tains the successive results of adding Incr to the previous ele‐
745 ment, until To is reached or passed (in the latter case, To is
746 not an element of the sequence). Incr defaults to 1.
747 Failures:
749 * If To < From - Incr and Incr > 0.
751 * If To > From - Incr and Incr < 0.
753 * If Incr =:= 0 and From =/= To.
755 The following equalities hold for all sequences:
757 length(lists:seq(From, To)) =:= To - From + 1
759 length(lists:seq(From, To, Incr)) =:= (To - From + Incr) div Incr
760 Examples:
762 > lists:seq(1, 10).
764 [1,2,3,4,5,6,7,8,9,10]
765 > lists:seq(1, 20, 3).
766 [1,4,7,10,13,16,19]
767 > lists:seq(1, 0, 1).
768 []
769 > lists:seq(10, 6, 4).
770 []
771 > lists:seq(1, 1, 0).
772 [1]
773 sort(List1) -> List2
775 Types:
777 List1 = List2 = [T]
779 T = term()
780 Returns a list containing the sorted elements of List1.
782 sort(Fun, List1) -> List2
784 Types:
786 Fun = fun((A :: T, B :: T) -> boolean())
788 List1 = List2 = [T]
789 T = term()
790 Returns a list containing the sorted elements of List1, accord‐
792 ing to the ordering function Fun. Fun(A, B) is to return true if
793 A compares less than or equal to B in the ordering, otherwise
794 false.
795 split(N, List1) -> {List2, List3}
797 Types:
799 N = integer() >= 0
801 0..length(List1)
802 List1 = List2 = List3 = [T]
803 T = term()
804 Splits List1 into List2 and List3. List2 contains the first N
806 elements and List3 the remaining elements (the Nth tail).
807 splitwith(Pred, List) -> {List1, List2}
809 Types:
811 Pred = fun((T) -> boolean())
813 List = List1 = List2 = [T]
814 T = term()
815 Partitions List into two lists according to Pred. splitwith/2
817 behaves as if it is defined as follows:
818 splitwith(Pred, List) ->
820 {takewhile(Pred, List), dropwhile(Pred, List)}.
821 Examples:
823 > lists:splitwith(fun(A) -> A rem 2 == 1 end, [1,2,3,4,5,6,7]).
825 {[1],[2,3,4,5,6,7]}
826 > lists:splitwith(fun(A) -> is_atom(A) end, [a,b,1,c,d,2,3,4,e]).
827 {[a,b],[1,c,d,2,3,4,e]}
828 For a different way to partition a list, see partition/2.
830 sublist(List1, Len) -> List2
832 Types:
834 List1 = List2 = [T]
836 Len = integer() >= 0
837 T = term()
838 Returns the sublist of List1 starting at position 1 and with
840 (maximum) Len elements. It is not an error for Len to exceed the
841 length of the list, in that case the whole list is returned.
842 sublist(List1, Start, Len) -> List2
844 Types:
846 List1 = List2 = [T]
848 Start = integer() >= 1
849 1..(length(List1)+1)
850 Len = integer() >= 0
851 T = term()
852 Returns the sublist of List1 starting at Start and with (maxi‐
854 mum) Len elements. It is not an error for Start+Len to exceed
855 the length of the list.
856 Examples:
858 > lists:sublist([1,2,3,4], 2, 2).
860 [2,3]
861 > lists:sublist([1,2,3,4], 2, 5).
862 [2,3,4]
863 > lists:sublist([1,2,3,4], 5, 2).
864 []
865 subtract(List1, List2) -> List3
867 Types:
869 List1 = List2 = List3 = [T]
871 T = term()
872 Returns a new list List3 that is a copy of List1, subjected to
874 the following procedure: for each element in List2, its first
875 occurrence in List1 is deleted.
876 Example:
878 > lists:subtract("123212", "212").
880 "312".
881 lists:subtract(A, B) is equivalent to A -- B.
883 suffix(List1, List2) -> boolean()
885 Types:
887 List1 = List2 = [T]
889 T = term()
890 Returns true if List1 is a suffix of List2, otherwise false.
892 sum(List) -> number()
894 Types:
896 List = [number()]
898 Returns the sum of the elements in List.
900 takewhile(Pred, List1) -> List2
902 Types:
904 Pred = fun((Elem :: T) -> boolean())
906 List1 = List2 = [T]
907 T = term()
908 Takes elements Elem from List1 while Pred(Elem) returns true,
910 that is, the function returns the longest prefix of the list for
911 which all elements satisfy the predicate.
912 ukeymerge(N, TupleList1, TupleList2) -> TupleList3
914 Types:
916 N = integer() >= 1
918 1..tuple_size(Tuple)
919 TupleList1 = [T1]
920 TupleList2 = [T2]
921 TupleList3 = [T1 | T2]
922 T1 = T2 = Tuple
923 Tuple = tuple()
924 Returns the sorted list formed by merging TupleList1 and Tu‐
926 pleList2. The merge is performed on the Nth element of each tu‐
927 ple. Both TupleList1 and TupleList2 must be key-sorted without
928 duplicates before evaluating this function. When two tuples com‐
929 pare equal, the tuple from TupleList1 is picked and the one from
930 TupleList2 is deleted.
931 ukeysort(N, TupleList1) -> TupleList2
933 Types:
935 N = integer() >= 1
937 1..tuple_size(Tuple)
938 TupleList1 = TupleList2 = [Tuple]
939 Tuple = tuple()
940 Returns a list containing the sorted elements of list TupleList1
942 where all except the first tuple of the tuples comparing equal
943 have been deleted. Sorting is performed on the Nth element of
944 the tuples.
945 umerge(ListOfLists) -> List1
947 Types:
949 ListOfLists = [List]
951 List = List1 = [T]
952 T = term()
953 Returns the sorted list formed by merging all the sublists of
955 ListOfLists. All sublists must be sorted and contain no dupli‐
956 cates before evaluating this function. When two elements compare
957 equal, the element from the sublist with the lowest position in
958 ListOfLists is picked and the other is deleted.
959 umerge(List1, List2) -> List3
961 Types:
963 List1 = [X]
965 List2 = [Y]
966 List3 = [X | Y]
967 X = Y = term()
968 Returns the sorted list formed by merging List1 and List2. Both
970 List1 and List2 must be sorted and contain no duplicates before
971 evaluating this function. When two elements compare equal, the
972 element from List1 is picked and the one from List2 is deleted.
973 umerge(Fun, List1, List2) -> List3
975 Types:
977 Fun = fun((A, B) -> boolean())
979 List1 = [A]
980 List2 = [B]
981 List3 = [A | B]
982 A = B = term()
983 Returns the sorted list formed by merging List1 and List2. Both
985 List1 and List2 must be sorted according to the ordering func‐
986 tion Fun and contain no duplicates before evaluating this func‐
987 tion. Fun(A, B) is to return true if A compares less than or
988 equal to B in the ordering, otherwise false. When two elements
989 compare equal, the element from List1 is picked and the one from
990 List2 is deleted.
991 umerge3(List1, List2, List3) -> List4
993 Types:
995 List1 = [X]
997 List2 = [Y]
998 List3 = [Z]
999 List4 = [X | Y | Z]
1000 X = Y = Z = term()
1001 Returns the sorted list formed by merging List1, List2, and
1003 List3. All of List1, List2, and List3 must be sorted and contain
1004 no duplicates before evaluating this function. When two elements
1005 compare equal, the element from List1 is picked if there is such
1006 an element, otherwise the element from List2 is picked, and the
1007 other is deleted.
1008 unzip(List1) -> {List2, List3}
1010 Types:
1012 List1 = [{A, B}]
1014 List2 = [A]
1015 List3 = [B]
1016 A = B = term()
1017 "Unzips" a list of two-tuples into two lists, where the first
1019 list contains the first element of each tuple, and the second
1020 list contains the second element of each tuple.
1021 unzip3(List1) -> {List2, List3, List4}
1023 Types:
1025 List1 = [{A, B, C}]
1027 List2 = [A]
1028 List3 = [B]
1029 List4 = [C]
1030 A = B = C = term()
1031 "Unzips" a list of three-tuples into three lists, where the
1033 first list contains the first element of each tuple, the second
1034 list contains the second element of each tuple, and the third
1035 list contains the third element of each tuple.
1036 usort(List1) -> List2
1038 Types:
1040 List1 = List2 = [T]
1042 T = term()
1043 Returns a list containing the sorted elements of List1 where all
1045 except the first element of the elements comparing equal have
1046 been deleted.
1047 usort(Fun, List1) -> List2
1049 Types:
1051 Fun = fun((T, T) -> boolean())
1053 List1 = List2 = [T]
1054 T = term()
1055 Returns a list containing the sorted elements of List1 where all
1057 except the first element of the elements comparing equal accord‐
1058 ing to the ordering function Fun have been deleted. Fun(A, B) is
1059 to return true if A compares less than or equal to B in the or‐
1060 dering, otherwise false.
1061 zip(List1, List2) -> List3
1063 Types:
1065 List1 = [A]
1067 List2 = [B]
1068 List3 = [{A, B}]
1069 A = B = term()
1070 "Zips" two lists of equal length into one list of two-tuples,
1072 where the first element of each tuple is taken from the first
1073 list and the second element is taken from the corresponding ele‐
1074 ment in the second list.
1075 zip3(List1, List2, List3) -> List4
1077 Types:
1079 List1 = [A]
1081 List2 = [B]
1082 List3 = [C]
1083 List4 = [{A, B, C}]
1084 A = B = C = term()
1085 "Zips" three lists of equal length into one list of three-tu‐
1087 ples, where the first element of each tuple is taken from the
1088 first list, the second element is taken from the corresponding
1089 element in the second list, and the third element is taken from
1090 the corresponding element in the third list.
1091 zipwith(Combine, List1, List2) -> List3
1093 Types:
1095 Combine = fun((X, Y) -> T)
1097 List1 = [X]
1098 List2 = [Y]
1099 List3 = [T]
1100 X = Y = T = term()
1101 Combines the elements of two lists of equal length into one
1103 list. For each pair X, Y of list elements from the two lists,
1104 the element in the result list is Combine(X, Y).
1105 zipwith(fun(X, Y) -> {X,Y} end, List1, List2) is equivalent to
1107 zip(List1, List2).
1108 Example:
1110 > lists:zipwith(fun(X, Y) -> X+Y end, [1,2,3], [4,5,6]).
1112 [5,7,9]
1113 zipwith3(Combine, List1, List2, List3) -> List4
1115 Types:
1117 Combine = fun((X, Y, Z) -> T)
1119 List1 = [X]
1120 List2 = [Y]
1121 List3 = [Z]
1122 List4 = [T]
1123 X = Y = Z = T = term()
1124 Combines the elements of three lists of equal length into one
1126 list. For each triple X, Y, Z of list elements from the three
1127 lists, the element in the result list is Combine(X, Y, Z).
1128 zipwith3(fun(X, Y, Z) -> {X,Y,Z} end, List1, List2, List3) is
1130 equivalent to zip3(List1, List2, List3).
1131 Examples:
1133 > lists:zipwith3(fun(X, Y, Z) -> X+Y+Z end, [1,2,3], [4,5,6], [7,8,9]).
1135 [12,15,18]
1136 > lists:zipwith3(fun(X, Y, Z) -> [X,Y,Z] end, [a,b,c], [x,y,z], [1,2,3]).
1137 [[a,x,1],[b,y,2],[c,z,3]]
1138Ericsson AB stdlib 3.14.2.1 lists(3)