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. The Pred function must return a boolean.
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. The Pred function must return a boolean.
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. The Pred function must return a
133 boolean.
134 duplicate(N, Elem) -> List
136 Types:
138 N = integer() >= 0
140 Elem = T
141 List = [T]
142 T = term()
143 Returns a list containing N copies of term Elem.
145 Example:
147 > lists:duplicate(5, xx).
149 [xx,xx,xx,xx,xx]
150 filter(Pred, List1) -> List2
152 Types:
154 Pred = fun((Elem :: T) -> boolean())
156 List1 = List2 = [T]
157 T = term()
158 List2 is a list of all elements Elem in List1 for which
160 Pred(Elem) returns true. The Pred function must return a bool‐
161 ean.
162 filtermap(Fun, List1) -> List2
164 Types:
166 Fun = fun((Elem) -> boolean() | {true, Value})
168 List1 = [Elem]
169 List2 = [Elem | Value]
170 Elem = Value = term()
171 Calls Fun(Elem) on successive elements Elem of List1. Fun/1 must
173 return either a Boolean or a tuple {true, Value}. The function
174 returns the list of elements for which Fun returns a new value,
175 where a value of true is synonymous with {true, Elem}.
176 That is, filtermap behaves as if it had been defined as follows:
178 filtermap(Fun, List1) ->
180 lists:foldr(fun(Elem, Acc) ->
181 case Fun(Elem) of
182 false -> Acc;
183 true -> [Elem|Acc];
184 {true,Value} -> [Value|Acc]
185 end
186 end, [], List1).
187 Example:
189 > lists:filtermap(fun(X) -> case X rem 2 of 0 -> {true, X div 2}; _ -> false end end, [1,2,3,4,5]).
191 [1,2]
192 flatlength(DeepList) -> integer() >= 0
194 Types:
196 DeepList = [term() | DeepList]
198 Equivalent to length(flatten(DeepList)), but more efficient.
200 flatmap(Fun, List1) -> List2
202 Types:
204 Fun = fun((A) -> [B])
206 List1 = [A]
207 List2 = [B]
208 A = B = term()
209 Takes a function from As to lists of Bs, and a list of As
211 (List1) and produces a list of Bs by applying the function to
212 every element in List1 and appending the resulting lists.
213 That is, flatmap behaves as if it had been defined as follows:
215 flatmap(Fun, List1) ->
217 append(map(Fun, List1)).
218 Example:
220 > lists:flatmap(fun(X)->[X,X] end, [a,b,c]).
222 [a,a,b,b,c,c]
223 flatten(DeepList) -> List
225 Types:
227 DeepList = [term() | DeepList]
229 List = [term()]
230 Returns a flattened version of DeepList.
232 flatten(DeepList, Tail) -> List
234 Types:
236 DeepList = [term() | DeepList]
238 Tail = List = [term()]
239 Returns a flattened version of DeepList with tail Tail appended.
241 foldl(Fun, Acc0, List) -> Acc1
243 Types:
245 Fun = fun((Elem :: T, AccIn) -> AccOut)
247 Acc0 = Acc1 = AccIn = AccOut = term()
248 List = [T]
249 T = term()
250 Calls Fun(Elem, AccIn) on successive elements A of List, start‐
252 ing with AccIn == Acc0. Fun/2 must return a new accumulator,
253 which is passed to the next call. The function returns the final
254 value of the accumulator. Acc0 is returned if the list is empty.
255 Example:
257 > lists:foldl(fun(X, Sum) -> X + Sum end, 0, [1,2,3,4,5]).
259 15
260 > lists:foldl(fun(X, Prod) -> X * Prod end, 1, [1,2,3,4,5]).
261 120
262 foldr(Fun, Acc0, List) -> Acc1
264 Types:
266 Fun = fun((Elem :: T, AccIn) -> AccOut)
268 Acc0 = Acc1 = AccIn = AccOut = term()
269 List = [T]
270 T = term()
271 Like foldl/3, but the list is traversed from right to left.
273 Example:
275 > P = fun(A, AccIn) -> io:format("~p ", [A]), AccIn end.
277 #Fun<erl_eval.12.2225172>
278 > lists:foldl(P, void, [1,2,3]).
279 1 2 3 void
280 > lists:foldr(P, void, [1,2,3]).
281 3 2 1 void
282 foldl/3 is tail recursive and is usually preferred to foldr/3.
284 join(Sep, List1) -> List2
286 Types:
288 Sep = T
290 List1 = List2 = [T]
291 T = term()
292 Inserts Sep between each element in List1. Has no effect on the
294 empty list and on a singleton list. For example:
295 > lists:join(x, [a,b,c]).
297 [a,x,b,x,c]
298 > lists:join(x, [a]).
299 [a]
300 > lists:join(x, []).
301 []
302 foreach(Fun, List) -> ok
304 Types:
306 Fun = fun((Elem :: T) -> term())
308 List = [T]
309 T = term()
310 Calls Fun(Elem) for each element Elem in List. This function is
312 used for its side effects and the evaluation order is defined to
313 be the same as the order of the elements in the list.
314 keydelete(Key, N, TupleList1) -> TupleList2
316 Types:
318 Key = term()
320 N = integer() >= 1
321 1..tuple_size(Tuple)
322 TupleList1 = TupleList2 = [Tuple]
323 Tuple = tuple()
324 Returns a copy of TupleList1 where the first occurrence of a tu‐
326 ple whose Nth element compares equal to Key is deleted, if there
327 is such a tuple.
328 keyfind(Key, N, TupleList) -> Tuple | false
330 Types:
332 Key = term()
334 N = integer() >= 1
335 1..tuple_size(Tuple)
336 TupleList = [Tuple]
337 Tuple = tuple()
338 Searches the list of tuples TupleList for a tuple whose Nth ele‐
340 ment compares equal to Key. Returns Tuple if such a tuple is
341 found, otherwise false.
342 keymap(Fun, N, TupleList1) -> TupleList2
344 Types:
346 Fun = fun((Term1 :: term()) -> Term2 :: term())
348 N = integer() >= 1
349 1..tuple_size(Tuple)
350 TupleList1 = TupleList2 = [Tuple]
351 Tuple = tuple()
352 Returns a list of tuples where, for each tuple in TupleList1,
354 the Nth element Term1 of the tuple has been replaced with the
355 result of calling Fun(Term1).
356 Examples:
358 > Fun = fun(Atom) -> atom_to_list(Atom) end.
360 #Fun<erl_eval.6.10732646>
361 2> lists:keymap(Fun, 2, [{name,jane,22},{name,lizzie,20},{name,lydia,15}]).
362 [{name,"jane",22},{name,"lizzie",20},{name,"lydia",15}]
363 keymember(Key, N, TupleList) -> boolean()
365 Types:
367 Key = term()
369 N = integer() >= 1
370 1..tuple_size(Tuple)
371 TupleList = [Tuple]
372 Tuple = tuple()
373 Returns true if there is a tuple in TupleList whose Nth element
375 compares equal to Key, otherwise false.
376 keymerge(N, TupleList1, TupleList2) -> TupleList3
378 Types:
380 N = integer() >= 1
382 1..tuple_size(Tuple)
383 TupleList1 = [T1]
384 TupleList2 = [T2]
385 TupleList3 = [T1 | T2]
386 T1 = T2 = Tuple
387 Tuple = tuple()
388 Returns the sorted list formed by merging TupleList1 and Tu‐
390 pleList2. The merge is performed on the Nth element of each tu‐
391 ple. Both TupleList1 and TupleList2 must be key-sorted before
392 evaluating this function. When two tuples compare equal, the tu‐
393 ple from TupleList1 is picked before the tuple from TupleList2.
394 keyreplace(Key, N, TupleList1, NewTuple) -> TupleList2
396 Types:
398 Key = term()
400 N = integer() >= 1
401 1..tuple_size(Tuple)
402 TupleList1 = TupleList2 = [Tuple]
403 NewTuple = Tuple
404 Tuple = tuple()
405 Returns a copy of TupleList1 where the first occurrence of a T
407 tuple whose Nth element compares equal to Key is replaced with
408 NewTuple, if there is such a tuple T.
409 keysearch(Key, N, TupleList) -> {value, Tuple} | false
411 Types:
413 Key = term()
415 N = integer() >= 1
416 1..tuple_size(Tuple)
417 TupleList = [Tuple]
418 Tuple = tuple()
419 Searches the list of tuples TupleList for a tuple whose Nth ele‐
421 ment compares equal to Key. Returns {value, Tuple} if such a tu‐
422 ple is found, otherwise false.
423 Note:
425 This function is retained for backward compatibility. Function
426 keyfind/3 is usually more convenient.
427 keysort(N, TupleList1) -> TupleList2
430 Types:
432 N = integer() >= 1
434 1..tuple_size(Tuple)
435 TupleList1 = TupleList2 = [Tuple]
436 Tuple = tuple()
437 Returns a list containing the sorted elements of list Tu‐
439 pleList1. Sorting is performed on the Nth element of the tuples.
440 The sort is stable.
441 keystore(Key, N, TupleList1, NewTuple) -> TupleList2
443 Types:
445 Key = term()
447 N = integer() >= 1
448 1..tuple_size(Tuple)
449 TupleList1 = [Tuple]
450 TupleList2 = [Tuple, ...]
451 NewTuple = Tuple
452 Tuple = tuple()
453 Returns a copy of TupleList1 where the first occurrence of a tu‐
455 ple T whose Nth element compares equal to Key is replaced with
456 NewTuple, if there is such a tuple T. If there is no such tuple
457 T, a copy of TupleList1 where [NewTuple] has been appended to
458 the end is returned.
459 keytake(Key, N, TupleList1) -> {value, Tuple, TupleList2} | false
461 Types:
463 Key = term()
465 N = integer() >= 1
466 1..tuple_size(Tuple)
467 TupleList1 = TupleList2 = [tuple()]
468 Tuple = tuple()
469 Searches the list of tuples TupleList1 for a tuple whose Nth el‐
471 ement compares equal to Key. Returns {value, Tuple, TupleList2}
472 if such a tuple is found, otherwise false. TupleList2 is a copy
473 of TupleList1 where the first occurrence of Tuple has been re‐
474 moved.
475 last(List) -> Last
477 Types:
479 List = [T, ...]
481 Last = T
482 T = term()
483 Returns the last element in List.
485 map(Fun, List1) -> List2
487 Types:
489 Fun = fun((A) -> B)
491 List1 = [A]
492 List2 = [B]
493 A = B = term()
494 Takes a function from As to Bs, and a list of As and produces a
496 list of Bs by applying the function to every element in the
497 list. This function is used to obtain the return values. The
498 evaluation order depends on the implementation.
499 mapfoldl(Fun, Acc0, List1) -> {List2, Acc1}
501 Types:
503 Fun = fun((A, AccIn) -> {B, AccOut})
505 Acc0 = Acc1 = AccIn = AccOut = term()
506 List1 = [A]
507 List2 = [B]
508 A = B = term()
509 Combines the operations of map/2 and foldl/3 into one pass.
511 Example:
513 Summing the elements in a list and double them at the same time:
515 > lists:mapfoldl(fun(X, Sum) -> {2*X, X+Sum} end,
517 0, [1,2,3,4,5]).
518 {[2,4,6,8,10],15}
519 mapfoldr(Fun, Acc0, List1) -> {List2, Acc1}
521 Types:
523 Fun = fun((A, AccIn) -> {B, AccOut})
525 Acc0 = Acc1 = AccIn = AccOut = term()
526 List1 = [A]
527 List2 = [B]
528 A = B = term()
529 Combines the operations of map/2 and foldr/3 into one pass.
531 max(List) -> Max
533 Types:
535 List = [T, ...]
537 Max = T
538 T = term()
539 Returns the first element of List that compares greater than or
541 equal to all other elements of List.
542 member(Elem, List) -> boolean()
544 Types:
546 Elem = T
548 List = [T]
549 T = term()
550 Returns true if Elem matches some element of List, otherwise
552 false.
553 merge(ListOfLists) -> List1
555 Types:
557 ListOfLists = [List]
559 List = List1 = [T]
560 T = term()
561 Returns the sorted list formed by merging all the sublists of
563 ListOfLists. All sublists must be sorted before evaluating this
564 function. When two elements compare equal, the element from the
565 sublist with the lowest position in ListOfLists is picked before
566 the other element.
567 merge(List1, List2) -> List3
569 Types:
571 List1 = [X]
573 List2 = [Y]
574 List3 = [X | Y]
575 X = Y = term()
576 Returns the sorted list formed by merging List1 and List2. Both
578 List1 and List2 must be sorted before evaluating this function.
579 When two elements compare equal, the element from List1 is
580 picked before the element from List2.
581 merge(Fun, List1, List2) -> List3
583 Types:
585 Fun = fun((A, B) -> boolean())
587 List1 = [A]
588 List2 = [B]
589 List3 = [A | B]
590 A = B = term()
591 Returns the sorted list formed by merging List1 and List2. Both
593 List1 and List2 must be sorted according to the ordering func‐
594 tion Fun before evaluating this function. Fun(A, B) is to return
595 true if A compares less than or equal to B in the ordering, oth‐
596 erwise false. When two elements compare equal, the element from
597 List1 is picked before the element from List2.
598 merge3(List1, List2, List3) -> List4
600 Types:
602 List1 = [X]
604 List2 = [Y]
605 List3 = [Z]
606 List4 = [X | Y | Z]
607 X = Y = Z = term()
608 Returns the sorted list formed by merging List1, List2, and
610 List3. All of List1, List2, and List3 must be sorted before
611 evaluating this function. When two elements compare equal, the
612 element from List1, if there is such an element, is picked be‐
613 fore the other element, otherwise the element from List2 is
614 picked before the element from List3.
615 min(List) -> Min
617 Types:
619 List = [T, ...]
621 Min = T
622 T = term()
623 Returns the first element of List that compares less than or
625 equal to all other elements of List.
626 nth(N, List) -> Elem
628 Types:
630 N = integer() >= 1
632 1..length(List)
633 List = [T, ...]
634 Elem = T
635 T = term()
636 Returns the Nth element of List.
638 Example:
640 > lists:nth(3, [a, b, c, d, e]).
642 c
643 nthtail(N, List) -> Tail
645 Types:
647 N = integer() >= 0
649 0..length(List)
650 List = [T, ...]
651 Tail = [T]
652 T = term()
653 Returns the Nth tail of List, that is, the sublist of List
655 starting at N+1 and continuing up to the end of the list.
656 Example
658 > lists:nthtail(3, [a, b, c, d, e]).
660 [d,e]
661 > tl(tl(tl([a, b, c, d, e]))).
662 [d,e]
663 > lists:nthtail(0, [a, b, c, d, e]).
664 [a,b,c,d,e]
665 > lists:nthtail(5, [a, b, c, d, e]).
666 []
667 partition(Pred, List) -> {Satisfying, NotSatisfying}
669 Types:
671 Pred = fun((Elem :: T) -> boolean())
673 List = Satisfying = NotSatisfying = [T]
674 T = term()
675 Partitions List into two lists, where the first list contains
677 all elements for which Pred(Elem) returns true, and the second
678 list contains all elements for which Pred(Elem) returns false.
679 Examples:
681 > lists:partition(fun(A) -> A rem 2 == 1 end, [1,2,3,4,5,6,7]).
683 {[1,3,5,7],[2,4,6]}
684 > lists:partition(fun(A) -> is_atom(A) end, [a,b,1,c,d,2,3,4,e]).
685 {[a,b,c,d,e],[1,2,3,4]}
686 For a different way to partition a list, see splitwith/2.
688 prefix(List1, List2) -> boolean()
690 Types:
692 List1 = List2 = [T]
694 T = term()
695 Returns true if List1 is a prefix of List2, otherwise false.
697 reverse(List1) -> List2
699 Types:
701 List1 = List2 = [T]
703 T = term()
704 Returns a list with the elements in List1 in reverse order.
706 reverse(List1, Tail) -> List2
708 Types:
710 List1 = [T]
712 Tail = term()
713 List2 = [T]
714 T = term()
715 Returns a list with the elements in List1 in reverse order, with
717 tail Tail appended.
718 Example:
720 > lists:reverse([1, 2, 3, 4], [a, b, c]).
722 [4,3,2,1,a,b,c]
723 search(Pred, List) -> {value, Value} | false
725 Types:
727 Pred = fun((T) -> boolean())
729 List = [T]
730 Value = T
731 If there is a Value in List such that Pred(Value) returns true,
733 returns {value, Value} for the first such Value, otherwise re‐
734 turns false. The Pred function must return a boolean.
735 seq(From, To) -> Seq
737 seq(From, To, Incr) -> Seq
739 Types:
741 From = To = Incr = integer()
743 Seq = [integer()]
744 Returns a sequence of integers that starts with From and con‐
746 tains the successive results of adding Incr to the previous ele‐
747 ment, until To is reached or passed (in the latter case, To is
748 not an element of the sequence). Incr defaults to 1.
749 Failures:
751 * If To < From - Incr and Incr > 0.
753 * If To > From - Incr and Incr < 0.
755 * If Incr =:= 0 and From =/= To.
757 The following equalities hold for all sequences:
759 length(lists:seq(From, To)) =:= To - From + 1
761 length(lists:seq(From, To, Incr)) =:= (To - From + Incr) div Incr
762 Examples:
764 > lists:seq(1, 10).
766 [1,2,3,4,5,6,7,8,9,10]
767 > lists:seq(1, 20, 3).
768 [1,4,7,10,13,16,19]
769 > lists:seq(1, 0, 1).
770 []
771 > lists:seq(10, 6, 4).
772 []
773 > lists:seq(1, 1, 0).
774 [1]
775 sort(List1) -> List2
777 Types:
779 List1 = List2 = [T]
781 T = term()
782 Returns a list containing the sorted elements of List1.
784 sort(Fun, List1) -> List2
786 Types:
788 Fun = fun((A :: T, B :: T) -> boolean())
790 List1 = List2 = [T]
791 T = term()
792 Returns a list containing the sorted elements of List1, accord‐
794 ing to the ordering function Fun. Fun(A, B) is to return true if
795 A compares less than or equal to B in the ordering, otherwise
796 false.
797 split(N, List1) -> {List2, List3}
799 Types:
801 N = integer() >= 0
803 0..length(List1)
804 List1 = List2 = List3 = [T]
805 T = term()
806 Splits List1 into List2 and List3. List2 contains the first N
808 elements and List3 the remaining elements (the Nth tail).
809 splitwith(Pred, List) -> {List1, List2}
811 Types:
813 Pred = fun((T) -> boolean())
815 List = List1 = List2 = [T]
816 T = term()
817 Partitions List into two lists according to Pred. splitwith/2
819 behaves as if it is defined as follows:
820 splitwith(Pred, List) ->
822 {takewhile(Pred, List), dropwhile(Pred, List)}.
823 Examples:
825 > lists:splitwith(fun(A) -> A rem 2 == 1 end, [1,2,3,4,5,6,7]).
827 {[1],[2,3,4,5,6,7]}
828 > lists:splitwith(fun(A) -> is_atom(A) end, [a,b,1,c,d,2,3,4,e]).
829 {[a,b],[1,c,d,2,3,4,e]}
830 The Pred function must return a boolean. For a different way to
832 partition a list, see partition/2.
833 sublist(List1, Len) -> List2
835 Types:
837 List1 = List2 = [T]
839 Len = integer() >= 0
840 T = term()
841 Returns the sublist of List1 starting at position 1 and with
843 (maximum) Len elements. It is not an error for Len to exceed the
844 length of the list, in that case the whole list is returned.
845 sublist(List1, Start, Len) -> List2
847 Types:
849 List1 = List2 = [T]
851 Start = integer() >= 1
852 1..(length(List1)+1)
853 Len = integer() >= 0
854 T = term()
855 Returns the sublist of List1 starting at Start and with (maxi‐
857 mum) Len elements. It is not an error for Start+Len to exceed
858 the length of the list.
859 Examples:
861 > lists:sublist([1,2,3,4], 2, 2).
863 [2,3]
864 > lists:sublist([1,2,3,4], 2, 5).
865 [2,3,4]
866 > lists:sublist([1,2,3,4], 5, 2).
867 []
868 subtract(List1, List2) -> List3
870 Types:
872 List1 = List2 = List3 = [T]
874 T = term()
875 Returns a new list List3 that is a copy of List1, subjected to
877 the following procedure: for each element in List2, its first
878 occurrence in List1 is deleted.
879 Example:
881 > lists:subtract("123212", "212").
883 "312".
884 lists:subtract(A, B) is equivalent to A -- B.
886 suffix(List1, List2) -> boolean()
888 Types:
890 List1 = List2 = [T]
892 T = term()
893 Returns true if List1 is a suffix of List2, otherwise false.
895 sum(List) -> number()
897 Types:
899 List = [number()]
901 Returns the sum of the elements in List.
903 takewhile(Pred, List1) -> List2
905 Types:
907 Pred = fun((Elem :: T) -> boolean())
909 List1 = List2 = [T]
910 T = term()
911 Takes elements Elem from List1 while Pred(Elem) returns true,
913 that is, the function returns the longest prefix of the list for
914 which all elements satisfy the predicate. The Pred function must
915 return a boolean.
916 ukeymerge(N, TupleList1, TupleList2) -> TupleList3
918 Types:
920 N = integer() >= 1
922 1..tuple_size(Tuple)
923 TupleList1 = [T1]
924 TupleList2 = [T2]
925 TupleList3 = [T1 | T2]
926 T1 = T2 = Tuple
927 Tuple = tuple()
928 Returns the sorted list formed by merging TupleList1 and Tu‐
930 pleList2. The merge is performed on the Nth element of each tu‐
931 ple. Both TupleList1 and TupleList2 must be key-sorted without
932 duplicates before evaluating this function. When two tuples com‐
933 pare equal, the tuple from TupleList1 is picked and the one from
934 TupleList2 is deleted.
935 ukeysort(N, TupleList1) -> TupleList2
937 Types:
939 N = integer() >= 1
941 1..tuple_size(Tuple)
942 TupleList1 = TupleList2 = [Tuple]
943 Tuple = tuple()
944 Returns a list containing the sorted elements of list TupleList1
946 where all except the first tuple of the tuples comparing equal
947 have been deleted. Sorting is performed on the Nth element of
948 the tuples.
949 umerge(ListOfLists) -> List1
951 Types:
953 ListOfLists = [List]
955 List = List1 = [T]
956 T = term()
957 Returns the sorted list formed by merging all the sublists of
959 ListOfLists. All sublists must be sorted and contain no dupli‐
960 cates before evaluating this function. When two elements compare
961 equal, the element from the sublist with the lowest position in
962 ListOfLists is picked and the other is deleted.
963 umerge(List1, List2) -> List3
965 Types:
967 List1 = [X]
969 List2 = [Y]
970 List3 = [X | Y]
971 X = Y = term()
972 Returns the sorted list formed by merging List1 and List2. Both
974 List1 and List2 must be sorted and contain no duplicates before
975 evaluating this function. When two elements compare equal, the
976 element from List1 is picked and the one from List2 is deleted.
977 umerge(Fun, List1, List2) -> List3
979 Types:
981 Fun = fun((A, B) -> boolean())
983 List1 = [A]
984 List2 = [B]
985 List3 = [A | B]
986 A = B = term()
987 Returns the sorted list formed by merging List1 and List2. Both
989 List1 and List2 must be sorted according to the ordering func‐
990 tion Fun and contain no duplicates before evaluating this func‐
991 tion. Fun(A, B) is to return true if A compares less than or
992 equal to B in the ordering, otherwise false. When two elements
993 compare equal, the element from List1 is picked and the one from
994 List2 is deleted.
995 umerge3(List1, List2, List3) -> List4
997 Types:
999 List1 = [X]
1001 List2 = [Y]
1002 List3 = [Z]
1003 List4 = [X | Y | Z]
1004 X = Y = Z = term()
1005 Returns the sorted list formed by merging List1, List2, and
1007 List3. All of List1, List2, and List3 must be sorted and contain
1008 no duplicates before evaluating this function. When two elements
1009 compare equal, the element from List1 is picked if there is such
1010 an element, otherwise the element from List2 is picked, and the
1011 other is deleted.
1012 unzip(List1) -> {List2, List3}
1014 Types:
1016 List1 = [{A, B}]
1018 List2 = [A]
1019 List3 = [B]
1020 A = B = term()
1021 "Unzips" a list of two-tuples into two lists, where the first
1023 list contains the first element of each tuple, and the second
1024 list contains the second element of each tuple.
1025 unzip3(List1) -> {List2, List3, List4}
1027 Types:
1029 List1 = [{A, B, C}]
1031 List2 = [A]
1032 List3 = [B]
1033 List4 = [C]
1034 A = B = C = term()
1035 "Unzips" a list of three-tuples into three lists, where the
1037 first list contains the first element of each tuple, the second
1038 list contains the second element of each tuple, and the third
1039 list contains the third element of each tuple.
1040 usort(List1) -> List2
1042 Types:
1044 List1 = List2 = [T]
1046 T = term()
1047 Returns a list containing the sorted elements of List1 where all
1049 except the first element of the elements comparing equal have
1050 been deleted.
1051 usort(Fun, List1) -> List2
1053 Types:
1055 Fun = fun((T, T) -> boolean())
1057 List1 = List2 = [T]
1058 T = term()
1059 Returns a list containing the sorted elements of List1 where all
1061 except the first element of the elements comparing equal accord‐
1062 ing to the ordering function Fun have been deleted. Fun(A, B) is
1063 to return true if A compares less than or equal to B in the or‐
1064 dering, otherwise false.
1065 zip(List1, List2) -> List3
1067 Types:
1069 List1 = [A]
1071 List2 = [B]
1072 List3 = [{A, B}]
1073 A = B = term()
1074 "Zips" two lists of equal length into one list of two-tuples,
1076 where the first element of each tuple is taken from the first
1077 list and the second element is taken from the corresponding ele‐
1078 ment in the second list.
1079 zip3(List1, List2, List3) -> List4
1081 Types:
1083 List1 = [A]
1085 List2 = [B]
1086 List3 = [C]
1087 List4 = [{A, B, C}]
1088 A = B = C = term()
1089 "Zips" three lists of equal length into one list of three-tu‐
1091 ples, where the first element of each tuple is taken from the
1092 first list, the second element is taken from the corresponding
1093 element in the second list, and the third element is taken from
1094 the corresponding element in the third list.
1095 zipwith(Combine, List1, List2) -> List3
1097 Types:
1099 Combine = fun((X, Y) -> T)
1101 List1 = [X]
1102 List2 = [Y]
1103 List3 = [T]
1104 X = Y = T = term()
1105 Combines the elements of two lists of equal length into one
1107 list. For each pair X, Y of list elements from the two lists,
1108 the element in the result list is Combine(X, Y).
1109 zipwith(fun(X, Y) -> {X,Y} end, List1, List2) is equivalent to
1111 zip(List1, List2).
1112 Example:
1114 > lists:zipwith(fun(X, Y) -> X+Y end, [1,2,3], [4,5,6]).
1116 [5,7,9]
1117 zipwith3(Combine, List1, List2, List3) -> List4
1119 Types:
1121 Combine = fun((X, Y, Z) -> T)
1123 List1 = [X]
1124 List2 = [Y]
1125 List3 = [Z]
1126 List4 = [T]
1127 X = Y = Z = T = term()
1128 Combines the elements of three lists of equal length into one
1130 list. For each triple X, Y, Z of list elements from the three
1131 lists, the element in the result list is Combine(X, Y, Z).
1132 zipwith3(fun(X, Y, Z) -> {X,Y,Z} end, List1, List2, List3) is
1134 equivalent to zip3(List1, List2, List3).
1135 Examples:
1137 > lists:zipwith3(fun(X, Y, Z) -> X+Y+Z end, [1,2,3], [4,5,6], [7,8,9]).
1139 [12,15,18]
1140 > lists:zipwith3(fun(X, Y, Z) -> [X,Y,Z] end, [a,b,c], [x,y,z], [1,2,3]).
1141 [[a,x,1],[b,y,2],[c,z,3]]
1142Ericsson AB stdlib 3.17.2 lists(3)