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