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 reaching the end of 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 len
50       is equivalent to compare (length l) len , except that  the  computation
51       stops after at most len 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 (4.05.0 in ListLabels)
66
67
68
69       val hd : 'a list -> 'a
70
71       Return the first element of the given list.
72
73
74       Raises Failure if the list is empty.
75
76
77
78       val tl : 'a list -> 'a list
79
80       Return the given list without its first element.
81
82
83       Raises Failure if the list is empty.
84
85
86
87       val nth : 'a list -> int -> 'a
88
89       Return the n -th element of the given list.  The first element (head of
90       the list) is at position 0.
91
92
93       Raises Failure if the list is too short.
94
95
96       Raises Invalid_argument if n is negative.
97
98
99
100       val nth_opt : 'a list -> int -> 'a option
101
102       Return the n -th element of the given list.  The first element (head of
103       the list) is at position 0.  Return None if the list is too short.
104
105
106       Since 4.05
107
108
109       Raises Invalid_argument if n is negative.
110
111
112
113       val rev : 'a list -> 'a list
114
115       List reversal.
116
117
118
119       val init : int -> (int -> 'a) -> 'a list
120
121
122       init len f is f 0; f 1; ...; f (len-1) , evaluated left to right.
123
124
125       Since 4.06.0
126
127
128       Raises Invalid_argument if len < 0 .
129
130
131
132       val append : 'a list -> 'a list -> 'a list
133
134       Concatenate  two  lists.  Same  function as the infix operator @ .  Not
135       tail-recursive (length of the first argument). The @  operator  is  not
136       tail-recursive either.
137
138
139
140       val rev_append : 'a list -> 'a list -> 'a list
141
142
143       rev_append  l1  l2  reverses  l1 and concatenates it with l2 .  This is
144       equivalent to ( List.rev l1) @ l2 , but  rev_append  is  tail-recursive
145       and more efficient.
146
147
148
149       val concat : 'a list list -> 'a list
150
151       Concatenate  a list of lists. The elements of the argument are all con‐
152       catenated together (in  the  same  order)  to  give  the  result.   Not
153       tail-recursive  (length  of  the  argument  +  length  of  the  longest
154       sub-list).
155
156
157
158       val flatten : 'a list list -> 'a list
159
160       Same as List.concat . Not tail-recursive  (length  of  the  argument  +
161       length of the longest sub-list).
162
163
164
165
166   Comparison
167       val equal : ('a -> 'a -> bool) -> 'a list -> 'a list -> bool
168
169
170       equal eq [a1; ...; an] [b1; ..; bm] holds when the two input lists have
171       the same length, and for each pair of elements ai , bi at the same  po‐
172       sition we have eq ai bi .
173
174       Note:  the  eq  function may be called even if the lists have different
175       length. If you know your equality function is costly, you may  want  to
176       check List.compare_lengths first.
177
178
179       Since 4.12.0
180
181
182
183       val compare : ('a -> 'a -> int) -> 'a list -> 'a list -> int
184
185
186       compare  cmp  [a1; ...; an] [b1; ...; bm] performs a lexicographic com‐
187       parison of the two input lists, using the same 'a -> 'a ->  int  inter‐
188       face as compare :
189
190
191       -  a1 :: l1 is smaller than a2 :: l2 (negative result) if a1 is smaller
192       than a2 , or if they are equal (0 result) and l1 is smaller than l2
193
194
195       -the empty list [] is strictly smaller than non-empty lists
196
197       Note: the cmp function will be called even if the lists have  different
198       lengths.
199
200
201       Since 4.12.0
202
203
204
205
206   Iterators
207       val iter : ('a -> unit) -> 'a list -> unit
208
209
210       iter  f [a1; ...; an] applies function f in turn to a1; ...; an . It is
211       equivalent to begin f a1; f a2; ...; f an; () end .
212
213
214
215       val iteri : (int -> 'a -> unit) -> 'a list -> unit
216
217       Same as List.iter , but the function is applied to the index of the el‐
218       ement  as  first  argument (counting from 0), and the element itself as
219       second argument.
220
221
222       Since 4.00.0
223
224
225
226       val map : ('a -> 'b) -> 'a list -> 'b list
227
228
229       map f [a1; ...; an] applies function f to a1, ..., an , and builds  the
230       list [f a1; ...; f an] with the results returned by f . Not tail-recur‐
231       sive.
232
233
234
235       val mapi : (int -> 'a -> 'b) -> 'a list -> 'b list
236
237       Same as List.map , but the function is applied to the index of the ele‐
238       ment  as  first  argument  (counting from 0), and the element itself as
239       second argument. Not tail-recursive.
240
241
242       Since 4.00.0
243
244
245
246       val rev_map : ('a -> 'b) -> 'a list -> 'b list
247
248
249       rev_map f l gives the same result as List.rev ( List.map f l) , but  is
250       tail-recursive and more efficient.
251
252
253
254       val filter_map : ('a -> 'b option) -> 'a list -> 'b list
255
256
257       filter_map  f  l applies f to every element of l , filters out the None
258       elements and returns the list of the arguments of the Some elements.
259
260
261       Since 4.08.0
262
263
264
265       val concat_map : ('a -> 'b list) -> 'a list -> 'b list
266
267
268       concat_map f l gives the same result as List.concat ( List.map f  l)  .
269       Tail-recursive.
270
271
272       Since 4.10.0
273
274
275
276       val  fold_left_map  : ('a -> 'b -> 'a * 'c) -> 'a -> 'b list -> 'a * 'c
277       list
278
279
280       fold_left_map is  a combination of fold_left and map  that  threads  an
281       accumulator through calls to f .
282
283
284       Since 4.11.0
285
286
287
288       val fold_left : ('a -> 'b -> 'a) -> 'a -> 'b list -> 'a
289
290
291       fold_left f init [b1; ...; bn] is f (... (f (f init b1) b2) ...) bn .
292
293
294
295       val fold_right : ('a -> 'b -> 'b) -> 'a list -> 'b -> 'b
296
297
298       fold_right f [a1; ...; an] init is f a1 (f a2 (... (f an init) ...))  .
299       Not tail-recursive.
300
301
302
303
304   Iterators on two lists
305       val iter2 : ('a -> 'b -> unit) -> 'a list -> 'b list -> unit
306
307
308       iter2 f [a1; ...; an] [b1; ...; bn] calls in turn f a1 b1; ...; f an bn
309       .
310
311
312       Raises Invalid_argument if the two lists are determined to have differ‐
313       ent lengths.
314
315
316
317       val map2 : ('a -> 'b -> 'c) -> 'a list -> 'b list -> 'c list
318
319
320       map2 f [a1; ...; an] [b1; ...; bn] is [f a1 b1; ...; f an bn] .
321
322
323       Raises Invalid_argument if the two lists are determined to have differ‐
324       ent lengths. Not tail-recursive.
325
326
327
328       val rev_map2 : ('a -> 'b -> 'c) -> 'a list -> 'b list -> 'c list
329
330
331       rev_map2 f l1 l2 gives the same result as List.rev ( List.map2 f l1 l2)
332       , but is tail-recursive and more efficient.
333
334
335
336       val fold_left2 : ('a -> 'b -> 'c -> 'a) -> 'a -> 'b list -> 'c list  ->
337       'a
338
339
340       fold_left2  f  init [a1; ...; an] [b1; ...; bn] is f (... (f (f init a1
341       b1) a2 b2) ...) an bn .
342
343
344       Raises Invalid_argument if the two lists are determined to have differ‐
345       ent lengths.
346
347
348
349       val fold_right2 : ('a -> 'b -> 'c -> 'c) -> 'a list -> 'b list -> 'c ->
350       'c
351
352
353       fold_right2 f [a1; ...; an] [b1; ...; bn] init is f a1 b1 (f a2 b2 (...
354       (f an bn init) ...))  .
355
356
357       Raises Invalid_argument if the two lists are determined to have differ‐
358       ent lengths. Not tail-recursive.
359
360
361
362
363   List scanning
364       val for_all : ('a -> bool) -> 'a list -> bool
365
366
367       for_all f [a1; ...; an] checks if all elements of the list satisfy  the
368       predicate f . That is, it returns (f a1) && (f a2) && ... && (f an) for
369       a non-empty list and true if the list is empty.
370
371
372
373       val exists : ('a -> bool) -> 'a list -> bool
374
375
376       exists f [a1; ...; an] checks if at least one element of the list  sat‐
377       isfies the predicate f . That is, it returns (f a1) || (f a2) || ... ||
378       (f an) for a non-empty list and false if the list is empty.
379
380
381
382       val for_all2 : ('a -> 'b -> bool) -> 'a list -> 'b list -> bool
383
384       Same as List.for_all , but for a two-argument predicate.
385
386
387       Raises Invalid_argument if the two lists are determined to have differ‐
388       ent lengths.
389
390
391
392       val exists2 : ('a -> 'b -> bool) -> 'a list -> 'b list -> bool
393
394       Same as List.exists , but for a two-argument predicate.
395
396
397       Raises Invalid_argument if the two lists are determined to have differ‐
398       ent lengths.
399
400
401
402       val mem : 'a -> 'a list -> bool
403
404
405       mem a set is true if and only if a is equal to an element of set .
406
407
408
409       val memq : 'a -> 'a list -> bool
410
411       Same as List.mem , but uses physical  equality  instead  of  structural
412       equality to compare list elements.
413
414
415
416
417   List searching
418       val find : ('a -> bool) -> 'a list -> 'a
419
420
421       find  f  l  returns  the first element of the list l that satisfies the
422       predicate f .
423
424
425       Raises Not_found if there is no value that satisfies f in the list l .
426
427
428
429       val find_opt : ('a -> bool) -> 'a list -> 'a option
430
431
432       find f l returns the first element of the list  l  that  satisfies  the
433       predicate  f  .   Returns None if there is no value that satisfies f in
434       the list l .
435
436
437       Since 4.05
438
439
440
441       val find_map : ('a -> 'b option) -> 'a list -> 'b option
442
443
444       find_map f l applies f to the elements of l in order, and  returns  the
445       first result of the form Some v , or None if none exist.
446
447
448       Since 4.10.0
449
450
451
452       val filter : ('a -> bool) -> 'a list -> 'a list
453
454
455       filter  f  l  returns  all  the elements of the list l that satisfy the
456       predicate f . The order of the elements in the input list is preserved.
457
458
459
460       val find_all : ('a -> bool) -> 'a list -> 'a list
461
462
463       find_all is another name for List.filter .
464
465
466
467       val filteri : (int -> 'a -> bool) -> 'a list -> 'a list
468
469       Same as List.filter , but the predicate is applied to the index of  the
470       element  as first argument (counting from 0), and the element itself as
471       second argument.
472
473
474       Since 4.11.0
475
476
477
478       val partition : ('a -> bool) -> 'a list -> 'a list * 'a list
479
480
481       partition f l returns a pair of lists (l1, l2) , where l1 is  the  list
482       of  all  the elements of l that satisfy the predicate f , and l2 is the
483       list of all the elements of l that do not satisfy f .  The order of the
484       elements in the input list is preserved.
485
486
487
488       val  partition_map  : ('a -> ('b, 'c) Either.t) -> 'a list -> 'b list *
489       'c list
490
491
492       partition_map f l returns a pair of lists (l1, l2) such that, for  each
493       element x of the input list l :
494
495       -if f x is Left y1 , then y1 is in l1 , and
496
497       -if f x is Right y2 , then y2 is in l2 .
498
499       The  output elements are included in l1 and l2 in the same relative or‐
500       der as the corresponding input elements in l .
501
502       In particular, partition_map (fun x -> if f x then Left x else Right x)
503       l is equivalent to partition f l .
504
505
506       Since 4.12.0
507
508
509
510
511   Association lists
512       val assoc : 'a -> ('a * 'b) list -> 'b
513
514
515       assoc  a l returns the value associated with key a in the list of pairs
516       l . That is, assoc a [ ...; (a,b); ...] = b if (a,b)  is  the  leftmost
517       binding of a in list l .
518
519
520       Raises Not_found if there is no value associated with a in the list l .
521
522
523
524       val assoc_opt : 'a -> ('a * 'b) list -> 'b option
525
526
527       assoc_opt  a  l  returns the value associated with key a in the list of
528       pairs l . That is, assoc_opt a [ ...; (a,b); ...] = Some b if (a,b)  is
529       the  leftmost  binding  of  a  in list l .  Returns None if there is no
530       value associated with a in the list l .
531
532
533       Since 4.05
534
535
536
537       val assq : 'a -> ('a * 'b) list -> 'b
538
539       Same as List.assoc , but uses physical equality instead  of  structural
540       equality to compare keys.
541
542
543
544       val assq_opt : 'a -> ('a * 'b) list -> 'b option
545
546       Same  as  List.assoc_opt , but uses physical equality instead of struc‐
547       tural equality to compare keys.
548
549
550       Since 4.05.0
551
552
553
554       val mem_assoc : 'a -> ('a * 'b) list -> bool
555
556       Same as List.assoc , but simply return true if a  binding  exists,  and
557       false if no bindings exist for the given key.
558
559
560
561       val mem_assq : 'a -> ('a * 'b) list -> bool
562
563       Same  as  List.mem_assoc , but uses physical equality instead of struc‐
564       tural equality to compare keys.
565
566
567
568       val remove_assoc : 'a -> ('a * 'b) list -> ('a * 'b) list
569
570
571       remove_assoc a l returns the list of pairs l  without  the  first  pair
572       with key a , if any.  Not tail-recursive.
573
574
575
576       val remove_assq : 'a -> ('a * 'b) list -> ('a * 'b) list
577
578       Same  as  List.remove_assoc  ,  but  uses  physical equality instead of
579       structural equality to compare keys. Not tail-recursive.
580
581
582
583
584   Lists of pairs
585       val split : ('a * 'b) list -> 'a list * 'b list
586
587       Transform a list of pairs into a pair of lists:  split  [(a1,b1);  ...;
588       (an,bn)] is ([a1; ...; an], [b1; ...; bn]) .  Not tail-recursive.
589
590
591
592       val combine : 'a list -> 'b list -> ('a * 'b) list
593
594       Transform  a  pair of lists into a list of pairs: combine [a1; ...; an]
595       [b1; ...; bn] is [(a1,b1); ...; (an,bn)] .
596
597
598       Raises Invalid_argument if the two lists have  different  lengths.  Not
599       tail-recursive.
600
601
602
603
604   Sorting
605       val sort : ('a -> 'a -> int) -> 'a list -> 'a list
606
607       Sort a list in increasing order according to a comparison function. The
608       comparison function must return 0 if its arguments compare as equal,  a
609       positive integer if the first is greater, and a negative integer if the
610       first is smaller (see Array.sort for a complete specification). For ex‐
611       ample,  compare  is a suitable comparison function.  The resulting list
612       is sorted in increasing order.  List.sort is guaranteed to run in  con‐
613       stant heap space (in addition to the size of the result list) and loga‐
614       rithmic stack space.
615
616       The current implementation uses Merge Sort. It runs  in  constant  heap
617       space and logarithmic stack space.
618
619
620
621       val stable_sort : ('a -> 'a -> int) -> 'a list -> 'a list
622
623       Same  as List.sort , but the sorting algorithm is guaranteed to be sta‐
624       ble (i.e. elements that compare equal are kept in  their  original  or‐
625       der).
626
627       The  current  implementation  uses Merge Sort. It runs in constant heap
628       space and logarithmic stack space.
629
630
631
632       val fast_sort : ('a -> 'a -> int) -> 'a list -> 'a list
633
634       Same as List.sort or List.stable_sort , whichever is faster on  typical
635       input.
636
637
638
639       val sort_uniq : ('a -> 'a -> int) -> 'a list -> 'a list
640
641       Same as List.sort , but also remove duplicates.
642
643
644       Since 4.02.0 (4.03.0 in ListLabels)
645
646
647
648       val merge : ('a -> 'a -> int) -> 'a list -> 'a list -> 'a list
649
650       Merge  two  lists:  Assuming that l1 and l2 are sorted according to the
651       comparison function cmp , merge cmp l1 l2 will  return  a  sorted  list
652       containing all the elements of l1 and l2 .  If several elements compare
653       equal, the elements of l1 will be before the  elements  of  l2  .   Not
654       tail-recursive (sum of the lengths of the arguments).
655
656
657
658
659   Iterators
660       val to_seq : 'a list -> 'a Seq.t
661
662       Iterate on the list.
663
664
665       Since 4.07
666
667
668
669       val of_seq : 'a Seq.t -> 'a list
670
671       Create a list from the iterator.
672
673
674       Since 4.07
675
676
677
678
679
680OCamldoc                          2021-07-22                    Stdlib.List(3)
Impressum