erlang 中文手册——list

声明：本文章是对erlang手册的部分内容的中文翻译(有些地方没有完全按原文翻译)，版权归原作者所有……由于本人的英语水平有限（翻译此手册的目的之一就是提高英语水平^0^），所以翻译有误乃正常现象，如有发现请及时提醒，THX……

谨以此文献给初学erlang并且不喜欢看英文手册的朋友……

Lists

模块

       lists

模块摘要
       list相关的处理函数

描述

       这个模块主要包含了处理list的一些函数。
       除非有特殊的规定，所有的函数都假定list的第一个元素的位置为1。
       当T1==T2为真时表示T1和T2相等；当T1=:=T2为真时表示T1和T2匹配。
       任何作为参数的排序函数，都假定具有如下属性——当x,y,z作用于F时：
        if x F y and y F x then x = y (F is antisymmetric(非对称性?));%%(译者注：个人感觉这个antisymmetric（反对称）不妥，F不是要对称的吗？求解……)

          if x F y and y F z then x F z (F is transitive()传递性);

          x F y or y F x (F is total(完整性)).

         

         一个典型的排序函数就是=<。

导出函数

all(Pred, List) -> boolean()

      Types:
             Pred = fun((Elem :: T) -> boolean())
             List = [T]
            T = term()
当List中的所有元素作用于函数Pred时都返回true的话，此函数返回true，否则返回false.
例如：
>List=[1,2,3], Pred=fun(X)-> X>0 end,
>lists:all(Pred, List).
true
            
>List=[1,2,0], Pred=fun(X)-> X>0 end,
>lists:all(Pred, List).
false

any(Pred, List) -> boolean()

         Types:
                   Pred = fun((Elem :: T) -> boolean())
                   List = [T]
                   T = term()
当List中的所有元素作用于函数Pred时至少有一个返回true的话，此函数返回true，否则返回false.
例如：
>List=[1,2,3], Pred=fun(X)-> X>2 end,
>lists:any(Pred, List).
true
            
>List=[1,2,0], Pred=fun(X)-> X>3 end,
>lists:any(Pred, List).
false

append(ListOfLists) -> List1

Types:
ListOfLists = [List]
List = List1 = [T]
T = term()

返回由ListOfLists中的所有元素拼接成的列表(注：ListOfLists中的所有元素必须是list否则会出现异常).
例如:

> lists:append([[1, 2, 3], [a, b], [4, 5, 6]]).
[1,2,3,a,b,4,5,6]

> lists:append([[1,2,3, [2]], [a, b]]).
[1,2,3,[2],a,b]

>lists:append([1, [2,3]]).
** exception error: bad argument
     in operator  ++/2
        called as 1 ++ [2,3]
     in call from lists:append/1 (lists.erl, line 74)



append(List1, List2) -> List3

Types:
List1 = List2 = List3 = [T]
T = term()

返回由列表List1和列表List2的元素拼接成的列表List3,List1的元素排在前面（注:List1和List2必须是列表）。
例如：
> lists:append("abc", "def").
"abcdef"

lists:append(A, B) 等价于 A ++ B.


concat(Things) -> string()

Types:
Things = [Thing]
Thing = atom() | integer() | float() | string()

把列表Things中的文本性质的元素拼接成字符串，Things中的元素可以是：原子，整数，符点数和字符串(注：其实还可以是列表，但得到的结果可能不是你想要的)
例如：
> lists:concat([doc, '/', file, '.', 3]).
"doc/file.3"

delete(Elem, List1) -> List2

Types:
Elem = T
List1 = List2 = [T]
T = term()

返回删除List1中与Elem相匹配的第一个元素后的列表,没有相匹配的元素则返回List1的一份拷贝。


dropwhile(Pred, List1) -> List2

Types:
Pred = fun((Elem :: T) -> boolean())
List1 = List2 = [T]
T = term()

将List1中的元素依次作用于函数Pred,当Pred第一次返回false时，则返回丢弃前面所有使Pred为true的元素后的剩余元素组成的列表,如果没有一个元素使Pred返回false,则返回[]。


duplicate(N, Elem) -> List

Types:
N = integer() >= 0
Elem = T
List = [T]
T = term()
返回由N个Elem组成的列表,例如:

