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 版被加入.
