mirror of
https://github.com/c-cube/ocaml-containers.git
synced 2025-12-07 11:45:31 -05:00
189 lines
6.1 KiB
OCaml
189 lines
6.1 KiB
OCaml
(* This file is free software, part of containers. See file "license" for more details. *)
|
|
|
|
(** Leftist Heaps
|
|
|
|
Implementation following Okasaki's book. *)
|
|
|
|
type 'a iter = ('a -> unit) -> unit
|
|
(** Fast internal iterator.
|
|
@since 2.8 *)
|
|
|
|
type 'a gen = unit -> 'a option
|
|
type 'a ktree = unit -> [ `Nil | `Node of 'a * 'a ktree list ]
|
|
type 'a printer = Format.formatter -> 'a -> unit
|
|
|
|
module type PARTIAL_ORD = sig
|
|
type t
|
|
|
|
val leq : t -> t -> bool
|
|
(** [leq x y] shall return [true] iff [x] is lower or equal to [y]. *)
|
|
end
|
|
|
|
module type TOTAL_ORD = sig
|
|
type t
|
|
|
|
val compare : t -> t -> int
|
|
(** [compare a b] shall return
|
|
a negative value if [a] is smaller than [b],
|
|
[0] if [a] and [b] are equal or
|
|
a positive value if [a] is greater than [b] *)
|
|
end
|
|
|
|
module type S = sig
|
|
type elt
|
|
type t
|
|
|
|
val empty : t
|
|
(** [empty] returns the empty heap. *)
|
|
|
|
val is_empty : t -> bool
|
|
(** [is_empty h] returns [true] if the heap [h] is empty. *)
|
|
|
|
exception Empty
|
|
|
|
val merge : t -> t -> t
|
|
(** [merge h1 h2] merges the two heaps [h1] and [h2]. *)
|
|
|
|
val insert : elt -> t -> t
|
|
(** [insert x h] inserts an element [x] into the heap [h]. *)
|
|
|
|
val add : t -> elt -> t
|
|
(** [add h x] inserts an element [x] into the heap [h]. *)
|
|
|
|
val filter : (elt -> bool) -> t -> t
|
|
(** [filter p h] filters values, only retaining the ones that satisfy the predicate [p].
|
|
Linear time at least. *)
|
|
|
|
val find_min : t -> elt option
|
|
(** [find_min h] find the minimal element of the heap [h]. *)
|
|
|
|
val find_min_exn : t -> elt
|
|
(** [find_min_exn h] is like {!find_min} but can fail.
|
|
@raise Empty if the heap is empty. *)
|
|
|
|
val take : t -> (t * elt) option
|
|
(** [take h] extracts and returns the minimum element, and the new heap (without
|
|
this element), or [None] if the heap [h] is empty. *)
|
|
|
|
val take_exn : t -> t * elt
|
|
(** [take_exn h] is like {!take}, but can fail.
|
|
@raise Empty if the heap is empty. *)
|
|
|
|
val delete_one : (elt -> elt -> bool) -> elt -> t -> t
|
|
(** [delete_one eq x h] uses [eq] to find one occurrence of a value [x]
|
|
if it exist in the heap [h], and delete it.
|
|
If [h] do not contain [x] then it return [h].
|
|
@since 2.0 *)
|
|
|
|
val delete_all : (elt -> elt -> bool) -> elt -> t -> t
|
|
(** [delete_all eq x h] uses [eq] to find all [x] in [h] and delete them.
|
|
If [h] do not contain [x] then it return [h].
|
|
The difference with {!filter} is that [delete_all] stops as soon as
|
|
it enters a subtree whose root is bigger than the element.
|
|
@since 2.0 *)
|
|
|
|
val iter : (elt -> unit) -> t -> unit
|
|
(** [iter f h] iterates over the heap [h] invoking [f] with the current element. *)
|
|
|
|
val fold : ('a -> elt -> 'a) -> 'a -> t -> 'a
|
|
(** [fold f acc h] folds on all values of [h]. *)
|
|
|
|
val size : t -> int
|
|
(** [size h] is the number of elements in the heap [h]. Linear complexity. *)
|
|
|
|
(** {2 Conversions} *)
|
|
|
|
val to_list : t -> elt list
|
|
(** [to_list h] returns the elements of the heap [h], in no particular order. *)
|
|
|
|
val to_list_sorted : t -> elt list
|
|
(** [to_list_sorted h] returns the elements of the heap [h] in increasing order.
|
|
@since 1.1 *)
|
|
|
|
val add_list : t -> elt list -> t
|
|
(** [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 of_list : elt list -> t
|
|
(** [of_list l] is [add_list empty l]. Complexity: [O(n log n)]. *)
|
|
|
|
val add_iter : t -> elt iter -> t
|
|
(** [add_iter h iter] is like {!add_list}.
|
|
@since 2.8 *)
|
|
|
|
val add_seq : t -> elt Seq.t -> t
|
|
(** [add_seq h seq] is like {!add_list}.
|
|
Renamed from [add_std_seq] since 3.0.
|
|
@since 3.0 *)
|
|
|
|
val of_iter : elt iter -> t
|
|
(** [of_iter iter] builds a heap from a given [iter]. Complexity: [O(n log n)].
|
|
@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)].
|
|
Renamed from [of_seq] since 3.0.
|
|
@since 3.0 *)
|
|
|
|
val to_iter : t -> elt iter
|
|
(** [to_iter h] returns a [iter] of the elements of the heap [h].
|
|
@since 2.8 *)
|
|
|
|
val to_seq : t -> elt Seq.t
|
|
(** [to_seq h] returns a [Seq.t] of the elements of the heap [h].
|
|
Renamed from [to_std_seq] since 3.0.
|
|
@since 3.0 *)
|
|
|
|
val to_iter_sorted : t -> elt iter
|
|
(** [to_iter_sorted h] returns a [iter] by iterating on the elements of [h],
|
|
in increasing order.
|
|
@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.
|
|
Renamed from [to_std_seq_sorted] 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].
|
|
@since 0.16 *)
|
|
|
|
val of_gen : elt gen -> t
|
|
(** [of_gen gen] builds a heap from a given [gen]. Complexity: [O(n log n)]. *)
|
|
|
|
val to_gen : t -> elt gen
|
|
(** [to_gen h] returns a [gen] of the elements of the heap [h]. *)
|
|
|
|
val to_tree : t -> elt ktree
|
|
(** [to_tree h] returns a [ktree] of the elements of the heap [h]. *)
|
|
|
|
val to_string : ?sep:string -> (elt -> string) -> t -> string
|
|
(** [to_string ?sep f h] prints the heap [h] in a string
|
|
using [sep] as a given separator (default ",") between each element
|
|
(converted to a string using [f]).
|
|
@since 2.7 *)
|
|
|
|
val pp :
|
|
?pp_start:unit printer ->
|
|
?pp_stop:unit printer ->
|
|
?pp_sep:unit printer ->
|
|
elt printer ->
|
|
t printer
|
|
(** [pp ?pp_start ?pp_stop ?pp_sep ppf h] prints [h] on [ppf].
|
|
Each element is formatted with [ppf], [pp_start] is called at the beginning,
|
|
[pp_stop] is called at the end, [pp_sep] is called between each elements.
|
|
By defaults [pp_start] and [pp_stop] does nothing and [pp_sep] defaults to
|
|
(fun out -> Format.fprintf out ",@ ").
|
|
Renamed from [print] since 2.0
|
|
@since 0.16 *)
|
|
end
|
|
|
|
module Make (E : PARTIAL_ORD) : S with type elt = E.t
|
|
|
|
(** A convenient version of [Make] that take a [TOTAL_ORD] instead of
|
|
a partially ordered module.
|
|
It allow to directly pass modules that implement [compare]
|
|
without implementing [leq] explicitly *)
|
|
module Make_from_compare (E : TOTAL_ORD) : S with type elt = E.t
|