> lists:duplicate(5, xx).
[xx,xx,xx,xx,xx]


filter(Pred, List1) -> List2

Types:
Pred = fun((Elem :: T) -> boolean())
List1 = List2 = [T]
T = term()

返回List1中所有使Pred返回true的元素组成的列表


flatlength(DeepList) -> integer() >= 0

Types:
DeepList = [term() | DeepList]

返回将DeepList的列表元素，以及列表元素中的列表元素……展开后，所有元素拼接成的列表的长度,
也就是将DeepList扁平化(见flatten函数)后的长度。该函数等效于 length(flatten(DeepList)), 但更高效.
例如：
>lists:flatlength([1, [2,3], [4, [5, {6, 7}]]]).
6

flatmap(Fun, List1) -> List2

Types:
Fun = fun((A) -> [B])
List1 = [A]
List2 = [B]
A = B = term()

将List1的元素依次作用于Fun(注：Fun必须返回一个列表),并将Fun返回的每一个列表拼接成一个列表返回,
可见flatmap像下面这样定义一样：
flatmap(Fun, List1) ->
    append(map(Fun, List1)).

例如:

> lists:flatmap(fun(X)->[X,X] end, [a,b,c]).
[a,a,b,b,c,c]


flatten(DeepList) -> List

Types:
DeepList = [term() | DeepList]
List = [term()]

返回一个扁平版本的列表，
例如：
>lists:flatten([1, [2, [3]], [4, [5, [6, {[7]}]]]]).
[1,2,3,4,5,6,{[7]}]

flatten(DeepList, Tail) -> List

Types:
DeepList = [term() | DeepList]
Tail = List = [term()]

返回将DeepList扁平化后与Tail拼接成的列表，等效于
append(flatten(DeepList),Tail),Tail必须是列表.


foldl(Fun, Acc0, List) -> Acc1

Types:
Fun = fun((Elem :: T, AccIn) -> AccOut)
Acc0 = Acc1 = AccIn = AccOut = term()
List = [T]
T = term()

从左到右依次用List中的元素Elem作用于Fun(Elem, AccIn),第一次时AccIn为Acc0,以后依次为上一次调用Fun所产生的结果,返回最后一次调用Fun的结果,
如果列表为空，则返回Acc0.
例如:
> lists:foldl(fun(X, Sum) -> X + Sum end, 0, [1,2,3,4,5]).
15
> lists:foldl(fun(X, Prod) -> X * Prod end, 1, [1,2,3,4,5]).
120

foldr(Fun, Acc0, List) -> Acc1

Types:
Fun = fun((Elem :: T, AccIn) -> AccOut)
Acc0 = Acc1 = AccIn = AccOut = term()
List = [T]
T = term()

与 foldl/3相似,但作用顺序是从右到左.
例如:

> P = fun(A, AccIn) -> io:format("~p ", [A]), AccIn end.
#Fun<erl_eval.12.2225172>
> lists:foldl(P, void, [1,2,3]).
1 2 3 void
> lists:foldr(P, void, [1,2,3]).
3 2 1 void

foldl/3 是尾递归的,所以应比foldr/3优先选择。

foreach(Fun, List) -> ok

Types:
Fun = fun((Elem :: T) -> term())
List = [T]
T = term()

将List中的元素依次作用于Fun,并返回ok.


keydelete(Key, N, TupleList1) -> TupleList2

Types:
Key = term()
N = integer() >= 1
1..tuple_size(Tuple)
TupleList1 = TupleList2 = [Tuple]
Tuple = tuple()

返回将元组组成的列表TupleList1中第一个符合以下条件的元组删除后的列表：第N个元素与Key相等。


keyfind(Key, N, TupleList) -> Tuple | false

Types:
Key = term()
N = 1..tuple_size(Tuple)
TupleList = [Tuple]
Tuple = tuple()

返回元组组成的列表TupleList中第一个符合以下条件的元组：第N个元素与Key相等,没有这样的元组则返回false



keymap(Fun, N, TupleList1) -> TupleList2

