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

NAME

6       Stdlib.ListLabels - no description
7

Module

9       Module   Stdlib.ListLabels
10

Documentation

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