# PyHash API

另請參閱 `PyTypeObject.tp_hash` 成員和 數值型別的雜湊。

type Py_hash_t

  雜湊值型別：有符號整數。

  在 3.2 版被加入.

type Py_uhash_t

  雜湊值型別：無符號整數。

  在 3.2 版被加入.

Py_HASH_ALGORITHM

  A numerical value indicating the algorithm for hashing of `str`, `bytes`, and `memoryview`.

  演算式名稱由 `sys.hash_info.algorithm` 公開。

  在 3.4 版被加入.

Py_HASH_FNV
Py_HASH_SIPHASH24
Py_HASH_SIPHASH13

  Numerical values to compare to `Py_HASH_ALGORITHM` to determine which algorithm is used for hashing. The hash algorithm can be configured via the configure `--with-hash-algorithm` option.

  在 3.4 版被加入: 新增 `Py_HASH_FNV` 和 `Py_HASH_SIPHASH24`。

  在 3.11 版被加入: 新增 `Py_HASH_SIPHASH13`。

Py_HASH_CUTOFF

  Buffers of length in range `[1, Py_HASH_CUTOFF)` are hashed using DJBX33A instead of the algorithm described by `Py_HASH_ALGORITHM`.

  - 將 `Py_HASH_CUTOFF` 設為 0 可停用此最佳化。

  - `Py_HASH_CUTOFF` 必須為非負且小於或等於 7。

  32-bit platforms should use a cutoff smaller than 64-bit platforms because it is easier to create colliding strings. A cutoff of 7 on 64-bit platforms and 5 on 32-bit platforms should provide a decent safety margin.

  這對應到 `sys.hash_info.cutoff` 常數。

  在 3.4 版被加入.

PyHASH_MODULUS

  用於數值雜湊方案的梅森質數 (Mersenne prime) `P = 2**n -1`。

  這對應到 `sys.hash_info.modulus` 常數。

  在 3.13 版被加入.

PyHASH_BITS

  `PyHASH_MODULUS` 中 `P` 的指數 `n`。

  在 3.13 版被加入.

PyHASH_MULTIPLIER

  用於字串和其他各種雜湊的質數乘數 (prime multiplier)。

  在 3.13 版被加入.

PyHASH_INF

  正無窮大回傳的雜湊值。

  這對應到 `sys.hash_info.inf` 常數。

  在 3.13 版被加入.

PyHASH_IMAG

  用於複數虛數部分的乘數。

  這對應到 `sys.hash_info.imag` 常數。

  在 3.13 版被加入.

type PyHash_FuncDef

  `PyHash_GetFuncDef()` 所使用的雜湊函式定義。

  Py_hash_t (*const hash)(const void*, Py_ssize_t)

    雜湊函式。

  const char *name

    雜湊函式名稱（UTF-8 編碼字串）。

    這對應到 `sys.hash_info.algorithm` 常數。

  const int hash_bits

    雜湊值的內部大小（以位元為單位）。

    這對應到 `sys.hash_info.hash_bits` 常數。

  const int seed_bits

    Seed 輸入的大小（以位元為單位）。

    這對應到 `sys.hash_info.seed_bits` 常數。

  在 3.4 版被加入.

PyHash_FuncDef *PyHash_GetFuncDef(void)

  取得雜湊函式定義。

  也參考

  PEP 456「安全且可交替使用的雜湊演算法 (Secure and interchangeable hash algorithm)」。

  在 3.4 版被加入.

Py_hash_t Py_HashPointer(const void *ptr)

  雜湊指標值：將指標值作為整數處理（在內部轉型為 `uintptr_t`）。指標不會被取值 (dereference)。

  此函式不會失敗：它不會回傳 `-1`。

  在 3.13 版被加入.

Py_hash_t Py_HashBuffer(const void *ptr, Py_ssize_t len)

  Compute and return the hash value of a buffer of len bytes starting at address ptr. The hash is guaranteed to match that of `bytes`, `memoryview`, and other built-in objects that implement the buffer protocol.

  Use this function to implement hashing for immutable objects whose `tp_richcompare` function compares to another object's buffer.

  len 必須大於或等於 `0`。

  此函式總是會成功執行。

  在 3.14 版被加入.

Py_hash_t PyObject_GenericHash(PyObject *obj)

  泛用雜湊函式，旨在放入型別物件的 `tp_hash` 插槽中。其結果僅取決於物件的識別性。

  在 CPython 中，它等價於 `Py_HashPointer()`。

  在 3.13 版被加入.