From 8666faf25793fa16f0e04d27ec54ed76f2817c93 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Glen=20M=C3=A9vel?= Date: Fri, 26 Jul 2024 22:33:33 +0200 Subject: [PATCH] doc/CCHeap: uniformize doc of conversion functions --- src/core/CCHeap.ml | 74 +++++++++++++++++++++++++++++++-------------- src/core/CCHeap.mli | 53 +++++++++++++++++++++----------- 2 files changed, 86 insertions(+), 41 deletions(-) diff --git a/src/core/CCHeap.ml b/src/core/CCHeap.ml index 5aefb2f8..bd2f4c03 100644 --- a/src/core/CCHeap.ml +++ b/src/core/CCHeap.ml @@ -87,66 +87,90 @@ module type S = sig val size : t -> int (** Number of elements (linear complexity). *) - (** {2 Conversions} *) + (** {2 Adding many elements at once} *) val add_list : t -> elt list -> t - (** Add the elements of the list to the heap. An element occurring several - times will be added that many times to the heap. + (** [add_list h l] adds the elements of the list [l] into the heap [h]. + An element occurring several times will be added that many times to the heap. @since 0.16 *) val add_iter : t -> elt iter -> t - (** Like {!add_list}. + (** [add_iter h iter] is akin to {!add_list}, + but taking an [iter] of elements as input. @since 2.8 *) val add_seq : t -> elt Seq.t -> t - (** Like {!add_list}. - @since 2.8 *) + (** [add_seq h seq] is akin to {!add_list}, + but taking a [Seq.t] of elements as input. + Renamed from [add_std_seq] since 3.0. + @since 3.0 *) val add_gen : t -> elt gen -> t - (** @since 0.16 *) + (** [add_gen h gen] is akin to {!add_list}, + but taking a [gen] of elements as input. + @since 0.16 *) + + (** {2 Conversions} *) val of_list : elt list -> t - (** [of_list l] is [add_list empty l]. Complexity: [O(n log n)]. *) + (** [of_list l] builds a heap from a given list of elements. + It is equivalent to [add_list empty l]. + Complexity: [O(n log n)]. + *) val of_iter : elt iter -> t - (** Build a heap from a given [iter]. Complexity: [O(n log n)]. + (** [of_iter iter] is akin to {!of_list}, + but taking an [iter] of elements as input. @since 2.8 *) val of_seq : elt Seq.t -> t - (** Build a heap from a given [Seq.t]. Complexity: [O(n log n)]. - @since 2.8 *) + (** [of_seq seq] is akin to {!of_list}, + but taking a [Seq.t] of elements as input. + Renamed from [of_seq] since 3.0. + @since 3.0 *) val of_gen : elt gen -> t - (** Build a heap from a given [gen]. Complexity: [O(n log n)]. *) + (** [of_gen gen] is akin to {!of_list}, + but taking a [gen] of elements as input. *) val to_list : t -> elt list - (** Return the elements of the heap, in no particular order. *) + (** [to_list h] returns a list of the elements of the heap [h], + in no particular order. + *) val to_iter : t -> elt iter - (** Return a [iter] of the elements of the heap. + (** [to_iter h] is akin to {!to_list}, but returning an [iter] of elements. @since 2.8 *) val to_seq : t -> elt Seq.t - (** Return a [Seq.t] of the elements of the heap. - @since 2.8 *) + (** [to_seq h] is akin to {!to_list}, but returning a [Seq.t] of elements + Renamed from [to_std_seq] since 3.0. + @since 3.0 *) val to_gen : t -> elt gen - (** Return a [gen] of the elements of the heap. *) + (** [to_gen h] is akin to {!to_list}, but returning a [gen] of elements. *) val to_list_sorted : t -> elt list - (** Return the elements in increasing order. + (** [to_list_sorted h] returns the list of elements of the heap [h] + in increasing order. @since 1.1 *) val to_iter_sorted : t -> elt iter - (** Iterate on the elements, in increasing order. + (** [to_iter_sorted h] is akin to {!to_list_sorted}, + but returning an [iter] of elements. @since 2.8 *) val to_seq_sorted : t -> elt Seq.t - (** Iterate on the elements, in increasing order. - @since 2.8 *) + (** [to_seq_sorted h] is akin to {!to_list_sorted}, + but returning a [Seq.t] of elements. + Renamed from [to_std_seq_sorted] since 3.0. + @since 3.0 *) val to_tree : t -> elt ktree - (** Return a [ktree] of the elements of the heap. *) + (** [to_tree h] returns a [ktree] of the elements of the heap [h]. + The layout is not specified. *) + + (** {2 Pretty-printing} *) val to_string : ?sep:string -> (elt -> string) -> t -> string (** Print the heap in a string @@ -281,7 +305,7 @@ module Make (E : PARTIAL_ORD) : S with type elt = E.t = struct | E -> 0 | N (_, _, l, r) -> 1 + size l + size r - (** {2 Conversions} *) + (** {2 Adding many elements at once} *) let add_list h l = List.fold_left add h l @@ -300,6 +324,8 @@ module Make (E : PARTIAL_ORD) : S with type elt = E.t = struct | None -> h | Some x -> add_gen (add h x) g + (** {2 Conversions} *) + let of_list l = add_list empty l let of_iter i = add_iter empty i let of_seq seq = add_seq empty seq @@ -370,6 +396,8 @@ module Make (E : PARTIAL_ORD) : S with type elt = E.t = struct | E -> `Nil | N (_, x, l, r) -> `Node (x, [ to_tree l; to_tree r ]) + (** {2 Pretty-printing} *) + let to_string ?(sep = ",") elt_to_string h = to_list_sorted h |> List.map elt_to_string |> String.concat sep diff --git a/src/core/CCHeap.mli b/src/core/CCHeap.mli index fdc4269f..14b2917f 100644 --- a/src/core/CCHeap.mli +++ b/src/core/CCHeap.mli @@ -91,7 +91,7 @@ module type S = sig val size : t -> int (** [size h] is the number of elements in the heap [h]. Linear complexity. *) - (** {2 Conversions} *) + (** {2 Adding many elements at once} *) val add_list : t -> elt list -> t (** [add_list h l] adds the elements of the list [l] into the heap [h]. @@ -99,65 +99,82 @@ module type S = sig @since 0.16 *) val add_iter : t -> elt iter -> t - (** [add_iter h iter] is like {!add_list}. + (** [add_iter h iter] is akin to {!add_list}, + but taking an [iter] of elements as input. @since 2.8 *) val add_seq : t -> elt Seq.t -> t - (** [add_seq h seq] is like {!add_list}. + (** [add_seq h seq] is akin to {!add_list}, + but taking a [Seq.t] of elements as input. Renamed from [add_std_seq] since 3.0. @since 3.0 *) val add_gen : t -> elt gen -> t - (** [add_gen h gen] adds the gen [gen] to the heap [h]. + (** [add_gen h gen] is akin to {!add_list}, + but taking a [gen] of elements as input. @since 0.16 *) + (** {2 Conversions} *) + val of_list : elt list -> t - (** [of_list l] is [add_list empty l]. Complexity: [O(n log n)]. *) + (** [of_list l] builds a heap from a given list of elements. + It is equivalent to [add_list empty l]. + Complexity: [O(n log n)]. + *) val of_iter : elt iter -> t - (** [of_iter iter] builds a heap from a given [iter]. Complexity: [O(n log n)]. + (** [of_iter iter] is akin to {!of_list}, + but taking an [iter] of elements as input. @since 2.8 *) val of_seq : elt Seq.t -> t - (** [of_seq seq] builds a heap from a given [Seq.t]. Complexity: [O(n log n)]. + (** [of_seq seq] is akin to {!of_list}, + but taking a [Seq.t] of elements as input. Renamed from [of_seq] since 3.0. @since 3.0 *) val of_gen : elt gen -> t - (** [of_gen gen] builds a heap from a given [gen]. Complexity: [O(n log n)]. *) + (** [of_gen gen] is akin to {!of_list}, + but taking a [gen] of elements as input. *) val to_list : t -> elt list - (** [to_list h] returns the elements of the heap [h], in no particular order. *) + (** [to_list h] returns a list of the elements of the heap [h], + in no particular order. + *) val to_iter : t -> elt iter - (** [to_iter h] returns a [iter] of the elements of the heap [h]. + (** [to_iter h] is akin to {!to_list}, but returning an [iter] of elements. @since 2.8 *) val to_seq : t -> elt Seq.t - (** [to_seq h] returns a [Seq.t] of the elements of the heap [h]. + (** [to_seq h] is akin to {!to_list}, but returning a [Seq.t] of elements Renamed from [to_std_seq] since 3.0. @since 3.0 *) val to_gen : t -> elt gen - (** [to_gen h] returns a [gen] of the elements of the heap [h]. *) + (** [to_gen h] is akin to {!to_list}, but returning a [gen] of elements. *) val to_list_sorted : t -> elt list - (** [to_list_sorted h] returns the elements of the heap [h] in increasing order. + (** [to_list_sorted h] returns the list of elements of the heap [h] + in increasing order. @since 1.1 *) val to_iter_sorted : t -> elt iter - (** [to_iter_sorted h] returns a [iter] by iterating on the elements of [h], - in increasing order. + (** [to_iter_sorted h] is akin to {!to_list_sorted}, + but returning an [iter] of elements. @since 2.8 *) val to_seq_sorted : t -> elt Seq.t - (** [to_seq_sorted h] returns a [Seq.t] by iterating on the elements of [h], - in increasing order. + (** [to_seq_sorted h] is akin to {!to_list_sorted}, + but returning a [Seq.t] of elements. Renamed from [to_std_seq_sorted] since 3.0. @since 3.0 *) val to_tree : t -> elt ktree - (** [to_tree h] returns a [ktree] of the elements of the heap [h]. *) + (** [to_tree h] returns a [ktree] of the elements of the heap [h]. + The layout is not specified. *) + + (** {2 Pretty-printing} *) val to_string : ?sep:string -> (elt -> string) -> t -> string (** [to_string ?sep f h] prints the heap [h] in a string