Types:
Fun = fun((Term1 :: term()) -> Term2 :: term())
N = integer() >= 1
1..tuple_size(Tuple)
TupleList1 = TupleList2 = [Tuple]
Tuple = tuple()

返回一个元组列表，该列表的所有元组由TupleList1中的元组组成，并且每一个元组的第N个元素Elem都替换成了Fun(Elem),注：TupleList1中的所有元素必须是元组,并且N不能大于元素个数最少的元组的元素个数.
例如:

> Fun = fun(Atom) -> atom_to_list(Atom) end.
#Fun<erl_eval.6.10732646>
2> lists:keymap(Fun, 2, [{name,jane,22},{name,lizzie,20},{name,lydia,15}]).
[{name,"jane",22},{name,"lizzie",20},{name,"lydia",15}]

keymember(Key, N, TupleList) -> boolean()

Types:
Key = term()
N = 1..tuple_size(Tuple)
TupleList = [Tuple]
 Tuple = tuple()
检测元组列表TupleList中是否存在一个这样的元组:第N个元素与Key相等,有则返回true,否则返回false.



keymerge(N, TupleList1, TupleList2) -> TupleList3

Types:
N = integer() >= 1
1..tuple_size(Tuple)
TupleList1 = [T1]
TupleList2 = [T2]
TupleList3 = [(T1 | T2)]
T1 = T2 = Tuple
Tuple = tuple()

把两个元组列表合拼成一个列表，元素的顺序由元组的第N个元素决定，小的排在前面,相等则TupleList1的元组排前面.


keyreplace(Key, N, TupleList1, NewTuple) -> TupleList2

Types:
Key = term()
N = integer() >= 1
1..tuple_size(Tuple)
TupleList1 = TupleList2 = [Tuple]
NewTuple = Tuple
Tuple = tuple()

返回元组列表TupleList1的拷贝，并且将列表中第一个符合以下条件的元组替换成NewTuple:第N个元素与Key相等。


keysearch(Key, N, TupleList) -> {value, Tuple} | false

Types:
Key = term()
N = 1..tuple_size(Tuple)
TupleList = [Tuple]
Tuple = tuple()

查找元组列表TupleList中第一个符合以下条件的元组：第N个元素与Key相等,如果找到则返回
{value, Tuple}, 否则返回false,(建议用keyfind/3代替)


keysort(N, TupleList1) -> TupleList2

Types:
N = integer() >= 1
1..tuple_size(Tuple)
TupleList1 = TupleList2 = [Tuple]
Tuple = tuple()

返回一个有序元组列表，元组的顺序由元组的第N个元素决定，小的排在前面，排序是稳定的。


keystore(Key, N, TupleList1, NewTuple) -> TupleList2

Types:
Key = term()
N = integer() >= 1
1..tuple_size(Tuple)
TupleList1 = [Tuple]
TupleList2 = [Tuple, ...]
NewTuple = Tuple
Tuple = tuple()

返回TupleLists1的拷贝，并且将第一个符合以下条件的元组替换成NewTuple:第N个元素与Key相等，如果不存在
这样的元组，则将NewTuple拼接在TupleLists1的后面.


keytake(Key, N, TupleList1) -> {value, Tuple, TupleList2} | false

Types:
Key = term()
N = integer() >= 1
1..tuple_size(Tuple)
TupleList1 = TupleList2 = [tuple()]
Tuple = tuple()

如果TupleList1中存在一个符合以下条件的元组Tuple:第N个元素与Key相等，则返回
{value, Tuple, TupleList2},其中TupleList2为TupleList1去除第一个符合条件的元组Tuple后剩余的元组组成的列表,
如果不存在符合条件的元组则返回false.

last(List) -> Last

Types:
List = [T, ...]
Last = T
T = term()

返回List的最后一个元素，其中List不能为空.

map(Fun, List1) -> List2

Types:
Fun = fun((A) -> B)
List1 = [A]
List2 = [B]
A = B = term()

返回一个列表List2,列表的元素为List1中的每一个元素依次作用于Fun后的结果.


mapfoldl(Fun, Acc0, List1) -> {List2, Acc1}

Types:
Fun = fun((A, AccIn) -> {B, AccOut})
Acc0 = Acc1 = AccIn = AccOut = term()
List1 = [A]
List2 = [B]
A = B = term()

