Unify labeled and unlabeled Standard Library modules

1 files changed, 72 insertions, 69 deletions

diff --git a/stdlib/listLabels.mli b/stdlib/listLabels.mli
index c98eaeef34..4563bf8517 100644
--- a/stdlib/listLabels.mli
+++ b/stdlib/listLabels.mli
@@ -13,8 +13,8 @@
 (*                                                                        *)
 (**************************************************************************)
 
-type 'a t = 'a list = [] | (::) of 'a * 'a list (**)
-(** An alias for the type of lists.
+(* NOTE: When updating listLabels.mli, run tools/unlabel to generate
+   list.mli
  *)
 
 (** List operations.
@@ -29,8 +29,9 @@ type 'a t = 'a list = [] | (::) of 'a * 'a list (**)
    The above considerations can usually be ignored if your lists are not
    longer than about 10000 elements.
 
-   This module is intended to be used through {!StdLabels} which replaces
-   {!Array}, {!Bytes}, {!List} and {!String} with their labeled counterparts.
+   The labeled version of this module, {!ListLabels}, is intended to be used
+   through {!StdLabels} which replaces {!Array}, {!Bytes}, {!List} and
+   {!String} with their labeled counterparts.
 
    For example:
    {[
@@ -40,32 +41,34 @@ type 'a t = 'a list = [] | (::) of 'a * 'a list (**)
    ]}
  *)
 
-val length : 'a list -> int
-(** Return the length (number of elements) of the given list.
- *)
+type 'a t = 'a list = [] | (::) of 'a * 'a list (**)
+(** An alias for the type of lists.  *)
 
-val hd : 'a list -> 'a
-(** Return the first element of the given list.
-   @raise Failure if the list is empty.
- *)
+val length : 'a list -> int
+(** Return the length (number of elements) of the given list. *)
 
 val compare_lengths : 'a list -> 'b list -> int
 (** Compare the lengths of two lists. [compare_lengths l1 l2] is
    equivalent to [compare (length l1) (length l2)], except that
-   the computation stops after itering on the shortest list.
+   the computation stops after reaching the end of the shortest list.
    @since 4.05.0
  *)
 
 val compare_length_with : 'a list -> len:int -> int
-(** Compare the length of a list to an integer. [compare_length_with l n] is
-   equivalent to [compare (length l) n], except that
-   the computation stops after at most [n] iterations on the list.
+(** Compare the length of a list to an integer. [compare_length_with l len] is
+   equivalent to [compare (length l) len], except that the computation stops
+   after at most [len] iterations on the list.
    @since 4.05.0
  *)
 
 val cons : 'a -> 'a list -> 'a list
 (** [cons x xs] is [x :: xs]
-    @since 4.05.0
+    @since 4.05.0 in labeled module or 4.03.0 in unlabeled
+ *)
+
+val hd : 'a list -> 'a
+(** Return the first element of the given list.
+   @raise Failure if the list is empty.
  *)
 
 val tl : 'a list -> 'a list
@@ -80,7 +83,7 @@ val nth : 'a list -> int -> 'a
    @raise Invalid_argument if [n] is negative.
  *)
 
-val nth_opt: 'a list -> int -> 'a option
+val nth_opt : 'a list -> int -> 'a option
 (** Return the [n]-th element of the given list.
     The first element (head of the list) is at position 0.
     Return [None] if the list is too short.
@@ -89,23 +92,22 @@ val nth_opt: 'a list -> int -> 'a option
  *)
 
 val rev : 'a list -> 'a list
-(** List reversal.
- *)
+(** List reversal.  *)
 
 val init : len:int -> f:(int -> 'a) -> 'a list
-(** [List.init len f] is [f 0; f 1; ...; f (len-1)], evaluated left to right.
+(** [init len f] is [f 0; f 1; ...; f (len-1)], evaluated left to right.
     @raise Invalid_argument if [len < 0].
     @since 4.06.0
  *)
 
 val append : 'a list -> 'a list -> 'a list
-(** Catenate two lists. Same function as the infix operator [@].
+(** Concatenate two lists. Same function as the infix operator [@].
    Not tail-recursive (length of the first argument). The [@]
    operator is not tail-recursive either.
  *)
 
 val rev_append : 'a list -> 'a list -> 'a list
-(** [List.rev_append l1 l2] reverses [l1] and concatenates it with [l2].
+(** [rev_append l1 l2] reverses [l1] and concatenates it with [l2].
    This is equivalent to [(]{!List.rev}[ l1) @ l2], but [rev_append] is
    tail-recursive and more efficient.
  *)
@@ -118,7 +120,7 @@ val concat : 'a list list -> 'a list
  *)
 
 val flatten : 'a list list -> 'a list
-(** Same as [concat]. Not tail-recursive
+(** Same as {!List.concat}. Not tail-recursive
    (length of the argument + length of the longest sub-list).
  *)
 
@@ -127,7 +129,7 @@ val flatten : 'a list list -> 'a list
 
 
 val iter : f:('a -> unit) -> 'a list -> unit
-(** [List.iter f [a1; ...; an]] applies function [f] in turn to
+(** [iter f [a1; ...; an]] applies function [f] in turn to
    [a1; ...; an]. It is equivalent to
    [begin f a1; f a2; ...; f an; () end].
  *)
@@ -140,7 +142,7 @@ val iteri : f:(int -> 'a -> unit) -> 'a list -> unit
  *)
 
 val map : f:('a -> 'b) -> 'a list -> 'b list
-(** [List.map f [a1; ...; an]] applies function [f] to [a1, ..., an],
+(** [map f [a1; ...; an]] applies function [f] to [a1, ..., an],
    and builds the list [[f a1; ...; f an]]
    with the results returned by [f]. Not tail-recursive.
  *)
@@ -148,12 +150,12 @@ val map : f:('a -> 'b) -> 'a list -> 'b list
 val mapi : f:(int -> 'a -> 'b) -> 'a list -> 'b list
 (** Same as {!List.map}, but the function is applied to the index of
    the element as first argument (counting from 0), and the element
-   itself as second argument.
+   itself as second argument. Not tail-recursive.
    @since 4.00.0
  *)
 
 val rev_map : f:('a -> 'b) -> 'a list -> 'b list
-(** [List.rev_map f l] gives the same result as
+(** [rev_map f l] gives the same result as
    {!List.rev}[ (]{!List.map}[ f l)], but is tail-recursive and
    more efficient.
  *)
@@ -166,26 +168,25 @@ val filter_map : f:('a -> 'b option) -> 'a list -> 'b list
  *)
 
 val concat_map : f:('a -> 'b list) -> 'a list -> 'b list
-(** [List.concat_map f l] gives the same result as
+(** [concat_map f l] gives the same result as
     {!List.concat}[ (]{!List.map}[ f l)]. Tail-recursive.
-
     @since 4.10.0
 *)
 
 val fold_left_map :
   f:('a -> 'b -> 'a * 'c) -> init:'a -> 'b list -> 'a * 'c list
-(** [fold_left_map] is  a combination of [fold_left] and [map] hat threads an
-    accumulator through calls to [f]
+(** [fold_left_map] is  a combination of [fold_left] and [map] that threads an
+    accumulator through calls to [f].
     @since 4.11.0
 *)
 
 val fold_left : f:('a -> 'b -> 'a) -> init:'a -> 'b list -> 'a
-(** [List.fold_left f a [b1; ...; bn]] is
+(** [fold_left f a [b1; ...; bn]] is
    [f (... (f (f a b1) b2) ...) bn].
  *)
 
 val fold_right : f:('a -> 'b -> 'b) -> 'a list -> init:'b -> 'b
-(** [List.fold_right f [a1; ...; an] b] is
+(** [fold_right f [a1; ...; an] b] is
    [f a1 (f a2 (... (f an b) ...))]. Not tail-recursive.
  *)
 
@@ -194,37 +195,37 @@ val fold_right : f:('a -> 'b -> 'b) -> 'a list -> init:'b -> 'b
 
 
 val iter2 : f:('a -> 'b -> unit) -> 'a list -> 'b list -> unit
-(** [List.iter2 f [a1; ...; an] [b1; ...; bn]] calls in turn
+(** [iter2 f [a1; ...; an] [b1; ...; bn]] calls in turn
    [f a1 b1; ...; f an bn].
    @raise Invalid_argument if the two lists are determined
    to have different lengths.
  *)
 
 val map2 : f:('a -> 'b -> 'c) -> 'a list -> 'b list -> 'c list
-(** [List.map2 f [a1; ...; an] [b1; ...; bn]] is
+(** [map2 f [a1; ...; an] [b1; ...; bn]] is
    [[f a1 b1; ...; f an bn]].
    @raise Invalid_argument if the two lists are determined
    to have different lengths. Not tail-recursive.
  *)
 
 val rev_map2 : f:('a -> 'b -> 'c) -> 'a list -> 'b list -> 'c list
-(** [List.rev_map2 f l1 l2] gives the same result as
+(** [rev_map2 f l1 l2] gives the same result as
    {!List.rev}[ (]{!List.map2}[ f l1 l2)], but is tail-recursive and
    more efficient.
  *)
 
 val fold_left2 :
   f:('a -> 'b -> 'c -> 'a) -> init:'a -> 'b list -> 'c list -> 'a
-(** [List.fold_left2 f a [b1; ...; bn] [c1; ...; cn]] is
-   [f (... (f (f a b1 c1) b2 c2) ...) bn cn].
+(** [fold_left2 f init [a1; ...; an] [b1; ...; bn]] is
+   [f (... (f (f init a1 b1) a2 b2) ...) an bn].
    @raise Invalid_argument if the two lists are determined
    to have different lengths.
  *)
 
 val fold_right2 :
   f:('a -> 'b -> 'c -> 'c) -> 'a list -> 'b list -> init:'c -> 'c
-(** [List.fold_right2 f [a1; ...; an] [b1; ...; bn] c] is
-   [f a1 b1 (f a2 b2 (... (f an bn c) ...))].
+(** [fold_right2 f [a1; ...; an] [b1; ...; bn] init] is
+   [f a1 b1 (f a2 b2 (... (f an bn init) ...))].
    @raise Invalid_argument if the two lists are determined
    to have different lengths. Not tail-recursive.
  *)
@@ -234,15 +235,17 @@ val fold_right2 :
 
 
 val for_all : f:('a -> bool) -> 'a list -> bool
-(** [for_all p [a1; ...; an]] checks if all elements of the list
-   satisfy the predicate [p]. That is, it returns
-   [(p a1) && (p a2) && ... && (p an)].
+(** [for_all f [a1; ...; an]] checks if all elements of the list
+   satisfy the predicate [f]. That is, it returns
+   [(f a1) && (f a2) && ... && (f an)] for a non-empty list and
+   [true] if the list is empty.
  *)
 
 val exists : f:('a -> bool) -> 'a list -> bool
-(** [exists p [a1; ...; an]] checks if at least one element of
-   the list satisfies the predicate [p]. That is, it returns
-   [(p a1) || (p a2) || ... || (p an)].
+(** [exists f [a1; ...; an]] checks if at least one element of
+   the list satisfies the predicate [f]. That is, it returns
+   [(f a1) || (f a2) || ... || (f an)] for a non-empty list and
+   [false] if the list is empty.
  *)
 
 val for_all2 : f:('a -> 'b -> bool) -> 'a list -> 'b list -> bool
@@ -258,8 +261,8 @@ val exists2 : f:('a -> 'b -> bool) -> 'a list -> 'b list -> bool
  *)
 
 val mem : 'a -> set:'a list -> bool
-(** [mem a l] is true if and only if [a] is equal
-   to an element of [l].
+(** [mem a set] is true if and only if [a] is equal
+   to an element of [set].
  *)
 
 val memq : 'a -> set:'a list -> bool
@@ -272,21 +275,21 @@ val memq : 'a -> set:'a list -> bool
 
 
 val find : f:('a -> bool) -> 'a list -> 'a
-(** [find p l] returns the first element of the list [l]
-   that satisfies the predicate [p].
-   @raise Not_found if there is no value that satisfies [p] in the
+(** [find f l] returns the first element of the list [l]
+   that satisfies the predicate [f].
+   @raise Not_found if there is no value that satisfies [f] in the
    list [l].
  *)
 
-val find_opt: f:('a -> bool) -> 'a list -> 'a option
-(** [find p l] returns the first element of the list [l]
-   that satisfies the predicate [p].
-   Returns [None] if there is no value that satisfies [p] in the
+val find_opt : f:('a -> bool) -> 'a list -> 'a option
+(** [find f l] returns the first element of the list [l]
+   that satisfies the predicate [f].
+   Returns [None] if there is no value that satisfies [f] in the
    list [l].
    @since 4.05
  *)
 
-val find_map: f:('a -> 'b option) -> 'a list -> 'b option
+val find_map : f:('a -> 'b option) -> 'a list -> 'b option
 (** [find_map f l] applies [f] to the elements of [l] in order,
     and returns the first result of the form [Some v], or [None]
     if none exist.
@@ -294,8 +297,8 @@ val find_map: f:('a -> 'b option) -> 'a list -> 'b option
 *)
 
 val filter : f:('a -> bool) -> 'a list -> 'a list
-(** [filter p l] returns all the elements of the list [l]
-   that satisfy the predicate [p]. The order of the elements
+(** [filter f l] returns all the elements of the list [l]
+   that satisfy the predicate [f]. The order of the elements
    in the input list is preserved.
  *)
 
@@ -311,10 +314,10 @@ val filteri : f:(int -> 'a -> bool) -> 'a list -> 'a list
 *)
 
 val partition : f:('a -> bool) -> 'a list -> 'a list * 'a list
-(** [partition p l] returns a pair of lists [(l1, l2)], where
+(** [partition f l] returns a pair of lists [(l1, l2)], where
    [l1] is the list of all the elements of [l] that
-   satisfy the predicate [p], and [l2] is the list of all the
-   elements of [l] that do not satisfy [p].
+   satisfy the predicate [f], and [l2] is the list of all the
+   elements of [l] that do not satisfy [f].
    The order of the elements in the input list is preserved.
  *)
 
@@ -331,7 +334,7 @@ val assoc : 'a -> ('a * 'b) list -> 'b
    list [l].
  *)
 
-val assoc_opt: 'a -> ('a * 'b) list -> 'b option
+val assoc_opt : 'a -> ('a * 'b) list -> 'b option
 (** [assoc_opt a l] returns the value associated with key [a] in the list of
     pairs [l]. That is,
     [assoc a [ ...; (a,b); ...] = b]
@@ -346,15 +349,15 @@ val assq : 'a -> ('a * 'b) list -> 'b
    structural equality to compare keys.
  *)
 
-val assq_opt: 'a -> ('a * 'b) list -> 'b option
+val assq_opt : 'a -> ('a * 'b) list -> 'b option
 (** Same as {!List.assoc_opt}, but uses physical equality instead of
    structural equality to compare keys.
    @since 4.05.0
  *)
 
 val mem_assoc : 'a -> map:('a * 'b) list -> bool
-(** Same as {!List.assoc}, but simply return true if a binding exists,
-   and false if no bindings exist for the given key.
+(** Same as {!List.assoc}, but simply return [true] if a binding exists,
+   and [false] if no bindings exist for the given key.
  *)
 
 val mem_assq : 'a -> map:('a * 'b) list -> bool
@@ -414,7 +417,7 @@ val sort : cmp:('a -> 'a -> int) -> 'a list -> 'a list
 val stable_sort : cmp:('a -> 'a -> int) -> 'a list -> 'a list
 (** Same as {!List.sort}, but the sorting algorithm is guaranteed to
    be stable (i.e. elements that compare equal are kept in their
-   original order) .
+   original order).
 
    The current implementation uses Merge Sort. It runs in constant
    heap space and logarithmic stack space.
@@ -427,7 +430,7 @@ val fast_sort : cmp:('a -> 'a -> int) -> 'a list -> 'a list
 
 val sort_uniq : cmp:('a -> 'a -> int) -> 'a list -> 'a list
 (** Same as {!List.sort}, but also remove duplicates.
-    @since 4.03.0
+    @since 4.03.0 in labeled module or 4.02.0 in unlabeled module
  *)
 
 val merge : cmp:('a -> 'a -> int) -> 'a list -> 'a list -> 'a list
@@ -443,11 +446,11 @@ val merge : cmp:('a -> 'a -> int) -> 'a list -> 'a list -> 'a list
 (** {1 Iterators} *)
 
 val to_seq : 'a list -> 'a Seq.t
-(** Iterate on the list
+(** Iterate on the list.
     @since 4.07
  *)
 
 val of_seq : 'a Seq.t -> 'a list
-(** Create a list from the iterator
+(** Create a list from the iterator.
     @since 4.07
  *)