###
7.3.2.1 組み込み codec (built-in codec)

Python では、処理速度を高めるために C で書かれた一そろいの codec を提供しています。これらの codec は全て以下の関数を介して 直接利用できます。

以下の API の多くが、 encoding と errors という二つの 引数をとります。これらのパラメタは、組み込みの Unicode オブジェクト コンストラクタである `unicode()` における同名のパラメタと同じ セマンティクスになっています。

encoding を `NULL` にすると、デフォルトエンコーディング である ASCIIを使います。ファイルシステムに関する関数の呼び出し では、ファイル名に対するエンコーディングとして `Py_FileSystemDefaultEncoding` を使わねばなりません。 この変数は読み出し専用の変数として扱わねばなりません: この変数は、あるシステムによっては静的な文字列に対するポインタで あったり、また別のシステムでは、例えばアプリケーションが setlocale を読んだときなどに変わったりもします。

errors で指定するエラー処理もまた、 `NULL` を指定できます。 `NULL` を指定すると、codec で定義されているデフォルト処理の使用を 意味します。全ての組み込み codec で、デフォルトのエラー処理は ``strict'' (`ValueError` を送出する) になっています。

個々の codec は全て同様のインタフェースを使っています。個別の codec の説明では、説明を簡単にするために以下の汎用のインタフェースとの 違いだけを説明しています。

以下は汎用 codec の API です:

PyObject* `PyUnicode_Decode`( | const char *s, int size, const char *encoding, const char *errors)

  戻り値: 新たな参照.
  何らかのエンコード方式でエンコードされた、 size バイトの 文字列 s をデコードして Unicode オブジェクトを生成します。 encoding と errors は、組み込み関数 unicode() の同名の パラメタと同じ意味を持ちます。使用する codec の検索は、 Python の codec レジストリを使って行います。codec が例外を送出した場合には `NULL` を返します。

PyObject* `PyUnicode_Encode`( | const Py_UNICODE *s, int size, const char *encoding, const char *errors)

  戻り値: 新たな参照.
  size で指定されたサイズの `Py_UNICODE` バッファを エンコードした Python 文字列オブジェクトを返します。 encoding および errors は Unicode 型の `encode()` メソッドに与える同名のパラメタと 同じ意味を持ちます。使用する codec の検索は、 Python の codec レジストリを使って行います。codec が例外を送出した場合には `NULL` を返します。

PyObject* `PyUnicode_AsEncodedString`( | PyObject *unicode, const char *encoding, const char *errors)

  戻り値: 新たな参照.
  Unicode オブジェクトをエンコードし、その結果を Python 文字列 オブジェクトとして返します。encoding および errors は Unicode 型の `encode()` メソッドに与える同名のパラメタと 同じ意味を持ちます。使用する codec の検索は、 Python の codec レジストリを使って行います。codec が例外を送出した場合には `NULL` を返します。

以下は UTF-8 codec の APIです:

PyObject* `PyUnicode_DecodeUTF8`( | const char *s, int size, const char *errors)

  戻り値: 新たな参照.
  UTF-8 でエンコードされた size バイトの文字列 s から Unicode オブジェクトを生成します。codec が例外を送出した場合には `NULL` を返します。

PyObject* `PyUnicode_EncodeUTF8`( | const Py_UNICODE *s, int size, const char *errors)

  戻り値: 新たな参照.
  size で指定された長さを持つ `Py_UNICODE` 型バッファを UTF-8 でエンコードし、 Python 文字列オブジェクトにして返します。 codec が例外を送出した場合には `NULL` を返します。

PyObject* `PyUnicode_AsUTF8String`( | PyObject *unicode)

  戻り値: 新たな参照.
  UTF-8 で Unicode オブジェクトをエンコードし、結果を Python 文字列 オブジェクトとして返します。エラー処理は ``strict'' です。 codec が例外を送出した場合には`NULL` を返します。