该函数类似于同时执行map/2和foldl/3，返回的结果{List2, Acc1}中的List2是由List1中的每一个元素作用于Fun后{B,AccOut}中的B组成的列表,
Acc1是最后一次作用于Fun后{B，AccOut}中的AccOut.例如：
> lists:mapfoldl(fun(X, Sum) -> {2*X, X+Sum} end,0, [1,2,3,4,5]).
{[2,4,6,8,10],15}

mapfoldr(Fun, Acc0, List1) -> {List2, Acc1}

Types:
Fun = fun((A, AccIn) -> {B, AccOut})
Acc0 = Acc1 = AccIn = AccOut = term()
List1 = [A]
List2 = [B]
A = B = term()
与mapfold相似,但作用于Fun的顺序相反，是从右到左。

max(List) -> Max

Types:
List = [T, ...]
Max = T
T = term()
返回List中第一个最大的元素

member(Elem, List) -> boolean()

Types:
Elem = term()
List = [term()]

如果List中至少有一个元素与Elem相匹配则返回true,否则false


merge(ListOfLists) -> List1

Types:
ListOfLists = [List]
List = List1 = [T]
T = term()
返回将ListOfLists的所有子列表合并后并排序的列表，ListOfLists的子列表必须是有序的（升序）


merge(List1, List2) -> List3

Types:
List1 = [X]
List2 = [Y]
List3 = [(X | Y)]
X = Y = term()
返回List1和List2合并后并排序的列表，List1和List2必须是升序的.

merge(Fun, List1, List2) -> List3

Types:
Fun = fun((A, B) -> boolean())
List1 = [A]
List2 = [B]
List3 = [(A | B)]
A = B = term()
与merge/2相似，但排序时用Fun作对比函数，当A=<B时Fun返回true,否则false.

merge3(List1, List2, List3) -> List4

Types:
List1 = [X]
List2 = [Y]
List3 = [Z]
List4 = [(X | Y | Z)]
X = Y = Z = term()

与merge/2相似，将三个列表合并后排序


min(List) -> Min

Types:
List = [T, ...]
Min = T
T = term()
返回List中第一个最小的元素,List不能为[].


nth(N, List) -> Elem

Types:
N = integer() >= 1
1..length(List)
List = [T, ...]
Elem = T
T = term()
返回List的第N个元素


nthtail(N, List) -> Tail

Types:
N = integer() >= 0
0..length(List)
List = [T, ...]
Tail = [T]
T = term()

返回去除List的前N个元素后剩余元素组成的列表，N不能大于List的长度.

partition(Pred, List) -> {Satisfying, NotSatisfying}

Types:
Pred = fun((Elem :: T) -> boolean())
List = Satisfying = NotSatisfying = [T]
T = term()

将List分成两个列表,其中第一个列表Satisfying由所有List中使Pred返回true的元素组成,其他元素组成列表NoSatisfying
Examples:

> lists:partition(fun(A) -> A rem 2 == 1 end, [1,2,3,4,5,6,7]).
{[1,3,5,7],[2,4,6]}
> lists:partition(fun(A) -> is_atom(A) end, [a,b,1,c,d,2,3,4,e]).
{[a,b,c,d,e],[1,2,3,4]}

prefix(List1, List2) -> boolean()

Types:
List1 = List2 = [T]
T = term()
如果List1中的所有N个元素依次与List2的前N个元素相等则返回true,否则false

reverse(List1) -> List2

Types:
List1 = List2 = [T]
T = term()
返回List1的反转列表.

reverse(List1, Tail) -> List2

Types:
List1 = Tail = List2 = [term()]

返回将List1反转后与Tail拼接的列表

example:

> lists:reverse([1, 2, 3, 4], [a, b, c]).
[4,3,2,1,a,b,c]


seq(From, To) -> Seq
seq(From, To, Incr) -> Seq

Types:
From = To = Incr = integer()
Seq = [integer()]

生成一系列从From到To以Incr为步长的整数,Incr默认为1
以下情况之一将导致失败而返回[]
If To<From+Incr and Incr>0, or if To>From-Incr and Incr<0, or if Incr==0 and From/=To.

