1lists(3)                   Erlang Module Definition                   lists(3)
2
3
4

NAME

6       lists - List processing functions.
7

DESCRIPTION

9       This module contains functions for list processing.
10
11       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
14       Two terms T1 and T2 compare equal if T1 == T2 evaluates to  true.  They
15       match if T1 =:= T2 evaluates to true.
16
17       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
20         * If x F y and y F x, then x = y (F is antisymmetric).
21
22         * If x F y and y F z, then x F z (F is transitive).
23
24         * x F y or y F x (F is total).
25
26       An example of a typical ordering function is less  than  or  equal  to:
27       =</2.
28

EXPORTS

30       all(Pred, List) -> boolean()
31
32              Types:
33
34                 Pred = fun((Elem :: T) -> boolean())
35                 List = [T]
36                 T = term()
37
38              Returns true if Pred(Elem) returns true for all elements Elem in
39              List, otherwise false. The Pred function must return a boolean.
40
41       any(Pred, List) -> boolean()
42
43              Types:
44
45                 Pred = fun((Elem :: T) -> boolean())
46                 List = [T]
47                 T = term()
48
49              Returns true if Pred(Elem) returns true for at least one element
50              Elem in List. The Pred function must return a boolean.
51
52       append(ListOfLists) -> List1
53
54              Types:
55
56                 ListOfLists = [List]
57                 List = List1 = [T]
58                 T = term()
59
60              Returns  a  list  in  which all the sublists of ListOfLists have
61              been appended.
62
63              Example:
64
65              > lists:append([[1, 2, 3], [a, b], [4, 5, 6]]).
66              [1,2,3,a,b,4,5,6]
67
68       append(List1, List2) -> List3
69
70              Types:
71
72                 List1 = List2 = List3 = [T]
73                 T = term()
74
75              Returns a new list List3, which is made  from  the  elements  of
76              List1 followed by the elements of List2.
77
78              Example:
79
80              > lists:append("abc", "def").
81              "abcdef"
82
83              lists:append(A, B) is equivalent to A ++ B.
84
85       concat(Things) -> string()
86
87              Types:
88
89                 Things = [Thing]
90                 Thing = atom() | integer() | float() | string()
91
92              Concatenates  the text representation of the elements of Things.
93              The elements of  Things  can  be  atoms,  integers,  floats,  or
94              strings.
95
96              Example:
97
98              > lists:concat([doc, '/', file, '.', 3]).
99              "doc/file.3"
100
101       delete(Elem, List1) -> List2
102
103              Types:
104
105                 Elem = T
106                 List1 = List2 = [T]
107                 T = term()
108
109              Returns a copy of List1 where the first element matching Elem is
110              deleted, if there is such an element.
111
112       droplast(List) -> InitList
113
114              Types:
115
116                 List = [T, ...]
117                 InitList = [T]
118                 T = term()
119
120              Drops the last element of a List. The list is to  be  non-empty,
121              otherwise the function crashes with a function_clause.
122
123       dropwhile(Pred, List1) -> List2
124
125              Types:
126
127                 Pred = fun((Elem :: T) -> boolean())
128                 List1 = List2 = [T]
129                 T = term()
130
131              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
135       duplicate(N, Elem) -> List
136
137              Types:
138
139                 N = integer() >= 0
140                 Elem = T
141                 List = [T]
142                 T = term()
143
144              Returns a list containing N copies of term Elem.
145
146              Example:
147
148              > lists:duplicate(5, xx).
149              [xx,xx,xx,xx,xx]
150
151       enumerate(List1) -> List2
152
153              Types:
154
155                 List1 = [T]
156                 List2 = [{Index, T}]
157                 Index = integer()
158                 T = term()
159
160              Returns  List1  with  each element H replaced by a tuple of form
161              {I, H} where I is the position of H in  List1.  The  enumeration
162              starts with 1 and increases by 1 in each step.
163
164              That  is,  enumerate/1 behaves as if it had been defined as fol‐
165              lows:
166
167              enumerate(List) ->
168                {List1, _ } = lists:mapfoldl(fun(T, Acc) -> {{Acc, T}, Acc+1} end, 1, List),
169                List1.
170
171              Example:
172
173              > lists:enumerate([a,b,c]).
174              [{1,a},{2,b},{3,c}]
175
176       enumerate(Index, List1) -> List2
177
178              Types:
179
180                 List1 = [T]
181                 List2 = [{Index, T}]
182                 Index = integer()
183                 T = term()
184
185              Returns List1 with each element H replaced by a  tuple  of  form
186              {I,  H}  where  I is the position of H in List1. The enumeration
187              starts with Index and increases by 1 in each step.
188
189              That is, enumerate/2 behaves as if it had been defined  as  fol‐
190              lows:
191
192              enumerate(I, List) ->
193                {List1, _ } = lists:mapfoldl(fun(T, Acc) -> {{Acc, T}, Acc+1} end, I, List),
194                List1.
195
196              Example:
197
198              > lists:enumerate(10, [a,b,c]).
199              [{10,a},{11,b},{12,c}]
200
201       filter(Pred, List1) -> List2
202
203              Types:
204
205                 Pred = fun((Elem :: T) -> boolean())
206                 List1 = List2 = [T]
207                 T = term()
208
209              List2  is  a  list  of  all  elements  Elem  in  List1 for which
210              Pred(Elem) returns true. The Pred function must return  a  bool‐
211              ean.
212
213       filtermap(Fun, List1) -> List2
214
215              Types:
216
217                 Fun = fun((Elem) -> boolean() | {true, Value})
218                 List1 = [Elem]
219                 List2 = [Elem | Value]
220                 Elem = Value = term()
221
222              Calls Fun(Elem) on successive elements Elem of List1. Fun/1 must
223              return either a Boolean or a tuple {true, Value}.  The  function
224              returns  the list of elements for which Fun returns a new value,
225              where a value of true is synonymous with {true, Elem}.
226
227              That is, filtermap behaves as if it had been defined as follows:
228
229              filtermap(Fun, List1) ->
230                  lists:foldr(fun(Elem, Acc) ->
231                                     case Fun(Elem) of
232                                         false -> Acc;
233                                         true -> [Elem|Acc];
234                                         {true,Value} -> [Value|Acc]
235                                     end
236                              end, [], List1).
237
238              Example:
239
240              > lists:filtermap(fun(X) -> case X rem 2 of 0 -> {true, X div 2}; _ -> false end end, [1,2,3,4,5]).
241              [1,2]
242
243       flatlength(DeepList) -> integer() >= 0
244
245              Types:
246
247                 DeepList = [term() | DeepList]
248
249              Equivalent to length(flatten(DeepList)), but more efficient.
250
251       flatmap(Fun, List1) -> List2
252
253              Types:
254
255                 Fun = fun((A) -> [B])
256                 List1 = [A]
257                 List2 = [B]
258                 A = B = term()
259
260              Takes a function from As to lists  of  Bs,  and  a  list  of  As
261              (List1)  and  produces  a list of Bs by applying the function to
262              every element in List1 and appending the resulting lists.
263
264              That is, flatmap behaves as if it had been defined as follows:
265
266              flatmap(Fun, List1) ->
267                  append(map(Fun, List1)).
268
269              Example:
270
271              > lists:flatmap(fun(X)->[X,X] end, [a,b,c]).
272              [a,a,b,b,c,c]
273
274       flatten(DeepList) -> List
275
276              Types:
277
278                 DeepList = [term() | DeepList]
279                 List = [term()]
280
281              Returns a flattened version of DeepList.
282
283       flatten(DeepList, Tail) -> List
284
285              Types:
286
287                 DeepList = [term() | DeepList]
288                 Tail = List = [term()]
289
290              Returns a flattened version of DeepList with tail Tail appended.
291
292       foldl(Fun, Acc0, List) -> Acc1
293
294              Types:
295
296                 Fun = fun((Elem :: T, AccIn) -> AccOut)
297                 Acc0 = Acc1 = AccIn = AccOut = term()
298                 List = [T]
299                 T = term()
300
301              Calls Fun(Elem, AccIn) on successive elements A of List,  start‐
302              ing  with  AccIn  ==  Acc0. Fun/2 must return a new accumulator,
303              which is passed to the next call. The function returns the final
304              value of the accumulator. Acc0 is returned if the list is empty.
305
306              Example:
307
308              > lists:foldl(fun(X, Sum) -> X + Sum end, 0, [1,2,3,4,5]).
309              15
310              > lists:foldl(fun(X, Prod) -> X * Prod end, 1, [1,2,3,4,5]).
311              120
312
313       foldr(Fun, Acc0, List) -> Acc1
314
315              Types:
316
317                 Fun = fun((Elem :: T, AccIn) -> AccOut)
318                 Acc0 = Acc1 = AccIn = AccOut = term()
319                 List = [T]
320                 T = term()
321
322              Like foldl/3, but the list is traversed from right to left.
323
324              Example:
325
326              > P = fun(A, AccIn) -> io:format("~p ", [A]), AccIn end.
327              #Fun<erl_eval.12.2225172>
328              > lists:foldl(P, void, [1,2,3]).
329              1 2 3 void
330              > lists:foldr(P, void, [1,2,3]).
331              3 2 1 void
332
333              foldl/3 is tail recursive and is usually preferred to foldr/3.
334
335       join(Sep, List1) -> List2
336
337              Types:
338
339                 Sep = T
340                 List1 = List2 = [T]
341                 T = term()
342
343              Inserts  Sep between each element in List1. Has no effect on the
344              empty list and on a singleton list. For example:
345
346              > lists:join(x, [a,b,c]).
347              [a,x,b,x,c]
348              > lists:join(x, [a]).
349              [a]
350              > lists:join(x, []).
351              []
352
353       foreach(Fun, List) -> ok
354
355              Types:
356
357                 Fun = fun((Elem :: T) -> term())
358                 List = [T]
359                 T = term()
360
361              Calls Fun(Elem) for each element Elem in List. This function  is
362              used for its side effects and the evaluation order is defined to
363              be the same as the order of the elements in the list.
364
365       keydelete(Key, N, TupleList1) -> TupleList2
366
367              Types:
368
369                 Key = term()
370                 N = integer() >= 1
371                   1..tuple_size(Tuple)
372                 TupleList1 = TupleList2 = [Tuple]
373                 Tuple = tuple()
374
375              Returns a copy of TupleList1 where the first occurrence of a tu‐
376              ple whose Nth element compares equal to Key is deleted, if there
377              is such a tuple.
378
379       keyfind(Key, N, TupleList) -> Tuple | false
380
381              Types:
382
383                 Key = term()
384                 N = integer() >= 1
385                   1..tuple_size(Tuple)
386                 TupleList = [Tuple]
387                 Tuple = tuple()
388
389              Searches the list of tuples TupleList for a tuple whose Nth ele‐
390              ment  compares  equal  to  Key. Returns Tuple if such a tuple is
391              found, otherwise false.
392
393       keymap(Fun, N, TupleList1) -> TupleList2
394
395              Types:
396
397                 Fun = fun((Term1 :: term()) -> Term2 :: term())
398                 N = integer() >= 1
399                   1..tuple_size(Tuple)
400                 TupleList1 = TupleList2 = [Tuple]
401                 Tuple = tuple()
402
403              Returns a list of tuples where, for each  tuple  in  TupleList1,
404              the  Nth  element  Term1 of the tuple has been replaced with the
405              result of calling Fun(Term1).
406
407              Examples:
408
409              > Fun = fun(Atom) -> atom_to_list(Atom) end.
410              #Fun<erl_eval.6.10732646>
411              2> lists:keymap(Fun, 2, [{name,jane,22},{name,lizzie,20},{name,lydia,15}]).
412              [{name,"jane",22},{name,"lizzie",20},{name,"lydia",15}]
413
414       keymember(Key, N, TupleList) -> boolean()
415
416              Types:
417
418                 Key = term()
419                 N = integer() >= 1
420                   1..tuple_size(Tuple)
421                 TupleList = [Tuple]
422                 Tuple = tuple()
423
424              Returns true if there is a tuple in TupleList whose Nth  element
425              compares equal to Key, otherwise false.
426
427       keymerge(N, TupleList1, TupleList2) -> TupleList3
428
429              Types:
430
431                 N = integer() >= 1
432                   1..tuple_size(Tuple)
433                 TupleList1 = [T1]
434                 TupleList2 = [T2]
435                 TupleList3 = [T1 | T2]
436                 T1 = T2 = Tuple
437                 Tuple = tuple()
438
439              Returns  the  sorted  list  formed by merging TupleList1 and Tu‐
440              pleList2. The merge is performed on the Nth element of each  tu‐
441              ple.  Both  TupleList1  and TupleList2 must be key-sorted before
442              evaluating this function. When two tuples compare equal, the tu‐
443              ple from TupleList1 is picked before the tuple from TupleList2.
444
445       keyreplace(Key, N, TupleList1, NewTuple) -> TupleList2
446
447              Types:
448
449                 Key = term()
450                 N = integer() >= 1
451                   1..tuple_size(Tuple)
452                 TupleList1 = TupleList2 = [Tuple]
453                 NewTuple = Tuple
454                 Tuple = tuple()
455
456              Returns  a  copy of TupleList1 where the first occurrence of a T
457              tuple whose Nth element compares equal to Key is  replaced  with
458              NewTuple, if there is such a tuple T.
459
460       keysearch(Key, N, TupleList) -> {value, Tuple} | false
461
462              Types:
463
464                 Key = term()
465                 N = integer() >= 1
466                   1..tuple_size(Tuple)
467                 TupleList = [Tuple]
468                 Tuple = tuple()
469
470              Searches the list of tuples TupleList for a tuple whose Nth ele‐
471              ment compares equal to Key. Returns {value, Tuple} if such a tu‐
472              ple is found, otherwise false.
473
474          Note:
475              This  function  is retained for backward compatibility. Function
476              keyfind/3 is usually more convenient.
477
478
479       keysort(N, TupleList1) -> TupleList2
480
481              Types:
482
483                 N = integer() >= 1
484                   1..tuple_size(Tuple)
485                 TupleList1 = TupleList2 = [Tuple]
486                 Tuple = tuple()
487
488              Returns a list  containing  the  sorted  elements  of  list  Tu‐
489              pleList1. Sorting is performed on the Nth element of the tuples.
490              The sort is stable.
491
492       keystore(Key, N, TupleList1, NewTuple) -> TupleList2
493
494              Types:
495
496                 Key = term()
497                 N = integer() >= 1
498                   1..tuple_size(Tuple)
499                 TupleList1 = [Tuple]
500                 TupleList2 = [Tuple, ...]
501                 NewTuple = Tuple
502                 Tuple = tuple()
503
504              Returns a copy of TupleList1 where the first occurrence of a tu‐
505              ple  T  whose Nth element compares equal to Key is replaced with
506              NewTuple, if there is such a tuple T. If there is no such  tuple
507              T,  a  copy  of TupleList1 where [NewTuple] has been appended to
508              the end is returned.
509
510       keytake(Key, N, TupleList1) -> {value, Tuple, TupleList2} | false
511
512              Types:
513
514                 Key = term()
515                 N = integer() >= 1
516                   1..tuple_size(Tuple)
517                 TupleList1 = TupleList2 = [tuple()]
518                 Tuple = tuple()
519
520              Searches the list of tuples TupleList1 for a tuple whose Nth el‐
521              ement  compares equal to Key. Returns {value, Tuple, TupleList2}
522              if such a tuple is found, otherwise false. TupleList2 is a  copy
523              of  TupleList1  where the first occurrence of Tuple has been re‐
524              moved.
525
526       last(List) -> Last
527
528              Types:
529
530                 List = [T, ...]
531                 Last = T
532                 T = term()
533
534              Returns the last element in List.
535
536       map(Fun, List1) -> List2
537
538              Types:
539
540                 Fun = fun((A) -> B)
541                 List1 = [A]
542                 List2 = [B]
543                 A = B = term()
544
545              Takes a function from As to Bs, and a list of As and produces  a
546              list  of  Bs  by  applying  the function to every element in the
547              list. This function is used to obtain  the  return  values.  The
548              evaluation order depends on the implementation.
549
550       mapfoldl(Fun, Acc0, List1) -> {List2, Acc1}
551
552              Types:
553
554                 Fun = fun((A, AccIn) -> {B, AccOut})
555                 Acc0 = Acc1 = AccIn = AccOut = term()
556                 List1 = [A]
557                 List2 = [B]
558                 A = B = term()
559
560              Combines the operations of map/2 and foldl/3 into one pass.
561
562              Example:
563
564              Summing the elements in a list and double them at the same time:
565
566              > lists:mapfoldl(fun(X, Sum) -> {2*X, X+Sum} end,
567              0, [1,2,3,4,5]).
568              {[2,4,6,8,10],15}
569
570       mapfoldr(Fun, Acc0, List1) -> {List2, Acc1}
571
572              Types:
573
574                 Fun = fun((A, AccIn) -> {B, AccOut})
575                 Acc0 = Acc1 = AccIn = AccOut = term()
576                 List1 = [A]
577                 List2 = [B]
578                 A = B = term()
579
580              Combines the operations of map/2 and foldr/3 into one pass.
581
582       max(List) -> Max
583
584              Types:
585
586                 List = [T, ...]
587                 Max = T
588                 T = term()
589
590              Returns  the first element of List that compares greater than or
591              equal to all other elements of List.
592
593       member(Elem, List) -> boolean()
594
595              Types:
596
597                 Elem = T
598                 List = [T]
599                 T = term()
600
601              Returns true if Elem matches some  element  of  List,  otherwise
602              false.
603
604       merge(ListOfLists) -> List1
605
606              Types:
607
608                 ListOfLists = [List]
609                 List = List1 = [T]
610                 T = term()
611
612              Returns  the  sorted  list formed by merging all the sublists of
613              ListOfLists. All sublists must be sorted before evaluating  this
614              function.  When two elements compare equal, the element from the
615              sublist with the lowest position in ListOfLists is picked before
616              the other element.
617
618       merge(List1, List2) -> List3
619
620              Types:
621
622                 List1 = [X]
623                 List2 = [Y]
624                 List3 = [X | Y]
625                 X = Y = term()
626
627              Returns  the sorted list formed by merging List1 and List2. Both
628              List1 and List2 must be sorted before evaluating this  function.
629              When  two  elements  compare  equal,  the  element from List1 is
630              picked before the element from List2.
631
632       merge(Fun, List1, List2) -> List3
633
634              Types:
635
636                 Fun = fun((A, B) -> boolean())
637                 List1 = [A]
638                 List2 = [B]
639                 List3 = [A | B]
640                 A = B = term()
641
642              Returns the sorted list formed by merging List1 and List2.  Both
643              List1  and  List2 must be sorted according to the ordering func‐
644              tion Fun before evaluating this function. Fun(A, B) is to return
645              true if A compares less than or equal to B in the ordering, oth‐
646              erwise false. When two elements compare equal, the element  from
647              List1 is picked before the element from List2.
648
649       merge3(List1, List2, List3) -> List4
650
651              Types:
652
653                 List1 = [X]
654                 List2 = [Y]
655                 List3 = [Z]
656                 List4 = [X | Y | Z]
657                 X = Y = Z = term()
658
659              Returns  the  sorted  list  formed  by merging List1, List2, and
660              List3. All of List1, List2, and  List3  must  be  sorted  before
661              evaluating  this  function. When two elements compare equal, the
662              element from List1, if there is such an element, is  picked  be‐
663              fore  the  other  element,  otherwise  the element from List2 is
664              picked before the element from List3.
665
666       min(List) -> Min
667
668              Types:
669
670                 List = [T, ...]
671                 Min = T
672                 T = term()
673
674              Returns the first element of List that  compares  less  than  or
675              equal to all other elements of List.
676
677       nth(N, List) -> Elem
678
679              Types:
680
681                 N = integer() >= 1
682                   1..length(List)
683                 List = [T, ...]
684                 Elem = T
685                 T = term()
686
687              Returns the Nth element of List.
688
689              Example:
690
691              > lists:nth(3, [a, b, c, d, e]).
692              c
693
694       nthtail(N, List) -> Tail
695
696              Types:
697
698                 N = integer() >= 0
699                   0..length(List)
700                 List = [T, ...]
701                 Tail = [T]
702                 T = term()
703
704              Returns  the  Nth  tail  of  List,  that is, the sublist of List
705              starting at N+1 and continuing up to the end of the list.
706
707              Example
708
709              > lists:nthtail(3, [a, b, c, d, e]).
710              [d,e]
711              > tl(tl(tl([a, b, c, d, e]))).
712              [d,e]
713              > lists:nthtail(0, [a, b, c, d, e]).
714              [a,b,c,d,e]
715              > lists:nthtail(5, [a, b, c, d, e]).
716              []
717
718       partition(Pred, List) -> {Satisfying, NotSatisfying}
719
720              Types:
721
722                 Pred = fun((Elem :: T) -> boolean())
723                 List = Satisfying = NotSatisfying = [T]
724                 T = term()
725
726              Partitions List into two lists, where the  first  list  contains
727              all  elements  for which Pred(Elem) returns true, and the second
728              list contains all elements for which Pred(Elem) returns false.
729
730              Examples:
731
732              > lists:partition(fun(A) -> A rem 2 == 1 end, [1,2,3,4,5,6,7]).
733              {[1,3,5,7],[2,4,6]}
734              > lists:partition(fun(A) -> is_atom(A) end, [a,b,1,c,d,2,3,4,e]).
735              {[a,b,c,d,e],[1,2,3,4]}
736
737              For a different way to partition a list, see splitwith/2.
738
739       prefix(List1, List2) -> boolean()
740
741              Types:
742
743                 List1 = List2 = [T]
744                 T = term()
745
746              Returns true if List1 is a prefix of List2, otherwise false.
747
748       reverse(List1) -> List2
749
750              Types:
751
752                 List1 = List2 = [T]
753                 T = term()
754
755              Returns a list with the elements in List1 in reverse order.
756
757       reverse(List1, Tail) -> List2
758
759              Types:
760
761                 List1 = [T]
762                 Tail = term()
763                 List2 = [T]
764                 T = term()
765
766              Returns a list with the elements in List1 in reverse order, with
767              tail Tail appended.
768
769              Example:
770
771              > lists:reverse([1, 2, 3, 4], [a, b, c]).
772              [4,3,2,1,a,b,c]
773
774       search(Pred, List) -> {value, Value} | false
775
776              Types:
777
778                 Pred = fun((T) -> boolean())
779                 List = [T]
780                 Value = T
781
782              If  there is a Value in List such that Pred(Value) returns true,
783              returns {value, Value} for the first such Value,  otherwise  re‐
784              turns false. The Pred function must return a boolean.
785
786       seq(From, To) -> Seq
787
788       seq(From, To, Incr) -> Seq
789
790              Types:
791
792                 From = To = Incr = integer()
793                 Seq = [integer()]
794
795              Returns  a  sequence  of integers that starts with From and con‐
796              tains the successive results of adding Incr to the previous ele‐
797              ment,  until  To is reached or passed (in the latter case, To is
798              not an element of the sequence). Incr defaults to 1.
799
800              Failures:
801
802                * If To < From - Incr and Incr > 0.
803
804                * If To > From - Incr and Incr < 0.
805
806                * If Incr =:= 0 and From =/= To.
807
808              The following equalities hold for all sequences:
809
810              length(lists:seq(From, To)) =:= To - From + 1
811              length(lists:seq(From, To, Incr)) =:= (To - From + Incr) div Incr
812
813              Examples:
814
815              > lists:seq(1, 10).
816              [1,2,3,4,5,6,7,8,9,10]
817              > lists:seq(1, 20, 3).
818              [1,4,7,10,13,16,19]
819              > lists:seq(1, 0, 1).
820              []
821              > lists:seq(10, 6, 4).
822              []
823              > lists:seq(1, 1, 0).
824              [1]
825
826       sort(List1) -> List2
827
828              Types:
829
830                 List1 = List2 = [T]
831                 T = term()
832
833              Returns a list containing the sorted elements of List1.
834
835       sort(Fun, List1) -> List2
836
837              Types:
838
839                 Fun = fun((A :: T, B :: T) -> boolean())
840                 List1 = List2 = [T]
841                 T = term()
842
843              Returns a list containing the sorted elements of List1,  accord‐
844              ing to the ordering function Fun. Fun(A, B) is to return true if
845              A compares less than or equal to B in  the  ordering,  otherwise
846              false.
847
848       split(N, List1) -> {List2, List3}
849
850              Types:
851
852                 N = integer() >= 0
853                   0..length(List1)
854                 List1 = List2 = List3 = [T]
855                 T = term()
856
857              Splits  List1  into  List2 and List3. List2 contains the first N
858              elements and List3 the remaining elements (the Nth tail).
859
860       splitwith(Pred, List) -> {List1, List2}
861
862              Types:
863
864                 Pred = fun((T) -> boolean())
865                 List = List1 = List2 = [T]
866                 T = term()
867
868              Partitions List into two lists according  to  Pred.  splitwith/2
869              behaves as if it is defined as follows:
870
871              splitwith(Pred, List) ->
872                  {takewhile(Pred, List), dropwhile(Pred, List)}.
873
874              Examples:
875
876              > lists:splitwith(fun(A) -> A rem 2 == 1 end, [1,2,3,4,5,6,7]).
877              {[1],[2,3,4,5,6,7]}
878              > lists:splitwith(fun(A) -> is_atom(A) end, [a,b,1,c,d,2,3,4,e]).
879              {[a,b],[1,c,d,2,3,4,e]}
880
881              The  Pred function must return a boolean. For a different way to
882              partition a list, see partition/2.
883
884       sublist(List1, Len) -> List2
885
886              Types:
887
888                 List1 = List2 = [T]
889                 Len = integer() >= 0
890                 T = term()
891
892              Returns the sublist of List1 starting at  position  1  and  with
893              (maximum) Len elements. It is not an error for Len to exceed the
894              length of the list, in that case the whole list is returned.
895
896       sublist(List1, Start, Len) -> List2
897
898              Types:
899
900                 List1 = List2 = [T]
901                 Start = integer() >= 1
902                   1..(length(List1)+1)
903                 Len = integer() >= 0
904                 T = term()
905
906              Returns the sublist of List1 starting at Start and  with  (maxi‐
907              mum)  Len  elements.  It is not an error for Start+Len to exceed
908              the length of the list.
909
910              Examples:
911
912              > lists:sublist([1,2,3,4], 2, 2).
913              [2,3]
914              > lists:sublist([1,2,3,4], 2, 5).
915              [2,3,4]
916              > lists:sublist([1,2,3,4], 5, 2).
917              []
918
919       subtract(List1, List2) -> List3
920
921              Types:
922
923                 List1 = List2 = List3 = [T]
924                 T = term()
925
926              Returns a new list List3 that is a copy of List1,  subjected  to
927              the  following  procedure:  for each element in List2, its first
928              occurrence in List1 is deleted.
929
930              Example:
931
932              > lists:subtract("123212", "212").
933              "312".
934
935              lists:subtract(A, B) is equivalent to A -- B.
936
937       suffix(List1, List2) -> boolean()
938
939              Types:
940
941                 List1 = List2 = [T]
942                 T = term()
943
944              Returns true if List1 is a suffix of List2, otherwise false.
945
946       sum(List) -> number()
947
948              Types:
949
950                 List = [number()]
951
952              Returns the sum of the elements in List.
953
954       takewhile(Pred, List1) -> List2
955
956              Types:
957
958                 Pred = fun((Elem :: T) -> boolean())
959                 List1 = List2 = [T]
960                 T = term()
961
962              Takes elements Elem from List1 while  Pred(Elem)  returns  true,
963              that is, the function returns the longest prefix of the list for
964              which all elements satisfy the predicate. The Pred function must
965              return a boolean.
966
967       ukeymerge(N, TupleList1, TupleList2) -> TupleList3
968
969              Types:
970
971                 N = integer() >= 1
972                   1..tuple_size(Tuple)
973                 TupleList1 = [T1]
974                 TupleList2 = [T2]
975                 TupleList3 = [T1 | T2]
976                 T1 = T2 = Tuple
977                 Tuple = tuple()
978
979              Returns  the  sorted  list  formed by merging TupleList1 and Tu‐
980              pleList2. The merge is performed on the Nth element of each  tu‐
981              ple.  Both  TupleList1 and TupleList2 must be key-sorted without
982              duplicates before evaluating this function. When two tuples com‐
983              pare equal, the tuple from TupleList1 is picked and the one from
984              TupleList2 is deleted.
985
986       ukeysort(N, TupleList1) -> TupleList2
987
988              Types:
989
990                 N = integer() >= 1
991                   1..tuple_size(Tuple)
992                 TupleList1 = TupleList2 = [Tuple]
993                 Tuple = tuple()
994
995              Returns a list containing the sorted elements of list TupleList1
996              where  all  except the first tuple of the tuples comparing equal
997              have been deleted. Sorting is performed on the  Nth  element  of
998              the tuples.
999
1000       umerge(ListOfLists) -> List1
1001
1002              Types:
1003
1004                 ListOfLists = [List]
1005                 List = List1 = [T]
1006                 T = term()
1007
1008              Returns  the  sorted  list formed by merging all the sublists of
1009              ListOfLists. All sublists must be sorted and contain  no  dupli‐
1010              cates before evaluating this function. When two elements compare
1011              equal, the element from the sublist with the lowest position  in
1012              ListOfLists is picked and the other is deleted.
1013
1014       umerge(List1, List2) -> List3
1015
1016              Types:
1017
1018                 List1 = [X]
1019                 List2 = [Y]
1020                 List3 = [X | Y]
1021                 X = Y = term()
1022
1023              Returns  the sorted list formed by merging List1 and List2. Both
1024              List1 and List2 must be sorted and contain no duplicates  before
1025              evaluating  this  function. When two elements compare equal, the
1026              element from List1 is picked and the one from List2 is deleted.
1027
1028       umerge(Fun, List1, List2) -> List3
1029
1030              Types:
1031
1032                 Fun = fun((A, B) -> boolean())
1033                 List1 = [A]
1034                 List2 = [B]
1035                 List3 = [A | B]
1036                 A = B = term()
1037
1038              Returns the sorted list formed by merging List1 and List2.  Both
1039              List1  and  List2 must be sorted according to the ordering func‐
1040              tion Fun and contain no duplicates before evaluating this  func‐
1041              tion.  Fun(A,  B)  is  to return true if A compares less than or
1042              equal to B in the ordering, otherwise false. When  two  elements
1043              compare equal, the element from List1 is picked and the one from
1044              List2 is deleted.
1045
1046       umerge3(List1, List2, List3) -> List4
1047
1048              Types:
1049
1050                 List1 = [X]
1051                 List2 = [Y]
1052                 List3 = [Z]
1053                 List4 = [X | Y | Z]
1054                 X = Y = Z = term()
1055
1056              Returns the sorted list formed  by  merging  List1,  List2,  and
1057              List3. All of List1, List2, and List3 must be sorted and contain
1058              no duplicates before evaluating this function. When two elements
1059              compare equal, the element from List1 is picked if there is such
1060              an element, otherwise the element from List2 is picked, and  the
1061              other is deleted.
1062
1063       unzip(List1) -> {List2, List3}
1064
1065              Types:
1066
1067                 List1 = [{A, B}]
1068                 List2 = [A]
1069                 List3 = [B]
1070                 A = B = term()
1071
1072              "Unzips"  a  list  of two-tuples into two lists, where the first
1073              list contains the first element of each tuple,  and  the  second
1074              list contains the second element of each tuple.
1075
1076       unzip3(List1) -> {List2, List3, List4}
1077
1078              Types:
1079
1080                 List1 = [{A, B, C}]
1081                 List2 = [A]
1082                 List3 = [B]
1083                 List4 = [C]
1084                 A = B = C = term()
1085
1086              "Unzips"  a  list  of  three-tuples  into three lists, where the
1087              first list contains the first element of each tuple, the  second
1088              list  contains  the  second element of each tuple, and the third
1089              list contains the third element of each tuple.
1090
1091       usort(List1) -> List2
1092
1093              Types:
1094
1095                 List1 = List2 = [T]
1096                 T = term()
1097
1098              Returns a list containing the sorted elements of List1 where all
1099              except  the  first  element of the elements comparing equal have
1100              been deleted.
1101
1102       usort(Fun, List1) -> List2
1103
1104              Types:
1105
1106                 Fun = fun((T, T) -> boolean())
1107                 List1 = List2 = [T]
1108                 T = term()
1109
1110              Returns a list containing the sorted elements of List1 where all
1111              except the first element of the elements comparing equal accord‐
1112              ing to the ordering function Fun have been deleted. Fun(A, B) is
1113              to  return true if A compares less than or equal to B in the or‐
1114              dering, otherwise false.
1115
1116       zip(List1, List2) -> List3
1117
1118              Types:
1119
1120                 List1 = [A]
1121                 List2 = [B]
1122                 List3 = [{A, B}]
1123                 A = B = term()
1124
1125              "Zips" two lists of equal length into one  list  of  two-tuples,
1126              where  the  first  element of each tuple is taken from the first
1127              list and the second element is taken from the corresponding ele‐
1128              ment in the second list.
1129
1130       zip3(List1, List2, List3) -> List4
1131
1132              Types:
1133
1134                 List1 = [A]
1135                 List2 = [B]
1136                 List3 = [C]
1137                 List4 = [{A, B, C}]
1138                 A = B = C = term()
1139
1140              "Zips"  three  lists  of equal length into one list of three-tu‐
1141              ples, where the first element of each tuple is  taken  from  the
1142              first  list,  the second element is taken from the corresponding
1143              element in the second list, and the third element is taken  from
1144              the corresponding element in the third list.
1145
1146       zipwith(Combine, List1, List2) -> List3
1147
1148              Types:
1149
1150                 Combine = fun((X, Y) -> T)
1151                 List1 = [X]
1152                 List2 = [Y]
1153                 List3 = [T]
1154                 X = Y = T = term()
1155
1156              Combines  the  elements  of  two  lists of equal length into one
1157              list. For each pair X, Y of list elements from  the  two  lists,
1158              the element in the result list is Combine(X, Y).
1159
1160              zipwith(fun(X,  Y)  -> {X,Y} end, List1, List2) is equivalent to
1161              zip(List1, List2).
1162
1163              Example:
1164
1165              > lists:zipwith(fun(X, Y) -> X+Y end, [1,2,3], [4,5,6]).
1166              [5,7,9]
1167
1168       zipwith3(Combine, List1, List2, List3) -> List4
1169
1170              Types:
1171
1172                 Combine = fun((X, Y, Z) -> T)
1173                 List1 = [X]
1174                 List2 = [Y]
1175                 List3 = [Z]
1176                 List4 = [T]
1177                 X = Y = Z = T = term()
1178
1179              Combines the elements of three lists of equal  length  into  one
1180              list.  For  each  triple X, Y, Z of list elements from the three
1181              lists, the element in the result list is Combine(X, Y, Z).
1182
1183              zipwith3(fun(X, Y, Z) -> {X,Y,Z} end, List1,  List2,  List3)  is
1184              equivalent to zip3(List1, List2, List3).
1185
1186              Examples:
1187
1188              > lists:zipwith3(fun(X, Y, Z) -> X+Y+Z end, [1,2,3], [4,5,6], [7,8,9]).
1189              [12,15,18]
1190              > lists:zipwith3(fun(X, Y, Z) -> [X,Y,Z] end, [a,b,c], [x,y,z], [1,2,3]).
1191              [[a,x,1],[b,y,2],[c,z,3]]
1192
1193       uniq(List1) -> List2
1194
1195              Types:
1196
1197                 List1 = List2 = [T]
1198                 T = term()
1199
1200              Returns  a list containing the elements of List1 with duplicated
1201              elements removed (preserving the order  of  the  elements).  The
1202              first occurrence of each element is kept.
1203
1204              Examples:
1205
1206              > lists:uniq([3,3,1,2,1,2,3]).
1207              [3,1,2]
1208              > lists:uniq([a, a, 1, b, 2, a, 3]).
1209              [a, 1, b, 2, 3]
1210
1211       uniq(Fun, List1) -> List2
1212
1213              Types:
1214
1215                 Fun = fun((T) -> any())
1216                 List1 = List2 = [T]
1217                 T = term()
1218
1219              Returns a list containing the elements of List1 without the ele‐
1220              ments for which Fun returned duplicate  values  (preserving  the
1221              order  of the elements). The first occurrence of each element is
1222              kept.
1223
1224              Examples:
1225
1226              > lists:uniq(fun({X, _}) -> X end, [{b, 2}, {a, 1}, {c, 3}, {a, 2}]).
1227              [{b, 2}, {a, 1}, {c, 3}]
1228
1229
1230
1231Ericsson AB                       stdlib 4.2                          lists(3)