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. Raise Failure "hd" if the
72 list is empty.
73 val tl : 'a list -> 'a list
77 Return the given list without its first element. Raise Failure "tl" if
79 the list is empty.
80 val nth : 'a list -> int -> 'a
84 Return the n -th element of the given list. The first element (head of
86 the list) is at position 0. Raise Failure "nth" if the list is too
87 short. Raise Invalid_argument "List.nth" if n is negative.
88 val nth_opt : 'a list -> int -> 'a option
92 Return the n -th element of the given list. The first element (head of
94 the list) is at position 0. Return None if the list is too short.
95 Raise Invalid_argument "List.nth" if n is negative.
96 Since 4.05
99 val rev : 'a list -> 'a list
103 List reversal.
105 val init : int -> (int -> 'a) -> 'a list
109 List.init len f is [f 0; f 1; ...; f (len-1)] , evaluated left to
112 right.
113 Since 4.06.0
116 Raises Invalid_argument if len < 0.
119 val append : 'a list -> 'a list -> 'a list
123 Concatenate two lists. Same as the infix operator @ . Not tail-recur‐
125 sive (length of the first argument).
126 val rev_append : 'a list -> 'a list -> 'a list
130 List.rev_append l1 l2 reverses l1 and concatenates it to l2 . This is
133 equivalent to List.rev l1 @ l2 , but rev_append is tail-recursive and
134 more efficient.
135 val concat : 'a list list -> 'a list
139 Concatenate a list of lists. The elements of the argument are all con‐
141 catenated together (in the same order) to give the result. Not
142 tail-recursive (length of the argument + length of the longest
143 sub-list).
144 val flatten : 'a list list -> 'a list
148 An alias for concat .
150 Iterators
155 val iter : ('a -> unit) -> 'a list -> unit
156 List.iter f [a1; ...; an] applies function f in turn to a1; ...; an .
159 It is equivalent to begin f a1; f a2; ...; f an; () end .
160 val iteri : (int -> 'a -> unit) -> 'a list -> unit
164 Same as List.iter , but the function is applied to the index of the
166 element as first argument (counting from 0), and the element itself as
167 second argument.
168 Since 4.00.0
171 val map : ('a -> 'b) -> 'a list -> 'b list
175 List.map f [a1; ...; an] applies function f to a1, ..., an , and builds
178 the list [f a1; ...; f an] with the results returned by f . Not
179 tail-recursive.
180 val mapi : (int -> 'a -> 'b) -> 'a list -> 'b list
184 Same as List.map , but the function is applied to the index of the ele‐
186 ment as first argument (counting from 0), and the element itself as
187 second argument. Not tail-recursive.
188 Since 4.00.0
191 val rev_map : ('a -> 'b) -> 'a list -> 'b list
195 List.rev_map f l gives the same result as List.rev ( List.map f l) ,
198 but is tail-recursive and more efficient.
199 val filter_map : ('a -> 'b option) -> 'a list -> 'b list
203 filter_map f l applies f to every element of l , filters out the None
206 elements and returns the list of the arguments of the Some elements.
207 Since 4.08.0
210 val concat_map : ('a -> 'b list) -> 'a list -> 'b list
214 List.concat_map f l gives the same result as List.concat ( List.map f
217 l) . Tail-recursive.
218 Since 4.10.0
221 val fold_left : ('a -> 'b -> 'a) -> 'a -> 'b list -> 'a
225 List.fold_left f a [b1; ...; bn] is f (... (f (f a b1) b2) ...) bn .
228 val fold_right : ('a -> 'b -> 'b) -> 'a list -> 'b -> 'b
232 List.fold_right f [a1; ...; an] b is f a1 (f a2 (... (f an b) ...)) .
235 Not tail-recursive.
236 Iterators on two lists
241 val iter2 : ('a -> 'b -> unit) -> 'a list -> 'b list -> unit
242 List.iter2 f [a1; ...; an] [b1; ...; bn] calls in turn f a1 b1; ...; f
245 an bn . Raise Invalid_argument if the two lists are determined to have
246 different lengths.
247 val map2 : ('a -> 'b -> 'c) -> 'a list -> 'b list -> 'c list
251 List.map2 f [a1; ...; an] [b1; ...; bn] is [f a1 b1; ...; f an bn] .
254 Raise Invalid_argument if the two lists are determined to have differ‐
255 ent lengths. Not tail-recursive.
256 val rev_map2 : ('a -> 'b -> 'c) -> 'a list -> 'b list -> 'c list
260 List.rev_map2 f l1 l2 gives the same result as List.rev ( List.map2 f
263 l1 l2) , but is tail-recursive and more efficient.
264 val fold_left2 : ('a -> 'b -> 'c -> 'a) -> 'a -> 'b list -> 'c list ->
268 'a
269 List.fold_left2 f a [b1; ...; bn] [c1; ...; cn] is f (... (f (f a b1
272 c1) b2 c2) ...) bn cn . Raise Invalid_argument if the two lists are
273 determined to have different lengths.
274 val fold_right2 : ('a -> 'b -> 'c -> 'c) -> 'a list -> 'b list -> 'c ->
278 'c
279 List.fold_right2 f [a1; ...; an] [b1; ...; bn] c is f a1 b1 (f a2 b2
282 (... (f an bn c) ...)) . Raise Invalid_argument if the two lists are
283 determined to have different lengths. Not tail-recursive.
284 List scanning
289 val for_all : ('a -> bool) -> 'a list -> bool
290 for_all p [a1; ...; an] checks if all elements of the list satisfy the
293 predicate p . That is, it returns (p a1) && (p a2) && ... && (p an) .
294 val exists : ('a -> bool) -> 'a list -> bool
298 exists p [a1; ...; an] checks if at least one element of the list sat‐
301 isfies the predicate p . That is, it returns (p a1) || (p a2) || ... ||
302 (p an) .
303 val for_all2 : ('a -> 'b -> bool) -> 'a list -> 'b list -> bool
307 Same as List.for_all , but for a two-argument predicate. Raise
309 Invalid_argument if the two lists are determined to have different
310 lengths.
311 val exists2 : ('a -> 'b -> bool) -> 'a list -> 'b list -> bool
315 Same as List.exists , but for a two-argument predicate. Raise
317 Invalid_argument if the two lists are determined to have different
318 lengths.
319 val mem : 'a -> 'a list -> bool
323 mem a l is true if and only if a is equal to an element of l .
326 val memq : 'a -> 'a list -> bool
330 Same as List.mem , but uses physical equality instead of structural
332 equality to compare list elements.
333 List searching
338 val find : ('a -> bool) -> 'a list -> 'a
339 find p l returns the first element of the list l that satisfies the
342 predicate p . Raise Not_found if there is no value that satisfies p in
343 the list l .
344 val find_opt : ('a -> bool) -> 'a list -> 'a option
348 find_opt p l returns the first element of the list l that satisfies the
351 predicate p , or None if there is no value that satisfies p in the list
352 l .
353 Since 4.05
356 val find_map : ('a -> 'b option) -> 'a list -> 'b option
360 find_map f l applies f to the elements of l in order, and returns the
363 first result of the form Some v , or None if none exist.
364 Since 4.10.0
367 val filter : ('a -> bool) -> 'a list -> 'a list
371 filter p l returns all the elements of the list l that satisfy the
374 predicate p . The order of the elements in the input list is pre‐
375 served.
376 val find_all : ('a -> bool) -> 'a list -> 'a list
380 find_all is another name for List.filter .
383 val partition : ('a -> bool) -> 'a list -> 'a list * 'a list
387 partition p l returns a pair of lists (l1, l2) , where l1 is the list
390 of all the elements of l that satisfy the predicate p , and l2 is the
391 list of all the elements of l that do not satisfy p . The order of the
392 elements in the input list is preserved.
393 Association lists
398 val assoc : 'a -> ('a * 'b) list -> 'b
399 assoc a l returns the value associated with key a in the list of pairs
402 l . That is, assoc a [ ...; (a,b); ...] = b if (a,b) is the leftmost
403 binding of a in list l . Raise Not_found if there is no value associ‐
404 ated with a in the list l .
405 val assoc_opt : 'a -> ('a * 'b) list -> 'b option
409 assoc_opt a l returns the value associated with key a in the list of
412 pairs l . That is, assoc_opt a [ ...; (a,b); ...] = b if (a,b) is the
413 leftmost binding of a in list l . Returns None if there is no value
414 associated with a in the list l .
415 Since 4.05
418 val assq : 'a -> ('a * 'b) list -> 'b
422 Same as List.assoc , but uses physical equality instead of structural
424 equality to compare keys.
425 val assq_opt : 'a -> ('a * 'b) list -> 'b option
429 Same as List.assoc_opt , but uses physical equality instead of struc‐
431 tural equality to compare keys.
432 Since 4.05
435 val mem_assoc : 'a -> ('a * 'b) list -> bool
439 Same as List.assoc , but simply return true if a binding exists, and
441 false if no bindings exist for the given key.
442 val mem_assq : 'a -> ('a * 'b) list -> bool
446 Same as List.mem_assoc , but uses physical equality instead of struc‐
448 tural equality to compare keys.
449 val remove_assoc : 'a -> ('a * 'b) list -> ('a * 'b) list
453 remove_assoc a l returns the list of pairs l without the first pair
456 with key a , if any. Not tail-recursive.
457 val remove_assq : 'a -> ('a * 'b) list -> ('a * 'b) list
461 Same as List.remove_assoc , but uses physical equality instead of
463 structural equality to compare keys. Not tail-recursive.
464 Lists of pairs
469 val split : ('a * 'b) list -> 'a list * 'b list
470 Transform a list of pairs into a pair of lists: split [(a1,b1); ...;
472 (an,bn)] is ([a1; ...; an], [b1; ...; bn]) . Not tail-recursive.
473 val combine : 'a list -> 'b list -> ('a * 'b) list
477 Transform a pair of lists into a list of pairs: combine [a1; ...; an]
479 [b1; ...; bn] is [(a1,b1); ...; (an,bn)] . Raise Invalid_argument if
480 the two lists have different lengths. Not tail-recursive.
481 Sorting
486 val sort : ('a -> 'a -> int) -> 'a list -> 'a list
487 Sort a list in increasing order according to a comparison function.
489 The comparison function must return 0 if its arguments compare as
490 equal, a positive integer if the first is greater, and a negative inte‐
491 ger if the first is smaller (see Array.sort for a complete specifica‐
492 tion). For example, compare is a suitable comparison function. The
493 resulting list is sorted in increasing order. List.sort is guaranteed
494 to run in constant heap space (in addition to the size of the result
495 list) and logarithmic stack space.
496 The current implementation uses Merge Sort. It runs in constant heap
498 space and logarithmic stack space.
499 val stable_sort : ('a -> 'a -> int) -> 'a list -> 'a list
503 Same as List.sort , but the sorting algorithm is guaranteed to be sta‐
505 ble (i.e. elements that compare equal are kept in their original order)
506 .
507 The current implementation uses Merge Sort. It runs in constant heap
509 space and logarithmic stack space.
510 val fast_sort : ('a -> 'a -> int) -> 'a list -> 'a list
514 Same as List.sort or List.stable_sort , whichever is faster on typical
516 input.
517 val sort_uniq : ('a -> 'a -> int) -> 'a list -> 'a list
521 Same as List.sort , but also remove duplicates.
523 Since 4.02.0
526 val merge : ('a -> 'a -> int) -> 'a list -> 'a list -> 'a list
530 Merge two lists: Assuming that l1 and l2 are sorted according to the
532 comparison function cmp , merge cmp l1 l2 will return a sorted list
533 containing all the elements of l1 and l2 . If several elements compare
534 equal, the elements of l1 will be before the elements of l2 . Not
535 tail-recursive (sum of the lengths of the arguments).
536 Iterators
541 val to_seq : 'a list -> 'a Seq.t
542 Iterate on the list
544 Since 4.07
547 val of_seq : 'a Seq.t -> 'a list
551 Create a list from the iterator
553 Since 4.07
556OCamldoc 2020-02-27 Stdlib.List(3)