1Stdlib.List(3) OCaml library Stdlib.List(3)
2
3
4
6 Stdlib.List - no description
7
9 Module Stdlib.List
10
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.
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 List.init len f is [f 0; f 1; ...; f (len-1)] , evaluated left to
123 right.
124
125
126 Since 4.06.0
127
128
129 Raises Invalid_argument if len < 0.
130
131
132
133 val append : 'a list -> 'a list -> 'a list
134
135 Concatenate two lists. Same as the infix operator @ . Not tail-recur‐
136 sive (length of the first argument).
137
138
139
140 val rev_append : 'a list -> 'a list -> 'a list
141
142
143 List.rev_append l1 l2 reverses l1 and concatenates it to l2 . This is
144 equivalent to List.rev l1 @ l2 , but rev_append is tail-recursive and
145 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 An alias for concat .
161
162
163
164
165 Iterators
166 val iter : ('a -> unit) -> 'a list -> unit
167
168
169 List.iter f [a1; ...; an] applies function f in turn to a1; ...; an .
170 It is equivalent to begin f a1; f a2; ...; f an; () end .
171
172
173
174 val iteri : (int -> 'a -> unit) -> 'a list -> unit
175
176 Same as List.iter , but the function is applied to the index of the
177 element as first argument (counting from 0), and the element itself as
178 second argument.
179
180
181 Since 4.00.0
182
183
184
185 val map : ('a -> 'b) -> 'a list -> 'b list
186
187
188 List.map f [a1; ...; an] applies function f to a1, ..., an , and builds
189 the list [f a1; ...; f an] with the results returned by f . Not
190 tail-recursive.
191
192
193
194 val mapi : (int -> 'a -> 'b) -> 'a list -> 'b list
195
196 Same as List.map , but the function is applied to the index of the ele‐
197 ment as first argument (counting from 0), and the element itself as
198 second argument. Not tail-recursive.
199
200
201 Since 4.00.0
202
203
204
205 val rev_map : ('a -> 'b) -> 'a list -> 'b list
206
207
208 List.rev_map f l gives the same result as List.rev ( List.map f l) ,
209 but is tail-recursive and more efficient.
210
211
212
213 val filter_map : ('a -> 'b option) -> 'a list -> 'b list
214
215
216 filter_map f l applies f to every element of l , filters out the None
217 elements and returns the list of the arguments of the Some elements.
218
219
220 Since 4.08.0
221
222
223
224 val concat_map : ('a -> 'b list) -> 'a list -> 'b list
225
226
227 List.concat_map f l gives the same result as List.concat ( List.map f
228 l) . Tail-recursive.
229
230
231 Since 4.10.0
232
233
234
235 val fold_left_map : ('a -> 'b -> 'a * 'c) -> 'a -> 'b list -> 'a * 'c
236 list
237
238
239 fold_left_map is a combination of fold_left and map that threads an
240 accumulator through calls to f
241
242
243
244 Since 4.11.0
245
246
247
248 val fold_left : ('a -> 'b -> 'a) -> 'a -> 'b list -> 'a
249
250
251 List.fold_left f a [b1; ...; bn] is f (... (f (f a b1) b2) ...) bn .
252
253
254
255 val fold_right : ('a -> 'b -> 'b) -> 'a list -> 'b -> 'b
256
257
258 List.fold_right f [a1; ...; an] b is f a1 (f a2 (... (f an b) ...)) .
259 Not tail-recursive.
260
261
262
263
264 Iterators on two lists
265 val iter2 : ('a -> 'b -> unit) -> 'a list -> 'b list -> unit
266
267
268 List.iter2 f [a1; ...; an] [b1; ...; bn] calls in turn f a1 b1; ...; f
269 an bn .
270
271
272 Raises Invalid_argument if the two lists are determined to have differ‐
273 ent lengths.
274
275
276
277 val map2 : ('a -> 'b -> 'c) -> 'a list -> 'b list -> 'c list
278
279
280 List.map2 f [a1; ...; an] [b1; ...; bn] is [f a1 b1; ...; f an bn] .
281
282
283 Raises Invalid_argument if the two lists are determined to have differ‐
284 ent lengths. Not tail-recursive.
285
286
287
288 val rev_map2 : ('a -> 'b -> 'c) -> 'a list -> 'b list -> 'c list
289
290
291 List.rev_map2 f l1 l2 gives the same result as List.rev ( List.map2 f
292 l1 l2) , but is tail-recursive and more efficient.
293
294
295
296 val fold_left2 : ('a -> 'b -> 'c -> 'a) -> 'a -> 'b list -> 'c list ->
297 'a
298
299
300 List.fold_left2 f a [b1; ...; bn] [c1; ...; cn] is f (... (f (f a b1
301 c1) b2 c2) ...) bn cn .
302
303
304 Raises Invalid_argument if the two lists are determined to have differ‐
305 ent lengths.
306
307
308
309 val fold_right2 : ('a -> 'b -> 'c -> 'c) -> 'a list -> 'b list -> 'c ->
310 'c
311
312
313 List.fold_right2 f [a1; ...; an] [b1; ...; bn] c is f a1 b1 (f a2 b2
314 (... (f an bn c) ...)) .
315
316
317 Raises Invalid_argument if the two lists are determined to have differ‐
318 ent lengths. Not tail-recursive.
319
320
321
322
323 List scanning
324 val for_all : ('a -> bool) -> 'a list -> bool
325
326
327 for_all p [a1; ...; an] checks if all elements of the list satisfy the
328 predicate p . That is, it returns (p a1) && (p a2) && ... && (p an) for
329 a non-empty list and true if the list is empty.
330
331
332
333 val exists : ('a -> bool) -> 'a list -> bool
334
335
336 exists p [a1; ...; an] checks if at least one element of the list sat‐
337 isfies the predicate p . That is, it returns (p a1) || (p a2) || ... ||
338 (p an) for a non-empty list and false if the list is empty.
339
340
341
342 val for_all2 : ('a -> 'b -> bool) -> 'a list -> 'b list -> bool
343
344 Same as List.for_all , but for a two-argument predicate.
345
346
347 Raises Invalid_argument if the two lists are determined to have differ‐
348 ent lengths.
349
350
351
352 val exists2 : ('a -> 'b -> bool) -> 'a list -> 'b list -> bool
353
354 Same as List.exists , but for a two-argument predicate.
355
356
357 Raises Invalid_argument if the two lists are determined to have differ‐
358 ent lengths.
359
360
361
362 val mem : 'a -> 'a list -> bool
363
364
365 mem a l is true if and only if a is equal to an element of l .
366
367
368
369 val memq : 'a -> 'a list -> bool
370
371 Same as List.mem , but uses physical equality instead of structural
372 equality to compare list elements.
373
374
375
376
377 List searching
378 val find : ('a -> bool) -> 'a list -> 'a
379
380
381 find p l returns the first element of the list l that satisfies the
382 predicate p .
383
384
385 Raises Not_found if there is no value that satisfies p in the list l .
386
387
388
389 val find_opt : ('a -> bool) -> 'a list -> 'a option
390
391
392 find_opt p l returns the first element of the list l that satisfies the
393 predicate p , or None if there is no value that satisfies p in the list
394 l .
395
396
397 Since 4.05
398
399
400
401 val find_map : ('a -> 'b option) -> 'a list -> 'b option
402
403
404 find_map f l applies f to the elements of l in order, and returns the
405 first result of the form Some v , or None if none exist.
406
407
408 Since 4.10.0
409
410
411
412 val filter : ('a -> bool) -> 'a list -> 'a list
413
414
415 filter p l returns all the elements of the list l that satisfy the
416 predicate p . The order of the elements in the input list is pre‐
417 served.
418
419
420
421 val find_all : ('a -> bool) -> 'a list -> 'a list
422
423
424 find_all is another name for List.filter .
425
426
427
428 val filteri : (int -> 'a -> bool) -> 'a list -> 'a list
429
430 Same as List.filter , but the predicate is applied to the index of the
431 element as first argument (counting from 0), and the element itself as
432 second argument.
433
434
435 Since 4.11.0
436
437
438
439 val partition : ('a -> bool) -> 'a list -> 'a list * 'a list
440
441
442 partition p l returns a pair of lists (l1, l2) , where l1 is the list
443 of all the elements of l that satisfy the predicate p , and l2 is the
444 list of all the elements of l that do not satisfy p . The order of the
445 elements in the input list is preserved.
446
447
448
449
450 Association lists
451 val assoc : 'a -> ('a * 'b) list -> 'b
452
453
454 assoc a l returns the value associated with key a in the list of pairs
455 l . That is, assoc a [ ...; (a,b); ...] = b if (a,b) is the leftmost
456 binding of a in list l .
457
458
459 Raises Not_found if there is no value associated with a in the list l .
460
461
462
463 val assoc_opt : 'a -> ('a * 'b) list -> 'b option
464
465
466 assoc_opt a l returns the value associated with key a in the list of
467 pairs l . That is, assoc_opt a [ ...; (a,b); ...] = b if (a,b) is the
468 leftmost binding of a in list l . Returns None if there is no value
469 associated with a in the list l .
470
471
472 Since 4.05
473
474
475
476 val assq : 'a -> ('a * 'b) list -> 'b
477
478 Same as List.assoc , but uses physical equality instead of structural
479 equality to compare keys.
480
481
482
483 val assq_opt : 'a -> ('a * 'b) list -> 'b option
484
485 Same as List.assoc_opt , but uses physical equality instead of struc‐
486 tural equality to compare keys.
487
488
489 Since 4.05
490
491
492
493 val mem_assoc : 'a -> ('a * 'b) list -> bool
494
495 Same as List.assoc , but simply return true if a binding exists, and
496 false if no bindings exist for the given key.
497
498
499
500 val mem_assq : 'a -> ('a * 'b) list -> bool
501
502 Same as List.mem_assoc , but uses physical equality instead of struc‐
503 tural equality to compare keys.
504
505
506
507 val remove_assoc : 'a -> ('a * 'b) list -> ('a * 'b) list
508
509
510 remove_assoc a l returns the list of pairs l without the first pair
511 with key a , if any. Not tail-recursive.
512
513
514
515 val remove_assq : 'a -> ('a * 'b) list -> ('a * 'b) list
516
517 Same as List.remove_assoc , but uses physical equality instead of
518 structural equality to compare keys. Not tail-recursive.
519
520
521
522
523 Lists of pairs
524 val split : ('a * 'b) list -> 'a list * 'b list
525
526 Transform a list of pairs into a pair of lists: split [(a1,b1); ...;
527 (an,bn)] is ([a1; ...; an], [b1; ...; bn]) . Not tail-recursive.
528
529
530
531 val combine : 'a list -> 'b list -> ('a * 'b) list
532
533 Transform a pair of lists into a list of pairs: combine [a1; ...; an]
534 [b1; ...; bn] is [(a1,b1); ...; (an,bn)] .
535
536
537 Raises Invalid_argument if the two lists have different lengths. Not
538 tail-recursive.
539
540
541
542
543 Sorting
544 val sort : ('a -> 'a -> int) -> 'a list -> 'a list
545
546 Sort a list in increasing order according to a comparison function.
547 The comparison function must return 0 if its arguments compare as
548 equal, a positive integer if the first is greater, and a negative inte‐
549 ger if the first is smaller (see Array.sort for a complete specifica‐
550 tion). For example, compare is a suitable comparison function. The
551 resulting list is sorted in increasing order. List.sort is guaranteed
552 to run in constant heap space (in addition to the size of the result
553 list) and logarithmic stack space.
554
555 The current implementation uses Merge Sort. It runs in constant heap
556 space and logarithmic stack space.
557
558
559
560 val stable_sort : ('a -> 'a -> int) -> 'a list -> 'a list
561
562 Same as List.sort , but the sorting algorithm is guaranteed to be sta‐
563 ble (i.e. elements that compare equal are kept in their original order)
564 .
565
566 The current implementation uses Merge Sort. It runs in constant heap
567 space and logarithmic stack space.
568
569
570
571 val fast_sort : ('a -> 'a -> int) -> 'a list -> 'a list
572
573 Same as List.sort or List.stable_sort , whichever is faster on typical
574 input.
575
576
577
578 val sort_uniq : ('a -> 'a -> int) -> 'a list -> 'a list
579
580 Same as List.sort , but also remove duplicates.
581
582
583 Since 4.02.0
584
585
586
587 val merge : ('a -> 'a -> int) -> 'a list -> 'a list -> 'a list
588
589 Merge two lists: Assuming that l1 and l2 are sorted according to the
590 comparison function cmp , merge cmp l1 l2 will return a sorted list
591 containing all the elements of l1 and l2 . If several elements compare
592 equal, the elements of l1 will be before the elements of l2 . Not
593 tail-recursive (sum of the lengths of the arguments).
594
595
596
597
598 Iterators
599 val to_seq : 'a list -> 'a Seq.t
600
601 Iterate on the list
602
603
604 Since 4.07
605
606
607
608 val of_seq : 'a Seq.t -> 'a list
609
610 Create a list from the iterator
611
612
613 Since 4.07
614
615
616
617
618
619OCamldoc 2020-09-01 Stdlib.List(3)