package ppx_hash

  1. Overview
  2. Docs
A ppx rewriter that generates hash functions from type expressions and definitions

Install

Dune Dependency

Authors

Maintainers

Sources

v0.17.0.tar.gz
sha256=8c8acae276a349d412eab9112cc3afa996d26ad4a01f2882121fc0adee0dd05e

Description

Part of the Jane Street's PPX rewriters collection.

Published: 23 May 2024

README

ppx_hash

A ppx writer that generates hash functions from type expressions and definitions.

Syntax

Type definitions: [@@deriving hash] Expressions: [%hash_fold: TYPE] and [%hash: TYPE] Types, record fields: [@hash.ignore]

Basic usage

    type t = {
      s : string;
      x : (int * bool) list;
    }
    [@@deriving hash]

This will generate a function hash_fold_t : Hash.state -> t -> Hash.state.

Where Hash is Ppx_hash_lib.Std.Hash.

The generated function follows the structure of the type; allowing user overrides at every level. This is in contrast to ocaml's builtin polymorphic hashing Hashtbl.hash which ignores user overrides.

Also generated is a direct hash-function hash : t -> Hash.hash_value. This function will be named hash_<T> when != "t".

The direct hash function is the one suitable for Hashable.Make.

Signature

In a module signature, type t [@@deriving hash] will add both hash_fold_t and hash (or hash_<T>) to the signature.

Hashing without a type definition

A folding hash function is accessed/created as [%hash_fold: TYPE]. A direct hash function is accessed/created as [%hash: TYPE].

Ignoring part of types

Types can be annotated with [@hash.ignore] so that they are not incorporated into the computed hash value.

  type second_only = (string [@hash.ignore]) * int [@@deriving hash]

Mutable records fields must have such an annotation.

    type t = {
      mutable s : string [@hash.ignore];
      x : (int * bool) list;
    }
    [@@deriving hash]

Special support for ppx_compare

The annotation [@compare.ignore] (and [@ignore]) implies [@hash.ignore], in order to preserve the invariant that compare x y = 0 implies hash x = hash y.

Adapting code to ppx_hash

So long as all types in support hashing, the following common pattern:

    module T = struct
      type t = <TYPE-EXP> [@@deriving compare, sexp]
      let hash = Hashtbl.hash
    end
    include T
    include Hashable.Make (T)

Can this be written as:

    module T = struct
      type t = <TYPE-EXP> [@@deriving compare, hash, sexp]
    end
    include T
    include Hashable.Make (T)

More information

ppx/ppx_hash/doc/design.notes
ppx/ppx_hash/runtime-lib/make_std.ml

Dependencies (7)

  1. ppxlib >= "0.28.0"
  2. dune >= "3.11.0"
  3. ppxlib_jane >= "v0.17" & < "v0.18"
  4. ppx_sexp_conv >= "v0.17" & < "v0.18"
  5. ppx_compare >= "v0.17" & < "v0.18"
  6. base >= "v0.17" & < "v0.18"
  7. ocaml >= "5.1.0"

Dev Dependencies

None

Used by (13)

  1. boomerang
  2. colibri2
  3. commons >= "1.8.0"
  4. coq-serapi >= "8.16.0+0.16.0"
  5. core >= "v0.17.0"
  6. core-and-more
  7. data-encoding >= "0.6"
  8. farith
  9. nsq >= "0.5.0" & < "0.5.2"
  10. opine
  11. ppx_bap < "v0.14.0"
  12. ppx_base >= "v0.17.0"
  13. pyre-ast

Conflicts

None

OCaml

Innovation. Community. Security.