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 enumerate(List1) -> List2
152 enumerate(Index, List1) -> List2
154 enumerate(Index, Step, List1) -> List2
156 Types:
158 List1 = [T]
160 List2 = [{Index, T}]
161 Index = Step = integer()
162 T = term()
163 Returns List1 with each element H replaced by a tuple of form
165 {I, H} where I is the position of H in List1. The enumeration
166 starts with Index and increases by Step in each step.
167 That is, enumerate/3 behaves as if it had been defined as fol‐
169 lows:
170 enumerate(I, S, List) ->
172 {List1, _ } = lists:mapfoldl(fun(T, Acc) -> {{Acc, T}, Acc+S} end, I, List),
173 List1.
174 The default values for Index and Step are both 1.
176 Examples:
178 > lists:enumerate([a,b,c]).
180 [{1,a},{2,b},{3,c}]
181 > lists:enumerate(10, [a,b,c]).
183 [{10,a},{11,b},{12,c}]
184 > lists:enumerate(0, -2, [a,b,c]).
186 [{0,a},{-2,b},{-4,c}]
187 filter(Pred, List1) -> List2
189 Types:
191 Pred = fun((Elem :: T) -> boolean())
193 List1 = List2 = [T]
194 T = term()
195 List2 is a list of all elements Elem in List1 for which
197 Pred(Elem) returns true. The Pred function must return a bool‐
198 ean.
199 filtermap(Fun, List1) -> List2
201 Types:
203 Fun = fun((Elem) -> boolean() | {true, Value})
205 List1 = [Elem]
206 List2 = [Elem | Value]
207 Elem = Value = term()
208 Calls Fun(Elem) on successive elements Elem of List1. Fun/1 must
210 return either a Boolean or a tuple {true, Value}. The function
211 returns the list of elements for which Fun returns a new value,
212 where a value of true is synonymous with {true, Elem}.
213 That is, filtermap behaves as if it had been defined as follows:
215 filtermap(Fun, List1) ->
217 lists:foldr(fun(Elem, Acc) ->
218 case Fun(Elem) of
219 false -> Acc;
220 true -> [Elem|Acc];
221 {true,Value} -> [Value|Acc]
222 end
223 end, [], List1).
224 Example:
226 > lists:filtermap(fun(X) -> case X rem 2 of 0 -> {true, X div 2}; _ -> false end end, [1,2,3,4,5]).
228 [1,2]
229 flatlength(DeepList) -> integer() >= 0
231 Types:
233 DeepList = [term() | DeepList]
235 Equivalent to length(flatten(DeepList)), but more efficient.
237 flatmap(Fun, List1) -> List2
239 Types:
241 Fun = fun((A) -> [B])
243 List1 = [A]
244 List2 = [B]
245 A = B = term()
246 Takes a function from As to lists of Bs, and a list of As
248 (List1) and produces a list of Bs by applying the function to
249 every element in List1 and appending the resulting lists.
250 That is, flatmap behaves as if it had been defined as follows:
252 flatmap(Fun, List1) ->
254 append(map(Fun, List1)).
255 Example:
257 > lists:flatmap(fun(X)->[X,X] end, [a,b,c]).
259 [a,a,b,b,c,c]
260 flatten(DeepList) -> List
262 Types:
264 DeepList = [term() | DeepList]
266 List = [term()]
267 Returns a flattened version of DeepList.
269 flatten(DeepList, Tail) -> List
271 Types:
273 DeepList = [term() | DeepList]
275 Tail = List = [term()]
276 Returns a flattened version of DeepList with tail Tail appended.
278 foldl(Fun, Acc0, List) -> Acc1
280 Types:
282 Fun = fun((Elem :: T, AccIn) -> AccOut)
284 Acc0 = Acc1 = AccIn = AccOut = term()
285 List = [T]
286 T = term()
287 Calls Fun(Elem, AccIn) on successive elements A of List, start‐
289 ing with AccIn == Acc0. Fun/2 must return a new accumulator,
290 which is passed to the next call. The function returns the final
291 value of the accumulator. Acc0 is returned if the list is empty.
292 Example:
294 > lists:foldl(fun(X, Sum) -> X + Sum end, 0, [1,2,3,4,5]).
296 15
297 > lists:foldl(fun(X, Prod) -> X * Prod end, 1, [1,2,3,4,5]).
298 120
299 foldr(Fun, Acc0, List) -> Acc1
301 Types:
303 Fun = fun((Elem :: T, AccIn) -> AccOut)
305 Acc0 = Acc1 = AccIn = AccOut = term()
306 List = [T]
307 T = term()
308 Like foldl/3, but the list is traversed from right to left.
310 Example:
312 > P = fun(A, AccIn) -> io:format("~p ", [A]), AccIn end.
314 #Fun<erl_eval.12.2225172>
315 > lists:foldl(P, void, [1,2,3]).
316 1 2 3 void
317 > lists:foldr(P, void, [1,2,3]).
318 3 2 1 void
319 foldl/3 is tail recursive and is usually preferred to foldr/3.
321 join(Sep, List1) -> List2
323 Types:
325 Sep = T
327 List1 = List2 = [T]
328 T = term()
329 Inserts Sep between each element in List1. Has no effect on the
331 empty list and on a singleton list. For example:
332 > lists:join(x, [a,b,c]).
334 [a,x,b,x,c]
335 > lists:join(x, [a]).
336 [a]
337 > lists:join(x, []).
338 []
339 foreach(Fun, List) -> ok
341 Types:
343 Fun = fun((Elem :: T) -> term())
345 List = [T]
346 T = term()
347 Calls Fun(Elem) for each element Elem in List. This function is
349 used for its side effects and the evaluation order is defined to
350 be the same as the order of the elements in the list.
351 keydelete(Key, N, TupleList1) -> TupleList2
353 Types:
355 Key = term()
357 N = integer() >= 1
358 1..tuple_size(Tuple)
359 TupleList1 = TupleList2 = [Tuple]
360 Tuple = tuple()
361 Returns a copy of TupleList1 where the first occurrence of a tu‐
363 ple whose Nth element compares equal to Key is deleted, if there
364 is such a tuple.
365 keyfind(Key, N, TupleList) -> Tuple | false
367 Types:
369 Key = term()
371 N = integer() >= 1
372 1..tuple_size(Tuple)
373 TupleList = [Tuple]
374 Tuple = tuple()
375 Searches the list of tuples TupleList for a tuple whose Nth ele‐
377 ment compares equal to Key. Returns Tuple if such a tuple is
378 found, otherwise false.
379 keymap(Fun, N, TupleList1) -> TupleList2
381 Types:
383 Fun = fun((Term1 :: term()) -> Term2 :: term())
385 N = integer() >= 1
386 1..tuple_size(Tuple)
387 TupleList1 = TupleList2 = [Tuple]
388 Tuple = tuple()
389 Returns a list of tuples where, for each tuple in TupleList1,
391 the Nth element Term1 of the tuple has been replaced with the
392 result of calling Fun(Term1).
393 Examples:
395 > Fun = fun(Atom) -> atom_to_list(Atom) end.
397 #Fun<erl_eval.6.10732646>
398 2> lists:keymap(Fun, 2, [{name,jane,22},{name,lizzie,20},{name,lydia,15}]).
399 [{name,"jane",22},{name,"lizzie",20},{name,"lydia",15}]
400 keymember(Key, N, TupleList) -> boolean()
402 Types:
404 Key = term()
406 N = integer() >= 1
407 1..tuple_size(Tuple)
408 TupleList = [Tuple]
409 Tuple = tuple()
410 Returns true if there is a tuple in TupleList whose Nth element
412 compares equal to Key, otherwise false.
413 keymerge(N, TupleList1, TupleList2) -> TupleList3
415 Types:
417 N = integer() >= 1
419 1..tuple_size(Tuple)
420 TupleList1 = [T1]
421 TupleList2 = [T2]
422 TupleList3 = [T1 | T2]
423 T1 = T2 = Tuple
424 Tuple = tuple()
425 Returns the sorted list formed by merging TupleList1 and Tu‐
427 pleList2. The merge is performed on the Nth element of each tu‐
428 ple. Both TupleList1 and TupleList2 must be key-sorted before
429 evaluating this function. When two tuples compare equal, the tu‐
430 ple from TupleList1 is picked before the tuple from TupleList2.
431 keyreplace(Key, N, TupleList1, NewTuple) -> TupleList2
433 Types:
435 Key = term()
437 N = integer() >= 1
438 1..tuple_size(Tuple)
439 TupleList1 = TupleList2 = [Tuple]
440 NewTuple = Tuple
441 Tuple = tuple()
442 Returns a copy of TupleList1 where the first occurrence of a T
444 tuple whose Nth element compares equal to Key is replaced with
445 NewTuple, if there is such a tuple T.
446 keysearch(Key, N, TupleList) -> {value, Tuple} | false
448 Types:
450 Key = term()
452 N = integer() >= 1
453 1..tuple_size(Tuple)
454 TupleList = [Tuple]
455 Tuple = tuple()
456 Searches the list of tuples TupleList for a tuple whose Nth ele‐
458 ment compares equal to Key. Returns {value, Tuple} if such a tu‐
459 ple is found, otherwise false.
460 Note:
462 This function is retained for backward compatibility. Function
463 keyfind/3 is usually more convenient.
464 keysort(N, TupleList1) -> TupleList2
467 Types:
469 N = integer() >= 1
471 1..tuple_size(Tuple)
472 TupleList1 = TupleList2 = [Tuple]
473 Tuple = tuple()
474 Returns a list containing the sorted elements of list Tu‐
476 pleList1. Sorting is performed on the Nth element of the tuples.
477 The sort is stable.
478 keystore(Key, N, TupleList1, NewTuple) -> TupleList2
480 Types:
482 Key = term()
484 N = integer() >= 1
485 1..tuple_size(Tuple)
486 TupleList1 = [Tuple]
487 TupleList2 = [Tuple, ...]
488 NewTuple = Tuple
489 Tuple = tuple()
490 Returns a copy of TupleList1 where the first occurrence of a tu‐
492 ple T whose Nth element compares equal to Key is replaced with
493 NewTuple, if there is such a tuple T. If there is no such tuple
494 T, a copy of TupleList1 where [NewTuple] has been appended to
495 the end is returned.
496 keytake(Key, N, TupleList1) -> {value, Tuple, TupleList2} | false
498 Types:
500 Key = term()
502 N = integer() >= 1
503 1..tuple_size(Tuple)
504 TupleList1 = TupleList2 = [tuple()]
505 Tuple = tuple()
506 Searches the list of tuples TupleList1 for a tuple whose Nth el‐
508 ement compares equal to Key. Returns {value, Tuple, TupleList2}
509 if such a tuple is found, otherwise false. TupleList2 is a copy
510 of TupleList1 where the first occurrence of Tuple has been re‐
511 moved.
512 last(List) -> Last
514 Types:
516 List = [T, ...]
518 Last = T
519 T = term()
520 Returns the last element in List.
522 map(Fun, List1) -> List2
524 Types:
526 Fun = fun((A) -> B)
528 List1 = [A]
529 List2 = [B]
530 A = B = term()
531 Takes a function from As to Bs, and a list of As and produces a
533 list of Bs by applying the function to every element in the
534 list. This function is used to obtain the return values. The
535 evaluation order depends on the implementation.
536 mapfoldl(Fun, Acc0, List1) -> {List2, Acc1}
538 Types:
540 Fun = fun((A, AccIn) -> {B, AccOut})
542 Acc0 = Acc1 = AccIn = AccOut = term()
543 List1 = [A]
544 List2 = [B]
545 A = B = term()
546 Combines the operations of map/2 and foldl/3 into one pass.
548 Example:
550 Summing the elements in a list and double them at the same time:
552 > lists:mapfoldl(fun(X, Sum) -> {2*X, X+Sum} end,
554 0, [1,2,3,4,5]).
555 {[2,4,6,8,10],15}
556 mapfoldr(Fun, Acc0, List1) -> {List2, Acc1}
558 Types:
560 Fun = fun((A, AccIn) -> {B, AccOut})
562 Acc0 = Acc1 = AccIn = AccOut = term()
563 List1 = [A]
564 List2 = [B]
565 A = B = term()
566 Combines the operations of map/2 and foldr/3 into one pass.
568 max(List) -> Max
570 Types:
572 List = [T, ...]
574 Max = T
575 T = term()
576 Returns the first element of List that compares greater than or
578 equal to all other elements of List.
579 member(Elem, List) -> boolean()
581 Types:
583 Elem = T
585 List = [T]
586 T = term()
587 Returns true if Elem matches some element of List, otherwise
589 false.
590 merge(ListOfLists) -> List1
592 Types:
594 ListOfLists = [List]
596 List = List1 = [T]
597 T = term()
598 Returns the sorted list formed by merging all the sublists of
600 ListOfLists. All sublists must be sorted before evaluating this
601 function. When two elements compare equal, the element from the
602 sublist with the lowest position in ListOfLists is picked before
603 the other element.
604 merge(List1, List2) -> List3
606 Types:
608 List1 = [X]
610 List2 = [Y]
611 List3 = [X | Y]
612 X = Y = term()
613 Returns the sorted list formed by merging List1 and List2. Both
615 List1 and List2 must be sorted before evaluating this function.
616 When two elements compare equal, the element from List1 is
617 picked before the element from List2.
618 merge(Fun, List1, List2) -> List3
620 Types:
622 Fun = fun((A, B) -> boolean())
624 List1 = [A]
625 List2 = [B]
626 List3 = [A | B]
627 A = B = term()
628 Returns the sorted list formed by merging List1 and List2. Both
630 List1 and List2 must be sorted according to the ordering func‐
631 tion Fun before evaluating this function. Fun(A, B) is to return
632 true if A compares less than or equal to B in the ordering, oth‐
633 erwise false. When two elements compare equal, the element from
634 List1 is picked before the element from List2.
635 merge3(List1, List2, List3) -> List4
637 Types:
639 List1 = [X]
641 List2 = [Y]
642 List3 = [Z]
643 List4 = [X | Y | Z]
644 X = Y = Z = term()
645 Returns the sorted list formed by merging List1, List2, and
647 List3. All of List1, List2, and List3 must be sorted before
648 evaluating this function. When two elements compare equal, the
649 element from List1, if there is such an element, is picked be‐
650 fore the other element, otherwise the element from List2 is
651 picked before the element from List3.
652 min(List) -> Min
654 Types:
656 List = [T, ...]
658 Min = T
659 T = term()
660 Returns the first element of List that compares less than or
662 equal to all other elements of List.
663 nth(N, List) -> Elem
665 Types:
667 N = integer() >= 1
669 1..length(List)
670 List = [T, ...]
671 Elem = T
672 T = term()
673 Returns the Nth element of List.
675 Example:
677 > lists:nth(3, [a, b, c, d, e]).
679 c
680 nthtail(N, List) -> Tail
682 Types:
684 N = integer() >= 0
686 0..length(List)
687 List = [T, ...]
688 Tail = [T]
689 T = term()
690 Returns the Nth tail of List, that is, the sublist of List
692 starting at N+1 and continuing up to the end of the list.
693 Example
695 > lists:nthtail(3, [a, b, c, d, e]).
697 [d,e]
698 > tl(tl(tl([a, b, c, d, e]))).
699 [d,e]
700 > lists:nthtail(0, [a, b, c, d, e]).
701 [a,b,c,d,e]
702 > lists:nthtail(5, [a, b, c, d, e]).
703 []
704 partition(Pred, List) -> {Satisfying, NotSatisfying}
706 Types:
708 Pred = fun((Elem :: T) -> boolean())
710 List = Satisfying = NotSatisfying = [T]
711 T = term()
712 Partitions List into two lists, where the first list contains
714 all elements for which Pred(Elem) returns true, and the second
715 list contains all elements for which Pred(Elem) returns false.
716 Examples:
718 > lists:partition(fun(A) -> A rem 2 == 1 end, [1,2,3,4,5,6,7]).
720 {[1,3,5,7],[2,4,6]}
721 > lists:partition(fun(A) -> is_atom(A) end, [a,b,1,c,d,2,3,4,e]).
722 {[a,b,c,d,e],[1,2,3,4]}
723 For a different way to partition a list, see splitwith/2.
725 prefix(List1, List2) -> boolean()
727 Types:
729 List1 = List2 = [T]
731 T = term()
732 Returns true if List1 is a prefix of List2, otherwise false.
734 reverse(List1) -> List2
736 Types:
738 List1 = List2 = [T]
740 T = term()
741 Returns a list with the elements in List1 in reverse order.
743 reverse(List1, Tail) -> List2
745 Types:
747 List1 = [T]
749 Tail = term()
750 List2 = [T]
751 T = term()
752 Returns a list with the elements in List1 in reverse order, with
754 tail Tail appended.
755 Example:
757 > lists:reverse([1, 2, 3, 4], [a, b, c]).
759 [4,3,2,1,a,b,c]
760 search(Pred, List) -> {value, Value} | false
762 Types:
764 Pred = fun((T) -> boolean())
766 List = [T]
767 Value = T
768 If there is a Value in List such that Pred(Value) returns true,
770 returns {value, Value} for the first such Value, otherwise re‐
771 turns false. The Pred function must return a boolean.
772 seq(From, To) -> Seq
774 seq(From, To, Incr) -> Seq
776 Types:
778 From = To = Incr = integer()
780 Seq = [integer()]
781 Returns a sequence of integers that starts with From and con‐
783 tains the successive results of adding Incr to the previous ele‐
784 ment, until To is reached or passed (in the latter case, To is
785 not an element of the sequence). Incr defaults to 1.
786 Failures:
788 * If To < From - Incr and Incr > 0.
790 * If To > From - Incr and Incr < 0.
792 * If Incr =:= 0 and From =/= To.
794 The following equalities hold for all sequences:
796 length(lists:seq(From, To)) =:= To - From + 1
798 length(lists:seq(From, To, Incr)) =:= (To - From + Incr) div Incr
799 Examples:
801 > lists:seq(1, 10).
803 [1,2,3,4,5,6,7,8,9,10]
804 > lists:seq(1, 20, 3).
805 [1,4,7,10,13,16,19]
806 > lists:seq(1, 0, 1).
807 []
808 > lists:seq(10, 6, 4).
809 []
810 > lists:seq(1, 1, 0).
811 [1]
812 sort(List1) -> List2
814 Types:
816 List1 = List2 = [T]
818 T = term()
819 Returns a list containing the sorted elements of List1.
821 sort(Fun, List1) -> List2
823 Types:
825 Fun = fun((A :: T, B :: T) -> boolean())
827 List1 = List2 = [T]
828 T = term()
829 Returns a list containing the sorted elements of List1, accord‐
831 ing to the ordering function Fun. Fun(A, B) is to return true if
832 A compares less than or equal to B in the ordering, otherwise
833 false.
834 split(N, List1) -> {List2, List3}
836 Types:
838 N = integer() >= 0
840 0..length(List1)
841 List1 = List2 = List3 = [T]
842 T = term()
843 Splits List1 into List2 and List3. List2 contains the first N
845 elements and List3 the remaining elements (the Nth tail).
846 splitwith(Pred, List) -> {List1, List2}
848 Types:
850 Pred = fun((T) -> boolean())
852 List = List1 = List2 = [T]
853 T = term()
854 Partitions List into two lists according to Pred. splitwith/2
856 behaves as if it is defined as follows:
857 splitwith(Pred, List) ->
859 {takewhile(Pred, List), dropwhile(Pred, List)}.
860 Examples:
862 > lists:splitwith(fun(A) -> A rem 2 == 1 end, [1,2,3,4,5,6,7]).
864 {[1],[2,3,4,5,6,7]}
865 > lists:splitwith(fun(A) -> is_atom(A) end, [a,b,1,c,d,2,3,4,e]).
866 {[a,b],[1,c,d,2,3,4,e]}
867 The Pred function must return a boolean. For a different way to
869 partition a list, see partition/2.
870 sublist(List1, Len) -> List2
872 Types:
874 List1 = List2 = [T]
876 Len = integer() >= 0
877 T = term()
878 Returns the sublist of List1 starting at position 1 and with
880 (maximum) Len elements. It is not an error for Len to exceed the
881 length of the list, in that case the whole list is returned.
882 sublist(List1, Start, Len) -> List2
884 Types:
886 List1 = List2 = [T]
888 Start = integer() >= 1
889 1..(length(List1)+1)
890 Len = integer() >= 0
891 T = term()
892 Returns the sublist of List1 starting at Start and with (maxi‐
894 mum) Len elements. It is not an error for Start+Len to exceed
895 the length of the list.
896 Examples:
898 > lists:sublist([1,2,3,4], 2, 2).
900 [2,3]
901 > lists:sublist([1,2,3,4], 2, 5).
902 [2,3,4]
903 > lists:sublist([1,2,3,4], 5, 2).
904 []
905 subtract(List1, List2) -> List3
907 Types:
909 List1 = List2 = List3 = [T]
911 T = term()
912 Returns a new list List3 that is a copy of List1, subjected to
914 the following procedure: for each element in List2, its first
915 occurrence in List1 is deleted.
916 Example:
918 > lists:subtract("123212", "212").
920 "312".
921 lists:subtract(A, B) is equivalent to A -- B.
923 suffix(List1, List2) -> boolean()
925 Types:
927 List1 = List2 = [T]
929 T = term()
930 Returns true if List1 is a suffix of List2, otherwise false.
932 sum(List) -> number()
934 Types:
936 List = [number()]
938 Returns the sum of the elements in List.
940 takewhile(Pred, List1) -> List2
942 Types:
944 Pred = fun((Elem :: T) -> boolean())
946 List1 = List2 = [T]
947 T = term()
948 Takes elements Elem from List1 while Pred(Elem) returns true,
950 that is, the function returns the longest prefix of the list for
951 which all elements satisfy the predicate. The Pred function must
952 return a boolean.
953 ukeymerge(N, TupleList1, TupleList2) -> TupleList3
955 Types:
957 N = integer() >= 1
959 1..tuple_size(Tuple)
960 TupleList1 = [T1]
961 TupleList2 = [T2]
962 TupleList3 = [T1 | T2]
963 T1 = T2 = Tuple
964 Tuple = tuple()
965 Returns the sorted list formed by merging TupleList1 and Tu‐
967 pleList2. The merge is performed on the Nth element of each tu‐
968 ple. Both TupleList1 and TupleList2 must be key-sorted without
969 duplicates before evaluating this function. When two tuples com‐
970 pare equal, the tuple from TupleList1 is picked and the one from
971 TupleList2 is deleted.
972 ukeysort(N, TupleList1) -> TupleList2
974 Types:
976 N = integer() >= 1
978 1..tuple_size(Tuple)
979 TupleList1 = TupleList2 = [Tuple]
980 Tuple = tuple()
981 Returns a list containing the sorted elements of list TupleList1
983 where all except the first tuple of the tuples comparing equal
984 have been deleted. Sorting is performed on the Nth element of
985 the tuples.
986 umerge(ListOfLists) -> List1
988 Types:
990 ListOfLists = [List]
992 List = List1 = [T]
993 T = term()
994 Returns the sorted list formed by merging all the sublists of
996 ListOfLists. All sublists must be sorted and contain no dupli‐
997 cates before evaluating this function. When two elements compare
998 equal, the element from the sublist with the lowest position in
999 ListOfLists is picked and the other is deleted.
1000 umerge(List1, List2) -> List3
1002 Types:
1004 List1 = [X]
1006 List2 = [Y]
1007 List3 = [X | Y]
1008 X = Y = term()
1009 Returns the sorted list formed by merging List1 and List2. Both
1011 List1 and List2 must be sorted and contain no duplicates before
1012 evaluating this function. When two elements compare equal, the
1013 element from List1 is picked and the one from List2 is deleted.
1014 umerge(Fun, List1, List2) -> List3
1016 Types:
1018 Fun = fun((A, B) -> boolean())
1020 List1 = [A]
1021 List2 = [B]
1022 List3 = [A | B]
1023 A = B = term()
1024 Returns the sorted list formed by merging List1 and List2. Both
1026 List1 and List2 must be sorted according to the ordering func‐
1027 tion Fun and contain no duplicates before evaluating this func‐
1028 tion. Fun(A, B) is to return true if A compares less than or
1029 equal to B in the ordering, otherwise false. When two elements
1030 compare equal, the element from List1 is picked and the one from
1031 List2 is deleted.
1032 umerge3(List1, List2, List3) -> List4
1034 Types:
1036 List1 = [X]
1038 List2 = [Y]
1039 List3 = [Z]
1040 List4 = [X | Y | Z]
1041 X = Y = Z = term()
1042 Returns the sorted list formed by merging List1, List2, and
1044 List3. All of List1, List2, and List3 must be sorted and contain
1045 no duplicates before evaluating this function. When two elements
1046 compare equal, the element from List1 is picked if there is such
1047 an element, otherwise the element from List2 is picked, and the
1048 other is deleted.
1049 unzip(List1) -> {List2, List3}
1051 Types:
1053 List1 = [{A, B}]
1055 List2 = [A]
1056 List3 = [B]
1057 A = B = term()
1058 "Unzips" a list of two-tuples into two lists, where the first
1060 list contains the first element of each tuple, and the second
1061 list contains the second element of each tuple.
1062 unzip3(List1) -> {List2, List3, List4}
1064 Types:
1066 List1 = [{A, B, C}]
1068 List2 = [A]
1069 List3 = [B]
1070 List4 = [C]
1071 A = B = C = term()
1072 "Unzips" a list of three-tuples into three lists, where the
1074 first list contains the first element of each tuple, the second
1075 list contains the second element of each tuple, and the third
1076 list contains the third element of each tuple.
1077 usort(List1) -> List2
1079 Types:
1081 List1 = List2 = [T]
1083 T = term()
1084 Returns a list containing the sorted elements of List1 where all
1086 except the first element of the elements comparing equal have
1087 been deleted.
1088 usort(Fun, List1) -> List2
1090 Types:
1092 Fun = fun((T, T) -> boolean())
1094 List1 = List2 = [T]
1095 T = term()
1096 Returns a list containing the sorted elements of List1 where all
1098 except the first element of the elements comparing equal accord‐
1099 ing to the ordering function Fun have been deleted. Fun(A, B) is
1100 to return true if A compares less than or equal to B in the or‐
1101 dering, otherwise false.
1102 zip(List1, List2) -> List3
1104 zip(List1, List2, How) -> List3
1106 Types:
1108 List1 = [A]
1110 List2 = [B]
1111 List3 = [{A | DefaultA, B | DefaultB}]
1112 A = B = term()
1113 How = fail | trim | {pad, {DefaultA, DefaultB}}
1114 DefaultA = DefaultB = term()
1115 "Zips" two lists into one list of two-tuples, where the first
1117 element of each tuple is taken from the first list and the sec‐
1118 ond element is taken from the corresponding element in the sec‐
1119 ond list.
1120 The How parameter specifies the behavior if the given lists are
1122 of different lengths.
1123 fail:
1125 The call will fail if the given lists are not of equal
1126 length. This is the default.
1127 trim:
1129 Surplus elements from the longer list will be ignored.
1130 Examples:
1132 > lists:zip([a, b], [1, 2, 3], trim).
1134 [{a,1},{b,2}]
1135 > lists:zip([a, b, c], [1, 2], trim).
1136 [{a,1},{b,2}]
1137 {pad, Defaults}:
1139 The shorter list will be padded to the length of the longer
1140 list, using the respective elements from the given Defaults
1141 tuple.
1142 Examples:
1144 > lists:zip([a, b], [1, 2, 3], {pad, {x, 0}}).
1146 [{a,1},{b,2},{x,3}]
1147 > lists:zip([a, b, c], [1, 2], {pad, {x, 0}}).
1148 [{a,1},{b,2},{c,0}]
1149 zip3(List1, List2, List3) -> List4
1151 zip3(List1, List2, List3, How) -> List4
1153 Types:
1155 List1 = [A]
1157 List2 = [B]
1158 List3 = [C]
1159 List4 = [{A | DefaultA, B | DefaultB, C | DefaultC}]
1160 A = B = C = term()
1161 How = fail | trim | {pad, {DefaultA, DefaultB, DefaultC}}
1162 DefaultA = DefaultB = DefaultC = term()
1163 "Zips" three lists into one list of three-tuples, where the
1165 first element of each tuple is taken from the first list, the
1166 second element is taken from the corresponding element in the
1167 second list, and the third element is taken from the correspond‐
1168 ing element in the third list.
1169 For a description of the How parameter, see zip/3.
1171 zipwith(Combine, List1, List2) -> List3
1173 zipwith(Combine, List1, List2, How) -> List3
1175 Types:
1177 Combine = fun((X | DefaultX, Y | DefaultY) -> T)
1179 List1 = [X]
1180 List2 = [Y]
1181 List3 = [T]
1182 X = Y = term()
1183 How = fail | trim | {pad, {DefaultX, DefaultY}}
1184 DefaultX = DefaultY = T = term()
1185 Combines the elements of two lists into one list. For each pair
1187 X, Y of list elements from the two lists, the element in the re‐
1188 sult list is Combine(X, Y).
1189 For a description of the How parameter, see zip/3.
1191 zipwith(fun(X, Y) -> {X,Y} end, List1, List2) is equivalent to
1193 zip(List1, List2).
1194 Example:
1196 > lists:zipwith(fun(X, Y) -> X+Y end, [1,2,3], [4,5,6]).
1198 [5,7,9]
1199 zipwith3(Combine, List1, List2, List3) -> List4
1201 zipwith3(Combine, List1, List2, List3, How) -> List4
1203 Types:
1205 Combine = fun((X | DefaultX, Y | DefaultY, Z | DefaultZ) ->
1207 T)
1208 List1 = [X]
1209 List2 = [Y]
1210 List3 = [Z]
1211 List4 = [T]
1212 X = Y = Z = term()
1213 How = fail | trim | {pad, {DefaultX, DefaultY, DefaultZ}}
1214 DefaultX = DefaultY = DefaultZ = T = term()
1215 Combines the elements of three lists into one list. For each
1217 triple X, Y, Z of list elements from the three lists, the ele‐
1218 ment in the result list is Combine(X, Y, Z).
1219 For a description of the How parameter, see zip/3.
1221 zipwith3(fun(X, Y, Z) -> {X,Y,Z} end, List1, List2, List3) is
1223 equivalent to zip3(List1, List2, List3).
1224 Examples:
1226 > lists:zipwith3(fun(X, Y, Z) -> X+Y+Z end, [1,2,3], [4,5,6], [7,8,9]).
1228 [12,15,18]
1229 > lists:zipwith3(fun(X, Y, Z) -> [X,Y,Z] end, [a,b,c], [x,y,z], [1,2,3]).
1230 [[a,x,1],[b,y,2],[c,z,3]]
1231 uniq(List1) -> List2
1233 Types:
1235 List1 = List2 = [T]
1237 T = term()
1238 Returns a list containing the elements of List1 with duplicated
1240 elements removed (preserving the order of the elements). The
1241 first occurrence of each element is kept.
1242 Examples:
1244 > lists:uniq([3,3,1,2,1,2,3]).
1246 [3,1,2]
1247 > lists:uniq([a, a, 1, b, 2, a, 3]).
1248 [a, 1, b, 2, 3]
1249 uniq(Fun, List1) -> List2
1251 Types:
1253 Fun = fun((T) -> any())
1255 List1 = List2 = [T]
1256 T = term()
1257 Returns a list containing the elements of List1 without the ele‐
1259 ments for which Fun returned duplicate values (preserving the
1260 order of the elements). The first occurrence of each element is
1261 kept.
1262 Examples:
1264 > lists:uniq(fun({X, _}) -> X end, [{b, 2}, {a, 1}, {c, 3}, {a, 2}]).
1266 [{b, 2}, {a, 1}, {c, 3}]
1267Ericsson AB stdlib 5.1.1 lists(3)