1StdLabels.List(3)                  OCamldoc                  StdLabels.List(3)
2
3
4

NAME

6       StdLabels.List - no description
7

Module

9       Module   StdLabels.List
10

Documentation

12       Module List
13        : (module ListLabels)
14
15
16
17
18
19
20
21
22       val length : 'a list -> int
23
24       Return the length (number of elements) of the given list.
25
26
27
28       val hd : 'a list -> 'a
29
30       Return  the  first  element  of the given list. Raise Failure hd if the
31       list is empty.
32
33
34
35       val compare_lengths : 'a list -> 'b list -> int
36
37       Compare the lengths of two lists.  compare_lengths l1 l2 is  equivalent
38       to  compare (length l1) (length l2) , except that the computation stops
39       after itering on the shortest list.
40
41
42       Since 4.05.0
43
44
45
46       val compare_length_with : 'a list -> len:int -> int
47
48       Compare the length of a list to an integer.  compare_length_with l n is
49       equivalent  to compare (length l) n , except that the computation stops
50       after at most n iterations on the list.
51
52
53       Since 4.05.0
54
55
56
57       val cons : 'a -> 'a list -> 'a list
58
59
60       cons x xs is x :: xs
61
62
63
64       Since 4.05.0
65
66
67
68       val tl : 'a list -> 'a list
69
70       Return the given list without its first element. Raise  Failure  tl  if
71       the list is empty.
72
73
74
75       val nth : 'a list -> int -> 'a
76
77       Return the n -th element of the given list.  The first element (head of
78       the list) is at position 0.  Raise Failure  nth  if  the  list  is  too
79       short.  Raise Invalid_argument List.nth if n is negative.
80
81
82
83       val nth_opt : 'a list -> int -> 'a option
84
85       Return the n -th element of the given list.  The first element (head of
86       the list) is at position 0.  Return None if  the  list  is  too  short.
87       Raise Invalid_argument List.nth if n is negative.
88
89
90       Since 4.05
91
92
93
94       val rev : 'a list -> 'a list
95
96       List reversal.
97
98
99
100       val append : 'a list -> 'a list -> 'a list
101
102       Catenate  two  lists.   Same  function  as  the infix operator @ .  Not
103       tail-recursive (length of the first argument).  The @ operator  is  not
104       tail-recursive either.
105
106
107
108       val rev_append : 'a list -> 'a list -> 'a list
109
110
111       List.rev_append  l1 l2 reverses l1 and concatenates it to l2 .  This is
112       equivalent to List.rev l1 @ l2 , but rev_append is  tail-recursive  and
113       more efficient.
114
115
116
117       val concat : 'a list list -> 'a list
118
119       Concatenate a list of lists.  The elements of the argument are all con‐
120       catenated together (in  the  same  order)  to  give  the  result.   Not
121       tail-recursive  (length  of  the  argument  +  length  of  the  longest
122       sub-list).
123
124
125
126       val flatten : 'a list list -> 'a list
127
128       Same as concat .  Not tail-recursive (length of the argument  +  length
129       of the longest sub-list).
130
131
132
133
134       === Iterators ===
135
136
137       val iter : f:('a -> unit) -> 'a list -> unit
138
139
140       List.iter  f  [a1; ...; an] applies function f in turn to a1; ...; an .
141       It is equivalent to begin f a1; f a2; ...; f an; () end .
142
143
144
145       val iteri : f:(int -> 'a -> unit) -> 'a list -> unit
146
147       Same as List.iter , but the function is applied to  the  index  of  the
148       element  as first argument (counting from 0), and the element itself as
149       second argument.
150
151
152       Since 4.00.0
153
154
155
156       val map : f:('a -> 'b) -> 'a list -> 'b list
157
158
159       List.map f [a1; ...; an] applies function f to a1, ..., an , and builds
160       the  list  [f  a1;  ...;  f  an]  with the results returned by f .  Not
161       tail-recursive.
162
163
164
165       val mapi : f:(int -> 'a -> 'b) -> 'a list -> 'b list
166
167       Same as List.map , but the function is applied to the index of the ele‐
168       ment  as  first  argument  (counting from 0), and the element itself as
169       second argument.
170
171
172       Since 4.00.0
173
174
175
176       val rev_map : f:('a -> 'b) -> 'a list -> 'b list
177
178
179       List.rev_map f l gives the same result as List.rev ( List.map  f  l)  ,
180       but is tail-recursive and more efficient.
181
182
183
184       val fold_left : f:('a -> 'b -> 'a) -> init:'a -> 'b list -> 'a
185
186
187       List.fold_left f a [b1; ...; bn] is f (... (f (f a b1) b2) ...) bn .
188
189
190
191       val fold_right : f:('a -> 'b -> 'b) -> 'a list -> init:'b -> 'b
192
193
194       List.fold_right  f [a1; ...; an] b is f a1 (f a2 (... (f an b) ...))  .
195       Not tail-recursive.
196
197
198
199
200       === Iterators on two lists ===
201
202
203       val iter2 : f:('a -> 'b -> unit) -> 'a list -> 'b list -> unit
204
205
206       List.iter2 f [a1; ...; an] [b1; ...; bn] calls in turn f a1 b1; ...;  f
207       an bn .  Raise Invalid_argument if the two lists are determined to have
208       different lengths.
209
210
211
212       val map2 : f:('a -> 'b -> 'c) -> 'a list -> 'b list -> 'c list
213
214
215       List.map2 f [a1; ...; an] [b1; ...; bn] is [f a1 b1; ...; f  an  bn]  .
216       Raise  Invalid_argument if the two lists are determined to have differ‐
217       ent lengths.  Not tail-recursive.
218
219
220
221       val rev_map2 : f:('a -> 'b -> 'c) -> 'a list -> 'b list -> 'c list
222
223
224       List.rev_map2 f l1 l2 gives the same result as List.rev (  List.map2  f
225       l1 l2) , but is tail-recursive and more efficient.
226
227
228
229       val  fold_left2  : f:('a -> 'b -> 'c -> 'a) -> init:'a -> 'b list -> 'c
230       list -> 'a
231
232
233       List.fold_left2 f a [b1; ...; bn] [c1; ...; cn] is f (... (f  (f  a  b1
234       c1)  b2  c2)  ...) bn cn .  Raise Invalid_argument if the two lists are
235       determined to have different lengths.
236
237
238
239       val fold_right2 : f:('a -> 'b -> 'c -> 'c) -> 'a list  ->  'b  list  ->
240       init:'c -> 'c
241
242
243       List.fold_right2  f  [a1;  ...; an] [b1; ...; bn] c is f a1 b1 (f a2 b2
244       (... (f an bn c) ...))  .  Raise Invalid_argument if the two lists  are
245       determined to have different lengths.  Not tail-recursive.
246
247
248
249
250       === List scanning ===
251
252
253       val for_all : f:('a -> bool) -> 'a list -> bool
254
255
256       for_all  p [a1; ...; an] checks if all elements of the list satisfy the
257       predicate p . That is, it returns (p a1) && (p a2) && ... && (p an) .
258
259
260
261       val exists : f:('a -> bool) -> 'a list -> bool
262
263
264       exists p [a1; ...; an] checks if at least one element of the list  sat‐
265       isfies the predicate p . That is, it returns (p a1) || (p a2) || ... ||
266       (p an) .
267
268
269
270       val for_all2 : f:('a -> 'b -> bool) -> 'a list -> 'b list -> bool
271
272       Same as  List.for_all  ,  but  for  a  two-argument  predicate.   Raise
273       Invalid_argument  if  the  two  lists  are determined to have different
274       lengths.
275
276
277
278       val exists2 : f:('a -> 'b -> bool) -> 'a list -> 'b list -> bool
279
280       Same  as  List.exists  ,  but  for  a  two-argument  predicate.   Raise
281       Invalid_argument  if  the  two  lists  are determined to have different
282       lengths.
283
284
285
286       val mem : 'a -> set:'a list -> bool
287
288
289       mem a l is true if and only if a is equal to an element of l .
290
291
292
293       val memq : 'a -> set:'a list -> bool
294
295       Same as List.mem , but uses physical  equality  instead  of  structural
296       equality to compare list elements.
297
298
299
300
301       === List searching ===
302
303
304       val find : f:('a -> bool) -> 'a list -> 'a
305
306
307       find  p  l  returns  the first element of the list l that satisfies the
308       predicate p .  Raise Not_found if there is no value that satisfies p in
309       the list l .
310
311
312
313       val find_opt : f:('a -> bool) -> 'a list -> 'a option
314
315
316       find  p  l  returns  the first element of the list l that satisfies the
317       predicate p .  Returns None if there is no value that  satisfies  p  in
318       the list l .
319
320
321       Since 4.05
322
323
324
325       val filter : f:('a -> bool) -> 'a list -> 'a list
326
327
328       filter  p  l  returns  all  the elements of the list l that satisfy the
329       predicate p .  The order of the elements in  the  input  list  is  pre‐
330       served.
331
332
333
334       val find_all : f:('a -> bool) -> 'a list -> 'a list
335
336
337       find_all is another name for List.filter .
338
339
340
341       val partition : f:('a -> bool) -> 'a list -> 'a list * 'a list
342
343
344       partition  p  l returns a pair of lists (l1, l2) , where l1 is the list
345       of all the elements of l that satisfy the predicate p , and l2  is  the
346       list of all the elements of l that do not satisfy p .  The order of the
347       elements in the input list is preserved.
348
349
350
351
352       === Association lists ===
353
354
355       val assoc : 'a -> ('a * 'b) list -> 'b
356
357
358       assoc a l returns the value associated with key a in the list of  pairs
359       l  .  That  is, assoc a [ ...; (a,b); ...] = b if (a,b) is the leftmost
360       binding of a in list l .  Raise Not_found if there is no value  associ‐
361       ated with a in the list l .
362
363
364
365       val assoc_opt : 'a -> ('a * 'b) list -> 'b option
366
367
368       assoc_opt  a  l  returns the value associated with key a in the list of
369       pairs l . That is, assoc a [ ...; (a,b); ...] = b if (a,b) is the left‐
370       most  binding of a in list l .  Returns None if there is no value asso‐
371       ciated with a in the list l .
372
373
374       Since 4.05
375
376
377
378       val assq : 'a -> ('a * 'b) list -> 'b
379
380       Same as List.assoc , but uses physical equality instead  of  structural
381       equality to compare keys.
382
383
384
385       val assq_opt : 'a -> ('a * 'b) list -> 'b option
386
387       Same  as  List.assoc_opt , but uses physical equality instead of struc‐
388       tural equality to compare keys.
389
390
391       Since 4.05.0
392
393
394
395       val mem_assoc : 'a -> map:('a * 'b) list -> bool
396
397       Same as List.assoc , but simply return true if a  binding  exists,  and
398       false if no bindings exist for the given key.
399
400
401
402       val mem_assq : 'a -> map:('a * 'b) list -> bool
403
404       Same  as  List.mem_assoc , but uses physical equality instead of struc‐
405       tural equality to compare keys.
406
407
408
409       val remove_assoc : 'a -> ('a * 'b) list -> ('a * 'b) list
410
411
412       remove_assoc a l returns the list of pairs l  without  the  first  pair
413       with key a , if any.  Not tail-recursive.
414
415
416
417       val remove_assq : 'a -> ('a * 'b) list -> ('a * 'b) list
418
419       Same  as  List.remove_assoc  ,  but  uses  physical equality instead of
420       structural equality to compare keys.  Not tail-recursive.
421
422
423
424
425       === Lists of pairs ===
426
427
428       val split : ('a * 'b) list -> 'a list * 'b list
429
430       Transform a list of pairs into a pair of lists:  split  [(a1,b1);  ...;
431       (an,bn)] is ([a1; ...; an], [b1; ...; bn]) .  Not tail-recursive.
432
433
434
435       val combine : 'a list -> 'b list -> ('a * 'b) list
436
437       Transform  a  pair of lists into a list of pairs: combine [a1; ...; an]
438       [b1; ...; bn] is [(a1,b1); ...; (an,bn)] .  Raise  Invalid_argument  if
439       the two lists have different lengths.  Not tail-recursive.
440
441
442
443
444       === Sorting ===
445
446
447       val sort : cmp:('a -> 'a -> int) -> 'a list -> 'a list
448
449       Sort  a  list  in  increasing order according to a comparison function.
450       The comparison function must return  0  if  its  arguments  compare  as
451       equal, a positive integer if the first is greater, and a negative inte‐
452       ger if the first is smaller (see Array.sort for a  complete  specifica‐
453       tion).   For example, Pervasives.compare is a suitable comparison func‐
454       tion.  The resulting list is sorted in increasing order.  List.sort  is
455       guaranteed  to  run  in constant heap space (in addition to the size of
456       the result list) and logarithmic stack space.
457
458       The current implementation uses Merge Sort. It runs  in  constant  heap
459       space and logarithmic stack space.
460
461
462
463       val stable_sort : cmp:('a -> 'a -> int) -> 'a list -> 'a list
464
465       Same  as List.sort , but the sorting algorithm is guaranteed to be sta‐
466       ble (i.e. elements that compare equal are kept in their original order)
467       .
468
469       The  current  implementation  uses Merge Sort. It runs in constant heap
470       space and logarithmic stack space.
471
472
473
474       val fast_sort : cmp:('a -> 'a -> int) -> 'a list -> 'a list
475
476       Same as List.sort or List.stable_sort , whichever is faster on  typical
477       input.
478
479
480
481       val sort_uniq : cmp:('a -> 'a -> int) -> 'a list -> 'a list
482
483       Same as List.sort , but also remove duplicates.
484
485
486       Since 4.03.0
487
488
489
490       val merge : cmp:('a -> 'a -> int) -> 'a list -> 'a list -> 'a list
491
492       Merge  two  lists:  Assuming that l1 and l2 are sorted according to the
493       comparison function cmp , merge cmp l1 l2 will  return  a  sorted  list
494       containting  all  the elements of l1 and l2 .  If several elements com‐
495       pare equal, the elements of l1 will be before the elements of l2 .  Not
496       tail-recursive (sum of the lengths of the arguments).
497
498
499
500
501
5022018-04-14                          source:                  StdLabels.List(3)