1Stdlib.List(3)                   OCaml library                  Stdlib.List(3)
2
3
4

NAME

6       Stdlib.List - no description
7

Module

9       Module   Stdlib.List
10

Documentation

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