1Stdlib.List(3) OCaml library Stdlib.List(3)
2
6 Stdlib.List - no description
7
9 Module Stdlib.List
10
12 Module List
13 : (module Stdlib__list)
14 type 'a t = 'a list =
22 | []
23 | :: of 'a * 'a list
24 An alias for the type of lists.
27 val length : 'a list -> int
31 Return the length (number of elements) of the given list.
33 val compare_lengths : 'a list -> 'b list -> int
37 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 Since 4.05.0
44 val compare_length_with : 'a list -> int -> int
48 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 Since 4.05.0
55 val cons : 'a -> 'a list -> 'a list
59 cons x xs is x :: xs
62 Since 4.03.0
66 val hd : 'a list -> 'a
70 Return the first element of the given list.
72 Raises Failure if the list is empty.
75 val tl : 'a list -> 'a list
79 Return the given list without its first element.
81 Raises Failure if the list is empty.
84 val nth : 'a list -> int -> 'a
88 Return the n -th element of the given list. The first element (head of
90 the list) is at position 0.
91 Raises Failure if the list is too short.
94 Raises Invalid_argument if n is negative.
97 val nth_opt : 'a list -> int -> 'a option
101 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 Since 4.05
107 Raises Invalid_argument if n is negative.
110 val rev : 'a list -> 'a list
114 List reversal.
116 val init : int -> (int -> 'a) -> 'a list
120 List.init len f is [f 0; f 1; ...; f (len-1)] , evaluated left to
123 right.
124 Since 4.06.0
127 Raises Invalid_argument if len < 0.
130 val append : 'a list -> 'a list -> 'a list
134 Concatenate two lists. Same as the infix operator @ . Not tail-recur‐
136 sive (length of the first argument).
137 val rev_append : 'a list -> 'a list -> 'a list
141 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 val concat : 'a list list -> 'a list
150 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 val flatten : 'a list list -> 'a list
159 An alias for concat .
161 Iterators
166 val iter : ('a -> unit) -> 'a list -> unit
167 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 val iteri : (int -> 'a -> unit) -> 'a list -> unit
175 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 Since 4.00.0
182 val map : ('a -> 'b) -> 'a list -> 'b list
186 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 val mapi : (int -> 'a -> 'b) -> 'a list -> 'b list
195 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 Since 4.00.0
202 val rev_map : ('a -> 'b) -> 'a list -> 'b list
206 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 val filter_map : ('a -> 'b option) -> 'a list -> 'b list
214 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 Since 4.08.0
221 val concat_map : ('a -> 'b list) -> 'a list -> 'b list
225 List.concat_map f l gives the same result as List.concat ( List.map f
228 l) . Tail-recursive.
229 Since 4.10.0
232 val fold_left_map : ('a -> 'b -> 'a * 'c) -> 'a -> 'b list -> 'a * 'c
236 list
237 fold_left_map is a combination of fold_left and map that threads an
240 accumulator through calls to f
241 Since 4.11.0
245 val fold_left : ('a -> 'b -> 'a) -> 'a -> 'b list -> 'a
249 List.fold_left f a [b1; ...; bn] is f (... (f (f a b1) b2) ...) bn .
252 val fold_right : ('a -> 'b -> 'b) -> 'a list -> 'b -> 'b
256 List.fold_right f [a1; ...; an] b is f a1 (f a2 (... (f an b) ...)) .
259 Not tail-recursive.
260 Iterators on two lists
265 val iter2 : ('a -> 'b -> unit) -> 'a list -> 'b list -> unit
266 List.iter2 f [a1; ...; an] [b1; ...; bn] calls in turn f a1 b1; ...; f
269 an bn .
270 Raises Invalid_argument if the two lists are determined to have differ‐
273 ent lengths.
274 val map2 : ('a -> 'b -> 'c) -> 'a list -> 'b list -> 'c list
278 List.map2 f [a1; ...; an] [b1; ...; bn] is [f a1 b1; ...; f an bn] .
281 Raises Invalid_argument if the two lists are determined to have differ‐
284 ent lengths. Not tail-recursive.
285 val rev_map2 : ('a -> 'b -> 'c) -> 'a list -> 'b list -> 'c list
289 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 val fold_left2 : ('a -> 'b -> 'c -> 'a) -> 'a -> 'b list -> 'c list ->
297 'a
298 List.fold_left2 f a [b1; ...; bn] [c1; ...; cn] is f (... (f (f a b1
301 c1) b2 c2) ...) bn cn .
302 Raises Invalid_argument if the two lists are determined to have differ‐
305 ent lengths.
306 val fold_right2 : ('a -> 'b -> 'c -> 'c) -> 'a list -> 'b list -> 'c ->
310 'c
311 List.fold_right2 f [a1; ...; an] [b1; ...; bn] c is f a1 b1 (f a2 b2
314 (... (f an bn c) ...)) .
315 Raises Invalid_argument if the two lists are determined to have differ‐
318 ent lengths. Not tail-recursive.
319 List scanning
324 val for_all : ('a -> bool) -> 'a list -> bool
325 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 val exists : ('a -> bool) -> 'a list -> bool
334 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 val for_all2 : ('a -> 'b -> bool) -> 'a list -> 'b list -> bool
343 Same as List.for_all , but for a two-argument predicate.
345 Raises Invalid_argument if the two lists are determined to have differ‐
348 ent lengths.
349 val exists2 : ('a -> 'b -> bool) -> 'a list -> 'b list -> bool
353 Same as List.exists , but for a two-argument predicate.
355 Raises Invalid_argument if the two lists are determined to have differ‐
358 ent lengths.
359 val mem : 'a -> 'a list -> bool
363 mem a l is true if and only if a is equal to an element of l .
366 val memq : 'a -> 'a list -> bool
370 Same as List.mem , but uses physical equality instead of structural
372 equality to compare list elements.
373 List searching
378 val find : ('a -> bool) -> 'a list -> 'a
379 find p l returns the first element of the list l that satisfies the
382 predicate p .
383 Raises Not_found if there is no value that satisfies p in the list l .
386 val find_opt : ('a -> bool) -> 'a list -> 'a option
390 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 Since 4.05
398 val find_map : ('a -> 'b option) -> 'a list -> 'b option
402 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 Since 4.10.0
409 val filter : ('a -> bool) -> 'a list -> 'a list
413 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 val find_all : ('a -> bool) -> 'a list -> 'a list
422 find_all is another name for List.filter .
425 val filteri : (int -> 'a -> bool) -> 'a list -> 'a list
429 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 Since 4.11.0
436 val partition : ('a -> bool) -> 'a list -> 'a list * 'a list
440 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 Association lists
451 val assoc : 'a -> ('a * 'b) list -> 'b
452 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 Raises Not_found if there is no value associated with a in the list l .
460 val assoc_opt : 'a -> ('a * 'b) list -> 'b option
464 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 Since 4.05
473 val assq : 'a -> ('a * 'b) list -> 'b
477 Same as List.assoc , but uses physical equality instead of structural
479 equality to compare keys.
480 val assq_opt : 'a -> ('a * 'b) list -> 'b option
484 Same as List.assoc_opt , but uses physical equality instead of struc‐
486 tural equality to compare keys.
487 Since 4.05
490 val mem_assoc : 'a -> ('a * 'b) list -> bool
494 Same as List.assoc , but simply return true if a binding exists, and
496 false if no bindings exist for the given key.
497 val mem_assq : 'a -> ('a * 'b) list -> bool
501 Same as List.mem_assoc , but uses physical equality instead of struc‐
503 tural equality to compare keys.
504 val remove_assoc : 'a -> ('a * 'b) list -> ('a * 'b) list
508 remove_assoc a l returns the list of pairs l without the first pair
511 with key a , if any. Not tail-recursive.
512 val remove_assq : 'a -> ('a * 'b) list -> ('a * 'b) list
516 Same as List.remove_assoc , but uses physical equality instead of
518 structural equality to compare keys. Not tail-recursive.
519 Lists of pairs
524 val split : ('a * 'b) list -> 'a list * 'b list
525 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 val combine : 'a list -> 'b list -> ('a * 'b) list
532 Transform a pair of lists into a list of pairs: combine [a1; ...; an]
534 [b1; ...; bn] is [(a1,b1); ...; (an,bn)] .
535 Raises Invalid_argument if the two lists have different lengths. Not
538 tail-recursive.
539 Sorting
544 val sort : ('a -> 'a -> int) -> 'a list -> 'a list
545 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 The current implementation uses Merge Sort. It runs in constant heap
556 space and logarithmic stack space.
557 val stable_sort : ('a -> 'a -> int) -> 'a list -> 'a list
561 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 The current implementation uses Merge Sort. It runs in constant heap
567 space and logarithmic stack space.
568 val fast_sort : ('a -> 'a -> int) -> 'a list -> 'a list
572 Same as List.sort or List.stable_sort , whichever is faster on typical
574 input.
575 val sort_uniq : ('a -> 'a -> int) -> 'a list -> 'a list
579 Same as List.sort , but also remove duplicates.
581 Since 4.02.0
584 val merge : ('a -> 'a -> int) -> 'a list -> 'a list -> 'a list
588 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 Iterators
599 val to_seq : 'a list -> 'a Seq.t
600 Iterate on the list
602 Since 4.07
605 val of_seq : 'a Seq.t -> 'a list
609 Create a list from the iterator
611 Since 4.07
614OCamldoc 2020-09-01 Stdlib.List(3)