所生成的系列使以下等式成立:

length(lists:seq(From, To)) == To-From+1
length(lists:seq(From, To, Incr)) == (To-From+Incr) div Incr

Examples:

> lists:seq(1, 10).
[1,2,3,4,5,6,7,8,9,10]
> lists:seq(1, 20, 3).
[1,4,7,10,13,16,19]
> lists:seq(1, 0, 1).
[]
> lists:seq(10, 6, 4).
[]
> lists:seq(1, 1, 0).
[1]

sort(List1) -> List2

Types:
List1 = List2 = [T]
T = term()
对List1进行排序

sort(Fun, List1) -> List2

Types:
Fun = fun((A :: T, B :: T) -> boolean())
List1 = List2 = [T]
T = term()
以Fun作为对比函数对List1进行排序，当A=<B时Fun应该返回true,否则false

split(N, List1) -> {List2, List3}

Types:
N = integer() >= 0
0..length(List1)
List1 = List2 = List3 = [T]
T = term()
将List1分成两个列表,其中第一个列表List2由前N个元素组成，List3由剩下的元素组成


splitwith(Pred, List) -> {List1, List2}

Types:
Pred = fun((T) -> boolean())
List = List1 = List2 = [T]
T = term()

将List分成两个列表，其中List1的元素由List的前N个依次作用于Pred均为true的元素组成,List2由剩下的元素组成

该函数类似于如下定义:
splitwith(Pred, List) ->
    {takewhile(Pred, List), dropwhile(Pred, List)}.

Examples:

> lists:splitwith(fun(A) -> A rem 2 == 1 end, [1,2,3,4,5,6,7]).
{[1],[2,3,4,5,6,7]}
> lists:splitwith(fun(A) -> is_atom(A) end, [a,b,1,c,d,2,3,4,e]).
{[a,b],[1,c,d,2,3,4,e]}


sublist(List1, Len) -> List2

Types:
List1 = List2 = [T]
Len = integer() >= 0
T = term()

返回List1的前Len个元素组成的列表，如果Len大于List1,则返回List1的拷贝。

sublist(List1, Start, Len) -> List2

Types:
List1 = List2 = [T]
Start = integer() >= 1
1..(length(List1)+1)
Len = integer() >= 0
T = term()
返回由List1的第Start个元素到第Len个元素组成的列表（包括第Start和第Len个）.Start不能大于length(List1)+1.
如果Len小于Start，则List2只包含第Start个元素

subtract(List1, List2) -> List3

Types:
List1 = List2 = List3 = [T]
T = term()

返回List1的拷贝，并依次用List2中的元素Elem对拷贝作如下操作:删除拷贝中与Elem相同的第一个元素.

例如：
> lists:subtract("123212", "212").
"312".

lists:subtract(A, B) 等效于 A -- B
警告：该函数效率比较低，不建议对长列表进行此操作。

suffix(List1, List2) -> boolean()

