simon/ocaml-containers
1
0
Fork 0
mirror of https://github.com/c-cube/ocaml-containers.git synced 2025-12-06 11:15:31 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions

doc/CCHeap: uniformize doc of conversion functions

Browse source
This commit is contained in:
Glen Mével 2024-07-26 22:33:33 +02:00
parent 6bd5d3aacf
commit 8666faf257
2 changed files with 86 additions and 41 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

74
src/core/CCHeap.ml
View file

@ -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

53
src/core/CCHeap.mli
View file

@ -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