以下は UTF-16 codec の APIです:

PyObject* `PyUnicode_DecodeUTF16`( | const char *s, int size, const char *errors, int *byteorder)

  戻り値: 新たな参照.
  UTF-16 でエンコードされたバッファ s から size バイト デコードして、結果を Unicode オブジェクトで返します。 errors は (`NULL`でない場合) エラー処理方法を定義します。 デフォルト値は ``strict'' です。

  byteorder が `NULL`でない場合、デコード機構は以下の ように指定されたバイト整列 (byte order) に従ってデコードを開始 します:

         *byteorder == -1: リトルエンディアン
         *byteorder == 0:  ネイティブ
         *byteorder == 1:  ビッグエンディアン

  その後、入力データ中に見つかった全てのバイト整列マーカ (byte order mark, BOM) に従って、バイト整列を切り替えます。 BOM はデコード結果の Unicode 文字列中にはコピーされません。 デコードを完結した後、*byteorder は入力データの終点現在に おけるバイト整列に設定されます。

  byteorder が `NULL`の場合、 codec はネイティブバイト整列の モードで開始します。

  codec が例外を送出した場合には`NULL` を返します。

PyObject* `PyUnicode_EncodeUTF16`( | const Py_UNICODE *s, int size, const char *errors, int byteorder)

  戻り値: 新たな参照.

  s 中の Unicode データを UTF-16 でエンコードした結果が入っている Python 文字列オブジェクトを返します。 byteorder が `0` でない場合、出力は以下のバイト整列 指定に従って書き出されます:

         byteorder == -1: リトルエンディアン
         byteorder == 0:  ネイティブ (BOM マーカを書き出します)
         byteorder == 1:  ビッグエンディアン

  バイトオーダが `0` の場合、出力結果となる文字列は常に Unicode BOM マーカ (U+FEFF) で始まります。それ以外のモードでは、 BOM マーカを頭につけません。

  `Py_UNICODE` データは UCS-2 に縮小された UTF-16 として解釈 されることに注意してください。このトリックによって、API を傷つける ことなく、完全な UTF-16 機能を後で追加できます。

  codec が例外を送出した場合には`NULL` を返します。

PyObject* `PyUnicode_AsUTF16String`( | PyObject *unicode)

  戻り値: 新たな参照.
  ネイティブバイトオーダの UTF-16 でエンコードされた Python 文字列を返します。 文字列は常に BOM マーカから始まります。エラー処理は ``strict'' です。 codec が例外を送出した場合には`NULL` を返します。

以下は ``Unicode Escape'' codec の APIです:

PyObject* `PyUnicode_DecodeUnicodeEscape`( | const char *s, int size, const char *errors)

  戻り値: 新たな参照.
  Unicode-Escape でエンコードされた size バイトの文字列 s から Unicode オブジェクトを生成します。codec が例外を送出した場合には `NULL` を返します。

PyObject* `PyUnicode_EncodeUnicodeEscape`( | const Py_UNICODE *s, int size, const char *errors)

  戻り値: 新たな参照.
  size で指定された長さを持つ `Py_UNICODE` 型バッファを Unicode-Escape でエンコードし、 Python 文字列オブジェクトにして返します。 codec が例外を送出した場合には `NULL` を返します。

PyObject* `PyUnicode_AsUnicodeEscapeString`( | PyObject *unicode)

  戻り値: 新たな参照.
  Unicode-Escape で Unicode オブジェクトをエンコードし、結果を Python 文字列オブジェクトとして返します。エラー処理は ``strict'' です。 codec が例外を送出した場合には`NULL` を返します。

以下は ``Raw Unicode Escape'' codec の APIです:

PyObject* `PyUnicode_DecodeRawUnicodeEscape`( | const char *s, int size, const char *errors)

  戻り値: 新たな参照.
  Raw-Unicode-Escape でエンコードされた size バイトの文字列 s から Unicode オブジェクトを生成します。codec が例外を送出した場合には `NULL` を返します。

