package core_kernel

  1. Overview
  2. Docs
Legend:
Library
Module
Module type
Parameter
Class
Class type

A polymorphic hashtbl that uses Pool to avoid allocation.

This uses the standard linked-chain hashtable algorithm, albeit with links performed through a pool and hence avoiding caml_modify (for table manipulation), even when hashing object keys/values.

This implementation is worth exploring for your application if profiling demonstrates that garbage collection and the caml_modify write barrier are a significant part of your execution time.

include Core_kernel.Hashtbl_intf.Hashtbl
val hash : 'a -> int
val hash_param : int -> int -> 'a -> int
type ('a, 'b) t
val sexp_of_t : ('a -> Base.Sexp.t) -> ('b -> Base.Sexp.t) -> ('a, 'b) t -> Base.Sexp.t

We provide a sexp_of_t but not a t_of_sexp for this type because one needs to be explicit about the hash and comparison functions used when creating a hashtable. Note that Hashtbl.Poly.t does have [@@deriving_inline sexp][@@@end], and uses OCaml's built-in polymorphic comparison and and polymorphic hashing.

Creators

val create : ?growth_allowed:bool -> ?size:int -> (module Base__.Hashtbl_intf.Key with type t = 'a) -> ('a, 'b) t

The module you pass to create must have a type that is hashable, sexpable, and comparable.

Example:

        Hashtbl.create (module Int);;
        - : (int, '_a) Hashtbl.t = <abstr>;;
val of_alist : ?growth_allowed:bool -> ?size:int -> (module Base__.Hashtbl_intf.Key with type t = 'a) -> ('a * 'b) list -> [ `Ok of ('a, 'b) t | `Duplicate_key of 'a ]

Example:

         Hashtbl.of_alist (module Int) [(3, "something"); (2, "whatever")]
         - : [ `Duplicate_key of int | `Ok of (int, string) Hashtbl.t ] = `Ok <abstr>
val of_alist_report_all_dups : ?growth_allowed:bool -> ?size:int -> (module Base__.Hashtbl_intf.Key with type t = 'a) -> ('a * 'b) list -> [ `Ok of ('a, 'b) t | `Duplicate_keys of 'a list ]

Whereas of_alist will report Duplicate_key no matter how many dups there are in your list, of_alist_report_all_dups will report each and every duplicate entry.

For example:

        Hashtbl.of_alist (module Int) [(1, "foo"); (1, "bar"); (2, "foo"); (2, "bar")];;
        - : [ `Duplicate_key of int | `Ok of (int, string) Hashtbl.t ] = `Duplicate_key 1

        Hashtbl.of_alist_report_all_dups (module Int) [(1, "foo"); (1, "bar"); (2, "foo"); (2, "bar")];;
        - : [ `Duplicate_keys of int list | `Ok of (int, string) Hashtbl.t ] = `Duplicate_keys [1; 2]
val of_alist_or_error : ?growth_allowed:bool -> ?size:int -> (module Base__.Hashtbl_intf.Key with type t = 'a) -> ('a * 'b) list -> ('a, 'b) t Base.Or_error.t
val of_alist_exn : ?growth_allowed:bool -> ?size:int -> (module Base__.Hashtbl_intf.Key with type t = 'a) -> ('a * 'b) list -> ('a, 'b) t
val of_alist_multi : ?growth_allowed:bool -> ?size:int -> (module Base__.Hashtbl_intf.Key with type t = 'a) -> ('a * 'b) list -> ('a, 'b list) t

Creates a "multi" hashtable, i.e., a hashtable where each key points to a list potentially containing multiple values. So instead of short-circuiting with a `Duplicate_key variant on duplicates, as in of_alist, of_alist_multi folds those values into a list for the given key:

      let h = Hashtbl.of_alist_multi (module Int) [(1, "a"); (1, "b"); (2, "c"); (2, "d")];;
      val h : (int, string list) Hashtbl.t = <abstr>

      Hashtbl.find_exn h 1;;
      - : string list = ["b"; "a"]
val create_mapped : ?growth_allowed:bool -> ?size:int -> (module Base__.Hashtbl_intf.Key with type t = 'a) -> get_key:('r -> 'a) -> get_data:('r -> 'b) -> 'r list -> [ `Ok of ('a, 'b) t | `Duplicate_keys of 'a list ]

Applies the get_key and get_data functions to the 'r list to create the initial keys and values, respectively, for the new hashtable.

create_mapped get_key get_data [x1;...;xn]
= of_alist [get_key x1, get_data x1; ...; get_key xn, get_data xn]

Example:

        let h =
          Hashtbl.create_mapped (module Int)
            ~get_key:(fun x -> x)
            ~get_data:(fun x -> x + 1)
           [1; 2; 3];;
        val h : [ `Duplicate_keys of int list | `Ok of (int, int) Hashtbl.t ] = `Ok <abstr>

        let h =
          match h with
          | `Ok x -> x
          | `Duplicate_keys _ -> failwith ""
        in
        Hashtbl.find_exn h 1;;
        - : int = 2
val create_with_key : ?growth_allowed:bool -> ?size:int -> (module Base__.Hashtbl_intf.Key with type t = 'a) -> get_key:('r -> 'a) -> 'r list -> [ `Ok of ('a, 'r) t | `Duplicate_keys of 'a list ]
create_with_key ~get_key [x1;...;xn]
= of_alist [get_key x1, x1; ...; get_key xn, xn] 
val create_with_key_or_error : ?growth_allowed:bool -> ?size:int -> (module Base__.Hashtbl_intf.Key with type t = 'a) -> get_key:('r -> 'a) -> 'r list -> ('a, 'r) t Base.Or_error.t
val create_with_key_exn : ?growth_allowed:bool -> ?size:int -> (module Base__.Hashtbl_intf.Key with type t = 'a) -> get_key:('r -> 'a) -> 'r list -> ('a, 'r) t
val group : ?growth_allowed:bool -> ?size:int -> (module Base__.Hashtbl_intf.Key with type t = 'a) -> get_key:('r -> 'a) -> get_data:('r -> 'b) -> combine:('b -> 'b -> 'b) -> 'r list -> ('a, 'b) t

Like create_mapped, applies the get_key and get_data functions to the 'r list to create the initial keys and values, respectively, for the new hashtable -- and then, like add_multi, folds together values belonging to the same keys. Here, though, the function used for the folding is given by combine (instead of just being a cons).

Example:

         Hashtbl.group (module Int)
           ~get_key:(fun x -> x / 2)
           ~get_data:(fun x -> x)
           ~combine:(fun x y -> x * y)
            [ 1; 2; 3; 4]
         |> Hashtbl.to_alist;;
         - : (int * int) list = [(2, 4); (1, 6); (0, 1)]

Accessors

type 'a key = 'a
val sexp_of_key : ('a, _) t -> 'a key -> Base.Sexp.t
val clear : (_, _) t -> unit
val copy : ('a, 'b) t -> ('a, 'b) t
val fold : ('a, 'b) t -> init:'c -> f:(key:'a key -> data:'b -> 'c -> 'c) -> 'c

Attempting to modify (set, remove, etc.) the hashtable during iteration (fold, iter, iter_keys, iteri) will raise an exception.

val iter_keys : ('a, _) t -> f:('a key -> unit) -> unit
val iter : (_, 'b) t -> f:('b -> unit) -> unit
val iteri : ('a, 'b) t -> f:(key:'a key -> data:'b -> unit) -> unit

Iterates over both keys and values.

Example:

      let h = Hashtbl.of_alist_exn (module Int) [(1, 4); (5, 6)] in
      Hashtbl.iteri h ~f:(fun ~key ~data ->
        print_endline (Printf.sprintf "%d-%d" key data));;
      1-4
      5-6
      - : unit = ()
val existsi : ('a, 'b) t -> f:(key:'a key -> data:'b -> bool) -> bool
val exists : (_, 'b) t -> f:('b -> bool) -> bool
val for_alli : ('a, 'b) t -> f:(key:'a key -> data:'b -> bool) -> bool
val for_all : (_, 'b) t -> f:('b -> bool) -> bool
val counti : ('a, 'b) t -> f:(key:'a key -> data:'b -> bool) -> int
val count : (_, 'b) t -> f:('b -> bool) -> int
val length : (_, _) t -> int
val is_empty : (_, _) t -> bool
val mem : ('a, _) t -> 'a key -> bool
val remove : ('a, _) t -> 'a key -> unit
val set : ('a, 'b) t -> key:'a key -> data:'b -> unit

Sets the given key to data.

val add : ('a, 'b) t -> key:'a key -> data:'b -> [ `Ok | `Duplicate ]

add and add_exn leave the table unchanged if the key was already present.

val add_exn : ('a, 'b) t -> key:'a key -> data:'b -> unit
val change : ('a, 'b) t -> 'a key -> f:('b option -> 'b option) -> unit

change t key ~f changes t's value for key to be f (find t key).

val update : ('a, 'b) t -> 'a key -> f:('b option -> 'b) -> unit

update t key ~f is change t key ~f:(fun o -> Some (f o)).

val map : ('a, 'b) t -> f:('b -> 'c) -> ('a, 'c) t

map t f returns a new table with values replaced by the result of applying f to the current values.

Example:

      let h = Hashtbl.of_alist_exn (module Int) [(1, 4); (5, 6)] in
      let h' = Hashtbl.map h ~f:(fun x -> x * 2) in
      Hashtbl.to_alist h';;
      - : (int * int) list = [(5, 12); (1, 8)]
val mapi : ('a, 'b) t -> f:(key:'a key -> data:'b -> 'c) -> ('a, 'c) t

Like map, but the function f takes both key and data as arguments.

val filter_map : ('a, 'b) t -> f:('b -> 'c option) -> ('a, 'c) t

Returns a new table by filtering the given table's values by f: the keys for which f applied to the current value returns Some are kept, and those for which it returns None are discarded.

Example:

      let h = Hashtbl.of_alist_exn (module Int) [(1, 4); (5, 6)] in
      Hashtbl.filter_map h ~f:(fun x -> if x > 5 then Some x else None)
      |> Hashtbl.to_alist;;
      - : (int * int) list = [(5, 6)]
val filter_mapi : ('a, 'b) t -> f:(key:'a key -> data:'b -> 'c option) -> ('a, 'c) t

Like filter_map, but the function f takes both key and data as arguments.

val filter_keys : ('a, 'b) t -> f:('a key -> bool) -> ('a, 'b) t
val filter : ('a, 'b) t -> f:('b -> bool) -> ('a, 'b) t
val filteri : ('a, 'b) t -> f:(key:'a key -> data:'b -> bool) -> ('a, 'b) t
val partition_map : ('a, 'b) t -> f:('b -> [ `Fst of 'c | `Snd of 'd ]) -> ('a, 'c) t * ('a, 'd) t

Returns new tables with bound values partitioned by f applied to the bound values.

val partition_mapi : ('a, 'b) t -> f:(key:'a key -> data:'b -> [ `Fst of 'c | `Snd of 'd ]) -> ('a, 'c) t * ('a, 'd) t

Like partition_map, but the function f takes both key and data as arguments.

val partition_tf : ('a, 'b) t -> f:('b -> bool) -> ('a, 'b) t * ('a, 'b) t

Returns a pair of tables (t1, t2), where t1 contains all the elements of the initial table which satisfy the predicate f, and t2 contains the rest.

val partitioni_tf : ('a, 'b) t -> f:(key:'a key -> data:'b -> bool) -> ('a, 'b) t * ('a, 'b) t

Like partition_tf, but the function f takes both key and data as arguments.

val find_or_add : ('a, 'b) t -> 'a key -> default:(unit -> 'b) -> 'b

find_or_add t k ~default returns the data associated with key k if it is in the table t, and otherwise assigns k the value returned by default ().

val findi_or_add : ('a, 'b) t -> 'a key -> default:('a key -> 'b) -> 'b

Like find_or_add but default takes the key as an argument.

val find : ('a, 'b) t -> 'a key -> 'b option

find t k returns Some (the current binding) of k in t, or None if no such binding exists.

val find_exn : ('a, 'b) t -> 'a key -> 'b

find_exn t k returns the current binding of k in t, or raises Caml.Not_found or Not_found_s if no such binding exists.

val find_and_call : ('a, 'b) t -> 'a key -> if_found:('b -> 'c) -> if_not_found:('a key -> 'c) -> 'c

find_and_call t k ~if_found ~if_not_found

is equivalent to:

match find t k with Some v -> if_found v | None -> if_not_found k

except that it doesn't allocate the option.

val findi_and_call : ('a, 'b) t -> 'a key -> if_found:(key:'a key -> data:'b -> 'c) -> if_not_found:('a key -> 'c) -> 'c
val find_and_remove : ('a, 'b) t -> 'a key -> 'b option

find_and_remove t k returns Some (the current binding) of k in t and removes it, or None is no such binding exists.

val merge : ('k, 'a) t -> ('k, 'b) t -> f: (key:'k key -> [ `Left of 'a | `Right of 'b | `Both of 'a * 'b ] -> 'c option) -> ('k, 'c) t

Merges two hashtables.

The result of merge f h1 h2 has as keys the set of all k in the union of the sets of keys of h1 and h2 for which d(k) is not None, where:

d(k) =

  • f ~key:k (Some d1) None if k in h1 maps to d1, and h2 does not have data for k;
  • f ~key:k None (Some d2) if k in h2 maps to d2, and h1 does not have data for k;
  • f ~key:k (Some d1) (Some d2) otherwise, where k in h1 maps to d1 and k in h2 maps to d2.

Each key k is mapped to a single piece of data x, where d(k) = Some x.

Example:

      let h1 = Hashtbl.of_alist_exn (module Int) [(1, 5); (2, 3232)] in
      let h2 = Hashtbl.of_alist_exn (module Int) [(1, 3)] in
      Hashtbl.merge h1 h2 ~f:(fun ~key:_ -> function
        | `Left x -> Some (`Left x)
        | `Right x -> Some (`Right x)
        | `Both (x, y) -> if x=y then None else Some (`Both (x,y))
      ) |> Hashtbl.to_alist;;
      - : (int * [> `Both of int * int | `Left of int | `Right of int ]) list =
      [(2, `Left 3232); (1, `Both (5, 3))]
type 'a merge_into_action =
  1. | Remove
  2. | Set_to of 'a

Every key in src will be removed or set in dst according to the return value of f.

val merge_into : src:('k, 'a) t -> dst:('k, 'b) t -> f:(key:'k key -> 'a -> 'b option -> 'b merge_into_action) -> unit
val keys : ('a, _) t -> 'a key list

Returns the list of all keys for given hashtable.

val data : (_, 'b) t -> 'b list

Returns the list of all data for given hashtable.

val filter_keys_inplace : ('a, _) t -> f:('a key -> bool) -> unit

filter_inplace t ~f removes all the elements from t that don't satisfy f.

val filter_inplace : (_, 'b) t -> f:('b -> bool) -> unit
val filteri_inplace : ('a, 'b) t -> f:(key:'a key -> data:'b -> bool) -> unit
val map_inplace : (_, 'b) t -> f:('b -> 'b) -> unit

map_inplace t ~f applies f to all elements in t, transforming them in place.

val mapi_inplace : ('a, 'b) t -> f:(key:'a key -> data:'b -> 'b) -> unit
val filter_map_inplace : (_, 'b) t -> f:('b -> 'b option) -> unit

filter_map_inplace combines the effects of map_inplace and filter_inplace.

val filter_mapi_inplace : ('a, 'b) t -> f:(key:'a key -> data:'b -> 'b option) -> unit
val equal : ('a, 'b) t -> ('a, 'b) t -> ('b -> 'b -> bool) -> bool

equal t1 t2 f and similar t1 t2 f both return true iff t1 and t2 have the same keys and for all keys k, f (find_exn t1 k) (find_exn t2 k). equal and similar only differ in their types.

val similar : ('a, 'b1) t -> ('a, 'b2) t -> ('b1 -> 'b2 -> bool) -> bool
val to_alist : ('a, 'b) t -> ('a key * 'b) list

Returns the list of all (key, data) pairs for given hashtable.

val validate : name:('a key -> string) -> 'b Base.Validate.check -> ('a, 'b) t Base.Validate.check
val incr : ?by:int -> ?remove_if_zero:bool -> ('a, int) t -> 'a key -> unit

remove_if_zero's default is false.

val decr : ?by:int -> ?remove_if_zero:bool -> ('a, int) t -> 'a key -> unit
val add_multi : ('a, 'b list) t -> key:'a key -> data:'b -> unit

add_multi t ~key ~data if key is present in the table then cons data on the list, otherwise add key with a single element list.

val remove_multi : ('a, _ list) t -> 'a key -> unit

remove_multi t key updates the table, removing the head of the list bound to key. If the list has only one element (or is empty) then the binding is removed.

val find_multi : ('a, 'b list) t -> 'a key -> 'b list

find_multi t key returns the empty list if key is not present in the table, returns t's values for key otherwise.

val hashable_s : ('key, _) t -> (module Base__.Hashtbl_intf.Key with type t = 'key)
include Base.Invariant.S2 with type ('a, 'b) t := ('a, 'b) t
val invariant : ('a -> unit) -> ('b -> unit) -> ('a, 'b) t -> unit
module Using_hashable : sig ... end
module Poly : sig ... end
module type Key_plain = Core_kernel.Hashtbl_intf.Key_plain
module type Key_binable = Core_kernel.Hashtbl_intf.Key_binable
module type S_plain = Core_kernel.Hashtbl_intf.S_plain with type ('a, 'b) hashtbl = ('a, 'b) t
module type S = Core_kernel.Hashtbl_intf.S with type ('a, 'b) hashtbl = ('a, 'b) t
module type S_binable = Core_kernel.Hashtbl_intf.S_binable with type ('a, 'b) hashtbl = ('a, 'b) t
module Make_plain (Key : Key_plain) : S_plain with type key = Key.t
module Make (Key : Key) : S with type key = Key.t
module Make_binable (Key : Key_binable) : S_binable with type key = Key.t
module M (K : Base.T.T) : sig ... end
module Hashable = Base.Hashable
val hashable : ('key, _) t -> 'key Hashable.t
module type For_deriving = Core_kernel.Hashtbl_intf.For_deriving
include For_deriving with type ('a, 'b) t := ('a, 'b) t
module type Sexp_of_m = sig ... end
module type M_of_sexp = sig ... end
val sexp_of_m__t : (module Sexp_of_m with type t = 'k) -> ('v -> Base.Sexp.t) -> ('k, 'v) t -> Base.Sexp.t
val m__t_of_sexp : (module M_of_sexp with type t = 'k) -> (Base.Sexp.t -> 'v) -> Base.Sexp.t -> ('k, 'v) t
val iter_vals : (_, 'b) t -> f:('b -> Base.Unit.t) -> Base.Unit.t
  • deprecated [since 2016-04] Use iter instead
val replace : ('a, 'b) t -> key:'a key -> data:'b -> Base.Unit.t
  • deprecated [since 2015-10] Use set instead
val replace_all : (_, 'b) t -> f:('b -> 'b) -> Base.Unit.t
  • deprecated [since 2016-02] Use map_inplace instead
val replace_alli : ('a, 'b) t -> f:(key:'a key -> data:'b -> 'b) -> Base.Unit.t
  • deprecated [since 2016-02] Use mapi_inplace instead
val filter_replace_all : (_, 'b) t -> f:('b -> 'b Base.Option.t) -> Base.Unit.t
  • deprecated [since 2016-02] Use filter_map_inplace instead
val filter_replace_alli : ('a, 'b) t -> f:(key:'a key -> data:'b -> 'b Base.Option.t) -> Base.Unit.t
  • deprecated [since 2016-02] Use filter_mapi_inplace instead
val resize : (_, _) t -> int -> unit

resize t size ensures that t can hold at least size entries without resizing (again), provided that t has growth enabled. This is useful for sizing global tables during application initialization, to avoid subsequent, expensive growth online. See Immediate.String.resize, for example.

val on_grow : before:(unit -> 'a) -> after:('a -> old_capacity:int -> new_capacity:int -> unit) -> unit

on_grow ~before ~after allows you to connect higher level loggers to the point where these hashtbls grow. before is called before the table grows, and after after it. This permits you to e.g. measure the time elapsed between the two.

This is only meant for debugging and profiling, e.g. note that once a callback is installed, there is no way to remove it.

OCaml

Innovation. Community. Security.