編解碼器註冊表和支援函式
************************

int PyCodec_Register(PyObject *search_function)
    * 為 穩定 ABI 的一部分.*

   註冊一個新的編解碼器搜索函式。

   作為副作用 (side effect)，這會嘗試載入 "encodings"（如果尚未完成）
   ，以確保它始終位於搜索函式列表中的第一個。

int PyCodec_Unregister(PyObject *search_function)
    * 為 穩定 ABI 的一部分 自 3.10 版本開始.*

   取消註冊編解碼器搜索函式並清除註冊表 (registry) 的快取。如果搜索函
   式並未被註冊，則不執行任何操作。成功回傳 0，發生錯誤時會引發例外並
   回傳 -1。

   在 3.10 版被加入.

int PyCodec_KnownEncoding(const char *encoding)
    * 為 穩定 ABI 的一部分.*

   回傳 "1" 或 "0"，具體取決於是否有給定 *encoding* 的已註冊編解碼器。
   這個函式總會成功。

PyObject *PyCodec_Encode(PyObject *object, const char *encoding, const char *errors)
    *回傳值：新的參照。** 為 穩定 ABI 的一部分.*

   基於泛用編解碼器的編碼 API。

   *object* 被傳遞給以給定 *encoding* 所查找到的編碼器函式，並使用以
   *errors* 定義的錯誤處理方法。*errors* 可以設為 "NULL" 來使用編解碼
   器定義的預設方法。如果找不到編碼器，則引發 "LookupError"。

PyObject *PyCodec_Decode(PyObject *object, const char *encoding, const char *errors)
    *回傳值：新的參照。** 為 穩定 ABI 的一部分.*

   基於泛用編解碼器的解碼 API。

   *object* 被傳遞給以給定 *encoding* 所查找到的解碼器函式，並使用以
   *errors* 定義的錯誤處理方法。*errors* 可以設為 "NULL" 來使用編解碼
   器定義的預設方法。如果找不到編碼器，則引發 "LookupError"。


編解碼器查找 API
================

在以下函式中，查找的 *encoding* 字串的所有字元將轉換為小寫，這使得透過
此機制查找的編碼可以不區分大小寫而更有效率。如果未找到編解碼器，則會設
定 "KeyError" 並回傳 "NULL"。

PyObject *PyCodec_Encoder(const char *encoding)
    *回傳值：新的參照。** 為 穩定 ABI 的一部分.*

   取得給定 *encoding* 的編碼器函式。

PyObject *PyCodec_Decoder(const char *encoding)
    *回傳值：新的參照。** 為 穩定 ABI 的一部分.*

   取得給定 *encoding* 的解碼器函式。

PyObject *PyCodec_IncrementalEncoder(const char *encoding, const char *errors)
    *回傳值：新的參照。** 為 穩定 ABI 的一部分.*

   取得給定 *encoding* 的 "IncrementalEncoder" 物件。

PyObject *PyCodec_IncrementalDecoder(const char *encoding, const char *errors)
    *回傳值：新的參照。** 為 穩定 ABI 的一部分.*

   取得給定 *encoding* 的 "IncrementalDecoder" 物件。

PyObject *PyCodec_StreamReader(const char *encoding, PyObject *stream, const char *errors)
    *回傳值：新的參照。** 為 穩定 ABI 的一部分.*

   取得給定 *encoding* 的 "StreamReader" 工廠函式。

PyObject *PyCodec_StreamWriter(const char *encoding, PyObject *stream, const char *errors)
    *回傳值：新的參照。** 為 穩定 ABI 的一部分.*

   取得給定 *encoding* 的 "StreamWriter" 工廠函式。


用於 Unicode 編碼錯誤處理程式的註冊 API
=======================================

int PyCodec_RegisterError(const char *name, PyObject *error)
    * 為 穩定 ABI 的一部分.*

   在給定的 *name* 下註冊錯誤處理回呼 (callback) 函式 *error*。當編解
   碼器遇到無法編碼的字元/無法解碼的位元組並且 *name* 被指定為呼叫編碼
   /解碼函式時的錯誤參數時，將呼叫此回呼函式。

   回呼取得單個引數，即 "UnicodeEncodeError"、"UnicodeDecodeError" 或
   "UnicodeTranslateError" 的實例，其中包含關於有問題的字元或位元組序
   列及其在原始字串中偏移量的資訊（有關取得此資訊的函式，請參閱
   Unicode Exception Objects）。回呼必須引發給定的例外，或者回傳一個包
   含有問題序列的替換的二元組 (two-item tuple)，以及一個代表原始字串中
   應該被恢復的編碼/解碼偏移量的整數。

   成功時回傳 "0"，錯誤時回傳 "-1"。

PyObject *PyCodec_LookupError(const char *name)
    *回傳值：新的參照。** 為 穩定 ABI 的一部分.*

   查找 *name* 下已註冊的錯誤處理回呼函式。作為一種特殊情況，可以傳遞
   "NULL"，在這種情況下，將回傳 "strict" 的錯誤處理回呼。

PyObject *PyCodec_StrictErrors(PyObject *exc)
    *回傳值：總是為 NULL。** 為 穩定 ABI 的一部分.*

   引發 *exc* 作為例外。

PyObject *PyCodec_IgnoreErrors(PyObject *exc)
    *回傳值：新的參照。** 為 穩定 ABI 的一部分.*

   忽略 unicode 錯誤，跳過錯誤的輸入。

PyObject *PyCodec_ReplaceErrors(PyObject *exc)
    *回傳值：新的參照。** 為 穩定 ABI 的一部分.*

   將 unicode 編碼錯誤替換為 "?" 或 "U+FFFD"。

PyObject *PyCodec_XMLCharRefReplaceErrors(PyObject *exc)
    *回傳值：新的參照。** 為 穩定 ABI 的一部分.*

   將 unicode 編碼錯誤替換為 XML 字元參照。

PyObject *PyCodec_BackslashReplaceErrors(PyObject *exc)
    *回傳值：新的參照。** 為 穩定 ABI 的一部分.*

   將 unicode 編碼錯誤替換為反斜線跳脫（"\x"、"\u" 和 "\U"）。

PyObject *PyCodec_NameReplaceErrors(PyObject *exc)
    *回傳值：新的參照。** 為 穩定 ABI 的一部分 自 3.7 版本開始.*

   將 unicode 編碼錯誤替換為 "\N{...}" 跳脫。

   在 3.5 版被加入.