PyObject* `PyUnicode_EncodeRawUnicodeEscape`( | const Py_UNICODE *s, int size, const char *errors)

  戻り値: 新たな参照.
  size で指定された長さを持つ `Py_UNICODE` 型バッファを Raw-Unicode-Escape でエンコードし、 Python 文字列オブジェクトにして返します。 codec が例外を送出した場合には `NULL` を返します。

PyObject* `PyUnicode_AsRawUnicodeEscapeString`( | PyObject *unicode)

  戻り値: 新たな参照.
  Raw-Unicode-Escape で Unicode オブジェクトをエンコードし、結果を Python 文字列オブジェクトとして返します。エラー処理は ``strict'' です。 codec が例外を送出した場合には`NULL` を返します。

以下は Latin-1 codec の APIです: Latin-1 は、 Unicode 序数の最初の 256 個に対応し、 エンコード時にはこの 256 個だけを受理します。

PyObject* `PyUnicode_DecodeLatin1`( | const char *s, int size, const char *errors)

  戻り値: 新たな参照.
  Latin-1 でエンコードされた size バイトの文字列 s から Unicode オブジェクトを生成します。codec が例外を送出した場合には `NULL` を返します。

PyObject* `PyUnicode_EncodeLatin1`( | const Py_UNICODE *s, int size, const char *errors)

  戻り値: 新たな参照.
  size で指定された長さを持つ `Py_UNICODE` 型バッファを Latin-1 でエンコードし、 Python 文字列オブジェクトにして返します。 codec が例外を送出した場合には `NULL` を返します。

PyObject* `PyUnicode_AsLatin1String`( | PyObject *unicode)

  戻り値: 新たな参照.
  Latin-1 で Unicode オブジェクトをエンコードし、結果を Python 文字列 オブジェクトとして返します。エラー処理は ``strict'' です。 codec が例外を送出した場合には`NULL` を返します。

以下は ASCII codec の APIです: 7 ビットの ASCII データだけを受理します。その他のコードは エラーになります。

PyObject* `PyUnicode_DecodeASCII`( | const char *s, int size, const char *errors)

  戻り値: 新たな参照.
  ASCII でエンコードされた size バイトの文字列 s から Unicode オブジェクトを生成します。codec が例外を送出した場合には `NULL` を返します。

PyObject* `PyUnicode_EncodeASCII`( | const Py_UNICODE *s, int size, const char *errors)

  戻り値: 新たな参照.
  size で指定された長さを持つ `Py_UNICODE` 型バッファを ASCII でエンコードし、 Python 文字列オブジェクトにして返します。 codec が例外を送出した場合には `NULL` を返します。

PyObject* `PyUnicode_AsASCIIString`( | PyObject *unicode)

  戻り値: 新たな参照.
  ASCII で Unicode オブジェクトをエンコードし、結果を Python 文字列 オブジェクトとして返します。エラー処理は ``strict'' です。 codec が例外を送出した場合には`NULL` を返します。

以下は mapping codec の APIです:

この codec は、多くの様々な codec を実装する際に使われるという点で 特殊な codec です (実際、`encodings` パッケージに入っている 標準 codecs のほとんどは、この codec を使っています)。 この codec は、文字のエンコードやデコードにマップ型 (mapping) を使います。

デコード用のマップ型は、文字列型の字列一組みを、 Unicode 型の字列一組、 整数 (Unicode 序数として解釈されます) または `None` ("定義されていない 対応付け(undefined mapping)" を意味し、エラーを引き起こします) の いずれかに対応付けなければなりません。

デコード用のマップ型は、Unicode 型の字列一組みを、 string 型の字列一組、 整数 (Latin-1 序数として解釈されます) または `None` ("定義されていない 対応付け(undefined mapping)" を意味し、エラーを引き起こします) の いずれかに対応付けなければなりません。

