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

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