Types:
List1 = List2 = [T]
T = term(）
如果List1是List2的后缀则返回true,否则false.即如果对于List1的所有Ｎ个元素都依次与List2中的后Ｎ个元素相同则返回true,否则false
例如：
>lists:suffix([1, 2], [1,3,1,2]).
true
>lists:suffix([1,2],[1,3,2,1]).
false

sum(List) -> number()

Types:
List = [number()]
返回List中所有元素之和，List中的元素必须是数字。

takewhile(Pred, List1) -> List2

Types:
Pred = fun((Elem :: T) -> boolean())
List1 = List2 = [T]
T = term()

对List1中的元素依次作用于Pred,直到出现一个使Pred为false的元素为止，返回前面所有使Pred为true的元素组成的列表。


ukeymerge(N, TupleList1, TupleList2) -> TupleList3

Types:
N = integer() >= 1
1..tuple_size(Tuple)
TupleList1 = [T1]
TupleList2 = [T2]
TupleList3 = [(T1 | T2)]
T1 = T2 = Tuple
Tuple = tuple()

对两个有序元组列表进行合并并排序(以元组的第N个元素作比较)，列表必须是升序的并且同一列表中不能有相同的元素。如果两个列表间有相同的元素，则只选择第一个列表的那个元素

ukeysort(N, TupleList1) -> TupleList2

Types:
N = integer() >= 1
1..tuple_size(Tuple)
TupleList1 = TupleList2 = [Tuple]
Tuple = tuple()
对元组列表进行排序(以元组的第N个元素作比较),如果有多个元组的第N个元素相同，则只保留第一个元组。

umerge(ListOfLists) -> List1

Types:
ListOfLists = [List]
List = List1 = [T]
T = term()

合并并排序列表的子列表元素，如果子列表间有相同的元素，则只保留第一个子列表的元素，子列表必须是有序的(升序)，同一个子列表中不能有相同的元素


umerge(List1, List2) -> List3

Types:
List1 = [X]
List2 = [Y]
List3 = [(X | Y)]
X = Y = term()

合并并排序两个列表的元素，如果列表间有相同的元素，则只保留第一个列表的元素，列表必须是有序的(升序),同一个子列表中不能有相同的元素

umerge(Fun, List1, List2) -> List3

Types:
Fun = fun((A, B) -> boolean())
List1 = [A]
List2 = [B]
List3 = [(A | B)]
A = B = term()
与umerge/2相同，但所有的排序都要用Fun作比较函数



umerge3(List1, List2, List3) -> List4

Types:
List1 = [X]
List2 = [Y]
List3 = [Z]
List4 = [(X | Y | Z)]
X = Y = Z = term()
与umerge/2相似


unzip(List1) -> {List2, List3}

Types:
List1 = [{A, B}]
List2 = [A]
List3 = [B]
A = B = term()
将list1中的所有元组元素的第一个元素组成List2,第二个元素组成List3,list1中的元素必须是含有两个元素的元组。


unzip3(List1) -> {List2, List3, List4}

Types:
List1 = [{A, B, C}]
List2 = [A]
List3 = [B]
List4 = [C]
A = B = C = term()

与unzip/1相似，分成三个列表，List1中的元素必须是含有三个元素的元组。


usort(List1) -> List2

Types:
List1 = List2 = [T]
T = term()
对Lists1排序，当有相同的元素时，只保留第一个元素。


usort(Fun, List1) -> List2

Types:
Fun = fun((T, T) -> boolean())
List1 = List2 = [T]
T = term()
与usort/1相似，但以Fun作为比较函数。

zip(List1, List2) -> List3

Types:
List1 = [A]
List2 = [B]
List3 = [{A, B}]
A = B = term()
用List1,List2的元素组合成List3：依次将List1,List2同一位置的元素组合成{A,B}作为List3的元素，List1与List2的长度必须相同


zip3(List1, List2, List3) -> List4

Types:
List1 = [A]
List2 = [B]
List3 = [C]
List4 = [{A, B, C}]
A = B = C = term()

用List1,List2,List3的元素组合成List4：依次将List1,List2,List3同一位置的元素组合成{A,B,C}作为List4的元素，List1,List2和List3的长度必须相同


zipwith(Combine, List1, List2) -> List3

Types:
Combine = fun((X, Y) -> T)
List1 = [X]
List2 = [Y]
List3 = [T]
X = Y = T = term()

用List1,List2的元素组合成List3：依次将List1,List2同一位置的元素作用于Combine，结果作为List3的元素，List1与List2的长度必须相同
Example:

> lists:zipwith(fun(X, Y) -> X+Y end, [1,2,3], [4,5,6]).
[5,7,9]

zipwith3(Combine, List1, List2, List3) -> List4

Types:
Combine = fun((X, Y, Z) -> T)
List1 = [X]
List2 = [Y]
List3 = [Z]
List4 = [T]
X = Y = Z = T = term()

用List1,List2,List3的元素组合成List4：依次将List1,List2,List3同一位置的元素作用于Combine,结果作为List4的元素，List1,List2和List3的长度必须相同
Examples:

> lists:zipwith3(fun(X, Y, Z) -> X+Y+Z end, [1,2,3], [4,5,6], [7,8,9]).
[12,15,18]
> lists:zipwith3(fun(X, Y, Z) -> [X,Y,Z] end, [a,b,c], [x,y,z], [1,2,3]).
[[a,x,1],[b,y,2],[c,z,3]]