マップ型オブジェクトは、 `__getitem__` マップ型インタフェース をサポートしなければなりません。

ある文字の検索が LookupError によって失敗すると、その文字は そのままコピーされます。すなわち、その文字の序数値がそれぞれ Unicode または Latin-1 として解釈されます。このため、codec を 実現するマップ型に入れる必要がある対応付け関係は、ある文字を別の コード点に対応付けるものだけです。

PyObject* `PyUnicode_DecodeCharmap`( | const char *s, int size, PyObject *mapping, const char *errors)

  戻り値: 新たな参照.

  エンコードされた size バイトの文字列 s から mapping に指定されたオブジェクトを使って Unicode オブジェクトを 生成します。codec が例外を送出した場合には`NULL` を返します。

PyObject* `PyUnicode_EncodeCharmap`( | const Py_UNICODE *s, int size, PyObject *mapping, const char *errors)

  戻り値: 新たな参照.
  size で指定された長さを持つ `Py_UNICODE` 型バッファを mapping に指定されたオブジェクトを使ってエンコードし、 Python 文字列オブジェクトにして返します。 codec が例外を送出した場合には `NULL` を返します。

PyObject* `PyUnicode_AsCharmapString`( | PyObject *unicode, PyObject *mapping)

  戻り値: 新たな参照.
  Unicode オブジェクトを mapping に指定されたオブジェクトを使って エンコードし、結果を Python 文字列オブジェクトとして返します。 エラー処理は ``strict'' です。 codec が例外を送出した場合には`NULL` を返します。

以下の codec API は Unicode から Unicode への対応付けを行う 特殊なものです。

PyObject* `PyUnicode_TranslateCharmap`( | const Py_UNICODE *s, int size, PyObject *table, const char *errors)

  戻り値: 新たな参照.
  で 指定された長さを持つ `Py_UNICODE` バッファを、 文字変換マップ table を適用して変換し、変換結果を Unicode オブジェクトで返します。codec が例外を発行した場合には `NULL` を返します。

  対応付けを行う table は、 Unicode 序数を表す整数を Unicode 序数を表す整数または `None` に対応付けます。 (`None` の場合にはその文字を削除します)

  対応付けテーブルが提供する必要があるメソッドは `__getitem__()` インタフェースだけです; 従って、辞書や 配列型を使ってもうまく動作します。対応付けを行っていない (`LookupError` を起こすような) 文字序数に対しては、 変換は行わず、そのままコピーします。

以下は MBCS codec の API です。この codec は現在のところ、 Windows 上だけで利用でき、変換の実装には Win32 MBCS 変換機構 (Win32 MBCS converter) を使っています。 MBCS (または DBCS) はエンコード方式の種類 (class) を表す言葉で、単一の エンコード方式を表すわけでなないので注意してください。 利用されるエンコード方式 (target encoding) は、 codec を動作 させているマシン上のユーザ設定で定義されています。

PyObject* `PyUnicode_DecodeMBCS`( | const char *s, int size, const char *errors)

  戻り値: 新たな参照.
  MBCS でエンコードされた size バイトの文字列 s から Unicode オブジェクトを生成します。codec が例外を送出した場合には `NULL` を返します。

PyObject* `PyUnicode_EncodeMBCS`( | const Py_UNICODE *s, int size, const char *errors)

  戻り値: 新たな参照.
  size で指定された長さを持つ `Py_UNICODE` 型バッファを MBCS でエンコードし、 Python 文字列オブジェクトにして返します。 codec が例外を送出した場合には `NULL` を返します。

PyObject* `PyUnicode_AsMBCSString`( | PyObject *unicode)

  戻り値: 新たな参照.
  MBCS で Unicode オブジェクトをエンコードし、結果を Python 文字列 オブジェクトとして返します。エラー処理は ``strict'' です。 codec が例外を送出した場合には`NULL` を返します。