Unicode オブジェクトと codec
****************************


Unicode オブジェクト
====================


Unicode 型
----------

以下は Python の Unicode 実装に用いられている基本 Unicode オブジェクト
型です:

Py_UNICODE

   この型は Unicode 序数 (Unicode ordinal) を保持するための基礎単位と
   して、 Python が内部的に使います。 Python のデフォルトのビルドでは
   、 "Py_UNICODE" として 16-bit 型を利用し、 Unicode の値を内部では
   UCS-2 で保持します。 UCS4 版の Python をビルドすることもできます。(
   最近の多くの Linux ディストリビューションでは UCS4 版の Python がつ
   いてきます) UCS4 版ビルドでは "Py_UNICODE" に 32-bit 型を利用し、内
   部では Unicode データを UCS4 で保持します。 "wchar_t" が利用できて
   、 Python の Unicode に関するビルドオプションと一致するときは、
   "Py_UNICODE" は "wchar_t" を typedef でエイリアスされ、ネイティブプ
   ラットフォームに対する互換性を高めます。それ以外のすべてのプラット
   フォームでは、 "Py_UNICODE" は "unsigned short" (UCS2) か "unsigned
   long" (UCS4) の typedef によるエイリアスになります。

UCS2 と UCS4 の Python ビルドの間にはバイナリ互換性がないことに注意し
てください。拡張やインタフェースを書くときには、このことを覚えておいて
ください。

PyUnicodeObject

   この "PyObject" のサブタイプは Unicode オブジェクトを表します。

PyTypeObject PyUnicode_Type

   この "PyTypeObject" のインスタンスは Python の Unicode 型を表します
   。 Python レイヤにおける "unicode" や "types.UnicodeType" と同じオ
   ブジェクトです。

以下の API は実際には C マクロで、Unicode オブジェクト内部の読み出し専
用データに対するチェックやアクセスを高速に行います:

int PyUnicode_Check(PyObject *o)

   *o* が Unicode 文字列型か Unicode 文字列型のサブタイプであるときに
   真を返します。

   バージョン 2.2 で変更: サブタイプを引数にとれるようになりました.

int PyUnicode_CheckExact(PyObject *o)

   *o* が Unicode 文字列型で、かつ Unicode 文字列型のサブタイプでない
   ときに真を返します。

   バージョン 2.2 で追加.

Py_ssize_t PyUnicode_GET_SIZE(PyObject *o)

   オブジェクトのサイズを返します。 *o* は "PyUnicodeObject" でなけれ
   ばなりません (チェックはしません)。

   バージョン 2.5 で変更: この関数は以前は "int" を返していました。こ
   の変更により、 64 bit システムを正しくサポートするには修正が必要に
   なります。

Py_ssize_t PyUnicode_GET_DATA_SIZE(PyObject *o)

   オブジェクトの内部バッファのサイズをバイト数で返します。 *o* は
   "PyUnicodeObject" でなければなりません (チェックはしません)。

   バージョン 2.5 で変更: この関数は以前は "int" を返していました。こ
   の変更により、 64 bit システムを正しくサポートするには修正が必要に
   なります。

Py_UNICODE* PyUnicode_AS_UNICODE(PyObject *o)

   オブジェクト内部の "Py_UNICODE" バッファへのポインタを返します。
   *o* は "PyUnicodeObject" でなければなりません (チェックはしません)
   。

const char* PyUnicode_AS_DATA(PyObject *o)

   オブジェクト内部バッファへのポインタを返します。 *o* は
   "PyUnicodeObject" でなければなりません (チェックはしません)。

int PyUnicode_ClearFreeList()

   フリーリストをクリアします。解放された要素数を返します。

   バージョン 2.6 で追加.


Unicode 文字プロパティ
----------------------

Unicode は数多くの異なる文字プロパティ (character property) を提供して
います。よく使われる文字プロパティは、以下のマクロで利用できます。これ
らのマクロは Python の設定に応じて、各々 C の関数に対応付けられていま
す。

int Py_UNICODE_ISSPACE(Py_UNICODE ch)

   *ch* が空白文字かどうかに応じて "1" または "0" を返します。

int Py_UNICODE_ISLOWER(Py_UNICODE ch)

   *ch* が小文字かどうかに応じて "1" または "0" を返します。

int Py_UNICODE_ISUPPER(Py_UNICODE ch)

   *ch* が大文字かどうかに応じて "1" または "0" を返します。

int Py_UNICODE_ISTITLE(Py_UNICODE ch)

   *ch* がタイトルケース文字 (titlecase character) かどうかに応じて
   "1" または "0" を返します。

int Py_UNICODE_ISLINEBREAK(Py_UNICODE ch)

   *ch* が改行文字かどうかに応じて "1" または "0" を返します。

int Py_UNICODE_ISDECIMAL(Py_UNICODE ch)

   *ch* が decimal 文字かどうかに応じて "1" または "0" を返します。

int Py_UNICODE_ISDIGIT(Py_UNICODE ch)

   *ch* が digit 文字かどうかに応じて "1" または "0" を返します。

int Py_UNICODE_ISNUMERIC(Py_UNICODE ch)

   *ch* が数字 (numeric) 文字かどうかに応じて "1" または "0" を返しま
   す。

int Py_UNICODE_ISALPHA(Py_UNICODE ch)

   *ch* がアルファベット文字かどうかに応じて "1" または "0" を返します
   。

int Py_UNICODE_ISALNUM(Py_UNICODE ch)

   *ch* が英数文字かどうかに応じて "1" または "0" を返します。

以下の API は、高速に直接文字変換を行うために使われます:

Py_UNICODE Py_UNICODE_TOLOWER(Py_UNICODE ch)

   *ch* を小文字に変換したものを返します。

Py_UNICODE Py_UNICODE_TOUPPER(Py_UNICODE ch)

   *ch* を大文字に変換したものを返します。

Py_UNICODE Py_UNICODE_TOTITLE(Py_UNICODE ch)

   *ch* をタイトルケース文字に変換したものを返します。

int Py_UNICODE_TODECIMAL(Py_UNICODE ch)

   *ch* を 10 進の正の整数に変換したものを返します。不可能ならば "-1"
   を返します。このマクロは例外を送出しません。

int Py_UNICODE_TODIGIT(Py_UNICODE ch)

   *ch* を一桁の 2 進整数に変換したものを返します。不可能ならば "-1"
   を返します。このマクロは例外を送出しません。

double Py_UNICODE_TONUMERIC(Py_UNICODE ch)

   *ch* を "double" に変換したものを返します。不可能ならば "-1.0" を返
   します。このマクロは例外を送出しません。


Plain Py_UNICODE
----------------

Unicode オブジェクトを生成したり、Unicode のシーケンスとしての基本的な
プロパティにアクセスしたりするには、以下の API を使ってください:

PyObject* PyUnicode_FromUnicode(const Py_UNICODE *u, Py_ssize_t size)
    *Return value: New reference.*

   *size* で指定された長さを持つ Py_UNICODE 型バッファ *u* から
   Unicode オブジェクトを生成します。 *u* を *NULL* にしてもよく、その
   場合オブジェクトの内容は未定義です。バッファに必要な情報を埋めるの
   はユーザの責任です。バッファの内容は新たなオブジェクトにコピーされ
   ます。バッファが *NULL* でない場合、戻り値は共有されたオブジェクト
   になることがあります。従って、この関数が返す Unicode オブジェクトを
   変更してよいのは *u* が *NULL* のときだけです。

   バージョン 2.5 で変更: この関数は以前は *size* の型に "int" を利用
   していました。この変更により、 64bit システムを正しくサポートするに
   は修正が必要になります。

PyObject* PyUnicode_FromStringAndSize(const char *u, Py_ssize_t size)
    *Return value: New reference.*

   char 型バッファ *u* から Unicode オブジェクトを生成します。 *u* の
   内容は UTF-8 エンコードされているものとします。 *u* を *NULL* にし
   てもよく、その場合オブジェクトの内容は未定義で、バッファに必要な情
   報を埋めるのはユーザの責任です。バッファの内容は新たなオブジェクト
   にコピーされます。バッファが *NULL* でない場合、戻り値は共有された
   オブジェクトになることがあります。従って、この関数が返す Unicode オ
   ブジェクトを変更してよいのは *u* が *NULL* のときだけです。

   バージョン 2.6 で追加.

PyObject *PyUnicode_FromString(const char *u)
    *Return value: New reference.*

   UTF-8 エンコードされたnull終端のchar 型バッファ *u* から Unicode オ
   ブジェクトを生成します。

   バージョン 2.6 で追加.

PyObject* PyUnicode_FromFormat(const char *format, ...)
    *Return value: New reference.*

   "printf()" スタイルの *format* 文字列と可変長引数を受け取り、結果の
   unicode 文字の長さを計算し、フォーマットされた文字列を含む unicode
   オブジェクトを返します。可変長引数は C の型を持っていて、 *format*
   文字列で指定された書式指定文字に完全に従う必要があります。以下の書
   式指定文字が利用できます:

   +---------------------+-----------------------+----------------------------------+
   | 書式指定文字        | 型                    | 備考                             |
   +=====================+=======================+==================================+
   | "%%"                | *n/a*                 | リテラルの % 文字                |
   +---------------------+-----------------------+----------------------------------+
   | "%c"                | int                   | C の整数型で表現される単一の文字 |
   |                     |                       | 。                               |
   +---------------------+-----------------------+----------------------------------+
   | "%d"                | int                   | C の "printf("%d")" と全く同じ   |
   +---------------------+-----------------------+----------------------------------+
   | "%u"                | unsigned int          | C の "printf("%u")" と全く同じ   |
   +---------------------+-----------------------+----------------------------------+
   | "%ld"               | long                  | C の "printf("%ld")" と全く同じ  |
   +---------------------+-----------------------+----------------------------------+
   | "%lu"               | unsigned long         | C の "printf("%lu")" と全く同じ  |
   +---------------------+-----------------------+----------------------------------+
   | "%zd"               | Py_ssize_t            | C の "printf("%zd")" と全く同じ  |
   +---------------------+-----------------------+----------------------------------+
   | "%zu"               | size_t                | C の "printf("%zu")" と全く同じ  |
   +---------------------+-----------------------+----------------------------------+
   | "%i"                | int                   | C の "printf("%i")" と全く同じ   |
   +---------------------+-----------------------+----------------------------------+
   | "%x"                | int                   | C の "printf("%x")" と全く同じ   |
   +---------------------+-----------------------+----------------------------------+
   | "%s"                | char*                 | null で終端された C の文字列。   |
   +---------------------+-----------------------+----------------------------------+
   | "%p"                | void*                 | C ポインタの 16 進表記。         |
   |                     |                       | "printf("%p")" とほとんど同じで  |
   |                     |                       | すが、プラッ トフォームにおける  |
   |                     |                       | "printf" の定義に関わりなく先頭  |
   |                     |                       | にリテラル "0x" が付きます。     |
   +---------------------+-----------------------+----------------------------------+
   | "%U"                | PyObject*             | unicode オブジェクト。           |
   +---------------------+-----------------------+----------------------------------+
   | "%V"                | PyObject*, char *     | unicode オブジェクト(*NULL* でも |
   |                     |                       | 良い)と、 2つめの引数として NUL  |
   |                     |                       | 終 端の C 文字列 (2つめの引数は1 |
   |                     |                       | つめの引数が *NULL* だった時にの |
   |                     |                       | み利用 されます)。               |
   +---------------------+-----------------------+----------------------------------+
   | "%S"                | PyObject*             | "PyObject_Unicode()" の戻り値    |
   +---------------------+-----------------------+----------------------------------+
   | "%R"                | PyObject*             | "PyObject_Repr()" の戻り値       |
   +---------------------+-----------------------+----------------------------------+

   識別できない書式指定文字があった場合、残りの書式文字列はそのまま出
   力文字列にコピーされ、残りの引数は無視されます。

   バージョン 2.6 で追加.

PyObject* PyUnicode_FromFormatV(const char *format, va_list vargs)
    *Return value: New reference.*

   2引数であることを除いて "PyUnicode_FromFormat()" と同じです。

   バージョン 2.6 で追加.

Py_UNICODE* PyUnicode_AsUnicode(PyObject *unicode)

   Unicode オブジェクトの内部バッファ "Py_UNICODE" に対する読み出し専
   用のポインタを返します。 *unicode* が Unicode オブジェクトでなけれ
   ば *NULL* を返します。結果の "Py_UNICODE*" 文字列には文字列の途中に
   も nul 文字が含まれうることに注意してください。これはほとんどの C
   関数で文字列を切り捨ててしまう結果になります。

Py_ssize_t PyUnicode_GetSize(PyObject *unicode)

   Unicode オブジェクトの長さを返します。

   バージョン 2.5 で変更: この関数は以前は "int" を返していました。こ
   の変更により、 64 bit システムを正しくサポートするには修正が必要に
   なります。

PyObject* PyUnicode_FromEncodedObject(PyObject *obj, const char *encoding, const char *errors)
    *Return value: New reference.*

   あるエンコード方式でエンコードされたオブジェクト *obj* を Unicode
   オブジェクトに型変換して、参照カウントをインクリメントして返します
   。

   文字列やその他の char バッファ互換オブジェクトの場合、オブジェクト
   は *encoding* に従ってデコードされます。このとき *error* で定義され
   たエラー処理を用います。これら二つの引数は *NULL* にでき、その場合
   デフォルト値が使われます (詳細は次の節を参照してください)

   その他のUnicodeオブジェクトを含むオブジェクトは "TypeError" 例外を
   引き起こします。

   この API は、エラーが生じたときには *NULL* を返します。呼び出し側は
   返されたオブジェクトに対し参照カウンタを 1 つ減らす (decref) する責
   任があります。

PyObject* PyUnicode_FromObject(PyObject *obj)
    *Return value: New reference.*

   "PyUnicode_FromEncodedObject(obj, NULL, "strict")" を行うショートカ
   ットで、インタプリタは Unicode への型強制が必要な際に常にこの関数を
   使います。

プラットフォームで "wchar_t" がサポートされていて、かつ wchar.h が提供
されている場合、Python は以下の関数を使って "wchar_t" に対して直接アク
セスすることができます。このアクセスは、Python 自体の "Py_UNICODE" 型
がシステムの "wchar_t" と同一の場合に最適化されます。


wchar_t サポート
----------------

"wchar_t" をサポートするプラットフォームでの wchar_t サポート:

PyObject* PyUnicode_FromWideChar(const wchar_t *w, Py_ssize_t size)
    *Return value: New reference.*

   *size* の "wchar_t" バッファ *w* から Unicode オブジェクトを生成し
   ます。失敗すると *NULL* を返します。

   バージョン 2.5 で変更: この関数は以前は *size* の型に "int" を利用
   していました。この変更により、 64bit システムを正しくサポートするに
   は修正が必要になります。

Py_ssize_t PyUnicode_AsWideChar(PyUnicodeObject *unicode, wchar_t *w, Py_ssize_t size)

   Unicode オブジェクトの内容を "wchar_t" バッファ *w* にコピーします
   。最大で *size* 個の "wchar_t" 文字を (末尾の 0-終端文字を除いて)
   コピーします。コピーした "wchar_t" 文字の個数を返します。エラーの時
   には "-1" を返します。 "wchar_t" 文字列は 0-終端されている場合も、
   されていない場合もあります。関数の呼び出し側の責任で、アプリケーシ
   ョンの必要に応じて "wchar_t" 文字列を 0-終端してください。また、結
   果の "wchar_t*" 文字列には文字列の途中にも nul 文字が含まれうること
   にも注意してください。これはほとんどの C 関数で文字列を切り捨ててし
   まう結果になります。

   バージョン 2.5 で変更: この関数は以前は "int" を返し、 *size* の型
   に "int" を利用していました。この変更により、 64bit システムを正し
   くサポートするには修正が必要になります。


組み込み 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
----------

以下は汎用 codec の API です:

PyObject* PyUnicode_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)
    *Return value: New reference.*

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

   バージョン 2.5 で変更: この関数は以前は *size* の型に "int" を利用
   していました。この変更により、 64bit システムを正しくサポートするに
   は修正が必要になります。

PyObject* PyUnicode_Encode(const Py_UNICODE *s, Py_ssize_t size, const char *encoding, const char *errors)
    *Return value: New reference.*

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

   バージョン 2.5 で変更: この関数は以前は *size* の型に "int" を利用
   していました。この変更により、 64bit システムを正しくサポートするに
   は修正が必要になります。

PyObject* PyUnicode_AsEncodedString(PyObject *unicode, const char *encoding, const char *errors)
    *Return value: New reference.*

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


UTF-8 Codecs
------------

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

PyObject* PyUnicode_DecodeUTF8(const char *s, Py_ssize_t size, const char *errors)
    *Return value: New reference.*

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

   バージョン 2.5 で変更: この関数は以前は *size* の型に "int" を利用
   していました。この変更により、 64bit システムを正しくサポートするに
   は修正が必要になります。

PyObject* PyUnicode_DecodeUTF8Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)
    *Return value: New reference.*

   *consumed* が *NULL* の場合、 "PyUnicode_DecodeUTF8()" と同じように
   動作します。 *consumed* が *NULL* でない場合、
   "PyUnicode_DecodeUTF8Stateful()" は末尾の不完全な UTF-8 バイト列を
   エラーとみなしません。これらのバイト列はデコードされず、デコードさ
   れたバイト数を *consumed* に返します。

   バージョン 2.4 で追加.

   バージョン 2.5 で変更: この関数は以前は *size* の型に "int" を利用
   していました。この変更により、 64bit システムを正しくサポートするに
   は修正が必要になります。

PyObject* PyUnicode_EncodeUTF8(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
    *Return value: New reference.*

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

   バージョン 2.5 で変更: この関数は以前は *size* の型に "int" を利用
   していました。この変更により、 64bit システムを正しくサポートするに
   は修正が必要になります。

PyObject* PyUnicode_AsUTF8String(PyObject *unicode)
    *Return value: New reference.*

   UTF-8 で Unicode オブジェクトをエンコードし、結果を Python 文字列オ
   ブジェクトとして返します。エラー処理は "strict" です。 codec が例外
   を送出した場合には *NULL* を返します。


UTF-32 Codecs
-------------

以下は UTF-32 codec API です:

PyObject* PyUnicode_DecodeUTF32(const char *s, Py_ssize_t size, const char *errors, int *byteorder)

   UTF-32 でエンコードされたバッファ文字列から *size* バイトをデコード
   し、 Unicodeオブジェクトとして返します。 *errors* は (*NULL* でない
   なら) エラーハンドラを指定します。デフォルトは "strict" です。

   *byteorder* が *NULL* でない時、デコーダは与えられたバイトオーダー
   でデコードを開始します。

      *byteorder == -1: little endian
      *byteorder == 0:  native order
      *byteorder == 1:  big endian

   "*byteorder" が 0 で入力データの最初の 4 バイトがバイトオーダーマー
   ク (BOM) だった場合、デコーダーは BOM のバイトオーダーに切り替え、
   BOM は結果の unicode 文字列には含まれません。 "*byteorder" が "-1"
   か "1" だった場合、すべての BOM は出力へコピーされます。

   デコードが完了した後、入力データの終端に来た時点でのバイトオーダー
   を **byteorder* にセットします。

   narrow build の場合、BMP 外のコードポイントはサロゲートペアとしてデ
   コードされます。

   *byteorder* が *NULL* のとき、 codec は native order モードで開始し
   ます。

   codec が例外を発生させたときは *NULL* を返します。

   バージョン 2.6 で追加.

PyObject* PyUnicode_DecodeUTF32Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)

   *consumed* が *NULL* のとき、 "PyUnicode_DecodeUTF32()" と同じよう
   に振る舞います。 *consumed* が *NULL* でないとき、
   "PyUnicode_DecodeUTF32Stateful()" は末尾の不完全な (4 で割り切れな
   い長さのバイト列などの) UTF-32 バイト列をエラーとして扱いません。末
   尾の不完全なバイト列はデコードされず、デコードされたバイト数が
   *consumed* に格納されます。

   バージョン 2.6 で追加.

PyObject* PyUnicode_EncodeUTF32(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)

   *s* の Unicode データを UTF-32 にエンコードし、その値を Python の
   bytes オブジェクトに格納して返します。出力は以下のバイトオーダーで
   従って書かれます。

      byteorder == -1: little endian
      byteorder == 0:  native byte order (writes a BOM mark)
      byteorder == 1:  big endian

   byteorder が "0" のとき、出力文字列は常に Unicode BOM マーク
   (U+FEFF) で始まります。それ以外の2つのモードでは、先頭に BOM マーク
   は出力されません。

   *Py_UNICODE_WIDE* が定義されていない場合は、サロゲートペアを 1 つの
   コードポイントとして出力します。

   codec が例外を発生させたときは *NULL* を返します。

   バージョン 2.6 で追加.

PyObject* PyUnicode_AsUTF32String(PyObject *unicode)

   ネイティブバイトオーダーで UTF-32 エンコーディングされた Python 文
   字列を返します。文字列は常に BOM マークで始まります。エラーハンドラ
   は "strict" です。 codec が例外を発生させたときは *NULL* を返します
   。

   バージョン 2.6 で追加.


UTF-16 Codecs
-------------

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

PyObject* PyUnicode_DecodeUTF16(const char *s, Py_ssize_t size, const char *errors, int *byteorder)
    *Return value: New reference.*

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

   *byteorder* が *NULL* でない時、デコーダは与えられたバイトオーダー
   でデコードを開始します。

      *byteorder == -1: little endian
      *byteorder == 0:  native order
      *byteorder == 1:  big endian

   "*byteorder" が 0 で、入力データの先頭2バイトがバイトオーダーマーク
   (BOM) だった場合、デコーダは BOM が示すバイトオーダーに切り替え、そ
   のBOMを結果の Unicode 文字列にコピーしません。 "*byteorder" が "-1"
   か "1" だった場合、すべてのBOMは出力へコピーされます (出力では
   "\ufeff" か "\ufffe" のどちらかになるでしょう)。

   デコードが完了した後、入力データの終端に来た時点でのバイトオーダー
   を **byteorder* にセットします。

   *byteorder* が *NULL* のとき、 codec は native order モードで開始し
   ます。

   codec が例外を発生させたときは *NULL* を返します。

   バージョン 2.5 で変更: この関数は以前は *size* の型に "int" を利用
   していました。この変更により、 64bit システムを正しくサポートするに
   は修正が必要になります。

PyObject* PyUnicode_DecodeUTF16Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)
    *Return value: New reference.*

   *consumed* が *NULL* の場合、 "PyUnicode_DecodeUTF16()" と同じよう
   に動作します。 *consumed* が *NULL* でない場合、
   "PyUnicode_DecodeUTF16Stateful()" は末尾の不完全な UTF-16 バイト列
   (奇数長のバイト列や分割されたサロゲートペア) をエラーとみなしません
   。これらのバイト列はデコードされず、デコードされたバイト数を
   *consumed* に返します。

   バージョン 2.4 で追加.

   バージョン 2.5 で変更: この関数は以前は *size* の型に "int" を利用
   し、 *consumed* の型に "int *" を利用していました。この変更により、
   64bit システムを正しくサポートするには修正が必要になります。

PyObject* PyUnicode_EncodeUTF16(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)
    *Return value: New reference.*

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

      byteorder == -1: little endian
      byteorder == 0:  native byte order (writes a BOM mark)
      byteorder == 1:  big endian

   byteorder が "0" のとき、出力文字列は常に Unicode BOM マーク
   (U+FEFF) で始まります。それ以外の2つのモードでは、先頭に BOM マーク
   は出力されません。

   *Py_UNICODE_WIDE* が定義されている場合、単一の "Py_UNICODE" 値はサ
   ロゲートペアとして表現されることがあります。 *Py_UNICODE_WIDE* が定
   義されていなければ、各 "Py_UNICODE" 値は UCS-2 文字として表現されま
   す。

   codec が例外を発生させたときは *NULL* を返します。

   バージョン 2.5 で変更: この関数は以前は *size* の型に "int" を利用
   していました。この変更により、 64bit システムを正しくサポートするに
   は修正が必要になります。

PyObject* PyUnicode_AsUTF16String(PyObject *unicode)
    *Return value: New reference.*

   ネイティブバイトオーダの UTF-16 でエンコードされた Python 文字列を
   返します。文字列は常に BOM マークから始まります。エラー処理は
   "strict" です。 codec が例外を送出した場合には *NULL* を返します。


UTF-7 Codecs
------------

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

PyObject* PyUnicode_DecodeUTF7(const char *s, Py_ssize_t size, const char *errors)

   UTF-7 でエンコードされた *size* バイトの文字列 *s* をデコードして
   Unicode オブジェクトを作成します。 codec が例外を発生させたときは
   *NULL* を返します。

PyObject* PyUnicode_DecodeUTF7Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)

   *consumed* が *NULL* のとき、 "PyUnicode_DecodeUTF7()" と同じように
   動作します。 *consumed* が *NULL* でないとき、末尾の不完全な UTF-7
   base-64 部分をエラーとしません。不完全な部分のバイト列はデコードせ
   ずに、デコードしたバイト数を *consumed* に格納します。

PyObject* PyUnicode_EncodeUTF7(const Py_UNICODE *s, Py_ssize_t size, int base64SetO, int base64WhiteSpace, const char *errors)

   与えられたサイズの "Py_UNICODE" バッファを UTF-7 でエンコードして、
   Python の bytes オブジェクトとして返します。 codec が例外を発生させ
   たときは *NULL* を返します。

   *base64SetO* がゼロでないとき、 "Set O" 文字 (他の場合には何も特別
   な意味を持たない句読点) を base-64 エンコードします。
   *base64WhiteSpace* がゼロでないとき、空白文字を base-64 エンコード
   します。 Python の "utf-7" codec では、両方ともゼロに設定されていま
   す。


Unicode-Escape Codecs
---------------------

以下は "Unicode Escape" codec の API です:

PyObject* PyUnicode_DecodeUnicodeEscape(const char *s, Py_ssize_t size, const char *errors)
    *Return value: New reference.*

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

   バージョン 2.5 で変更: この関数は以前は *size* の型に "int" を利用
   していました。この変更により、 64bit システムを正しくサポートするに
   は修正が必要になります。

PyObject* PyUnicode_EncodeUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size)
    *Return value: New reference.*

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

   バージョン 2.5 で変更: この関数は以前は *size* の型に "int" を利用
   していました。この変更により、 64bit システムを正しくサポートするに
   は修正が必要になります。

PyObject* PyUnicode_AsUnicodeEscapeString(PyObject *unicode)
    *Return value: New reference.*

   Unicode-Escape で Unicode オブジェクトをエンコードし、結果を Python
   文字列オブジェクトとして返します。エラー処理は "strict" です。
   codec が例外を送出した場合には *NULL* を返します。


Raw-Unicode-Escape Codecs
-------------------------

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

PyObject* PyUnicode_DecodeRawUnicodeEscape(const char *s, Py_ssize_t size, const char *errors)
    *Return value: New reference.*

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

   バージョン 2.5 で変更: この関数は以前は *size* の型に "int" を利用
   していました。この変更により、 64bit システムを正しくサポートするに
   は修正が必要になります。

PyObject* PyUnicode_EncodeRawUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
    *Return value: New reference.*

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

   バージョン 2.5 で変更: この関数は以前は *size* の型に "int" を利用
   していました。この変更により、 64bit システムを正しくサポートするに
   は修正が必要になります。

PyObject* PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)
    *Return value: New reference.*

   Raw-Unicode-Escape で Unicode オブジェクトをエンコードし、結果を
   Python 文字列オブジェクトとして返します。エラー処理は "strict" です
   。 codec が例外を送出した場合には *NULL* を返します。


Latin-1 Codecs
--------------

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

PyObject* PyUnicode_DecodeLatin1(const char *s, Py_ssize_t size, const char *errors)
    *Return value: New reference.*

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

   バージョン 2.5 で変更: この関数は以前は *size* の型に "int" を利用
   していました。この変更により、 64bit システムを正しくサポートするに
   は修正が必要になります。

PyObject* PyUnicode_EncodeLatin1(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
    *Return value: New reference.*

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

   バージョン 2.5 で変更: この関数は以前は *size* の型に "int" を利用
   していました。この変更により、 64bit システムを正しくサポートするに
   は修正が必要になります。

PyObject* PyUnicode_AsLatin1String(PyObject *unicode)
    *Return value: New reference.*

   Latin-1 で Unicode オブジェクトをエンコードし、結果を Python 文字列
   オブジェクトとして返します。エラー処理は "strict" です。 codec が例
   外を送出した場合には *NULL* を返します。


ASCII Codecs
------------

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

PyObject* PyUnicode_DecodeASCII(const char *s, Py_ssize_t size, const char *errors)
    *Return value: New reference.*

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

   バージョン 2.5 で変更: この関数は以前は *size* の型に "int" を利用
   していました。この変更により、 64bit システムを正しくサポートするに
   は修正が必要になります。

PyObject* PyUnicode_EncodeASCII(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
    *Return value: New reference.*

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

   バージョン 2.5 で変更: この関数は以前は *size* の型に "int" を利用
   していました。この変更により、 64bit システムを正しくサポートするに
   は修正が必要になります。

PyObject* PyUnicode_AsASCIIString(PyObject *unicode)
    *Return value: New reference.*

   ASCII で Unicode オブジェクトをエンコードし、結果を Python 文字列オ
   ブジェクトとして返します。エラー処理は "strict" です。 codec が例外
   を送出した場合には *NULL* を返します。


Character Map Codecs
--------------------

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

デコード用の対応表は、 string 型の文字を Unicode 型の文字、整数
(Unicode 序数として解釈されます)、 "None" ("未定義の対応付け" を意味し
、エラーを引き起こします) のいずれかに対応付けなければなりません。

エンコード用の対応表は、Unicode 型の文字を string 型の文字、整数
(Latin-1 序数として解釈されます)、 "None" ("未定義の対応付け" を意味し
、エラーを引き起こします) のいずれかに対応付けなければなりません。

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

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

以下は mapping codec の APIです:

PyObject* PyUnicode_DecodeCharmap(const char *s, Py_ssize_t size, PyObject *mapping, const char *errors)
    *Return value: New reference.*

   エンコードされた *size* バイトの文字列 *s* から *mapping* に指定さ
   れたオブジェクトを使って Unicode オブジェクトを生成します。codec が
   例外を送出した場合には *NULL* を返します。もし、 *mapping* が
   *NULL* だった場合、latin-1 でデコードされます。それ以外の場合では、
   *mapping* は byte に対する辞書マップ (訳注: s に含まれる文字の
   unsigned な値を int 型でキーとして、値として変換対象の Unicode 文字
   を表す Unicode 文字列になっているような辞書) か、ルックアップテーブ
   ルとして扱われる Unicode 文字列です。文字列 (訳注: mapping が
   Unicode 文字列として渡された場合) の長さより大きい byte 値や、(訳注
   : mappingにしたがって変換した結果が) U+FFFE "characters" になる
   Byte値は、"定義されていない対応付け (undefined mapping)" として扱わ
   れます。

   バージョン 2.4 で変更: mapping引数としてunicodeが使えるようになりま
   した.

   バージョン 2.5 で変更: この関数は以前は *size* の型に "int" を利用
   していました。この変更により、 64bit システムを正しくサポートするに
   は修正が必要になります。

PyObject* PyUnicode_EncodeCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *mapping, const char *errors)
    *Return value: New reference.*

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

   バージョン 2.5 で変更: この関数は以前は *size* の型に "int" を利用
   していました。この変更により、 64bit システムを正しくサポートするに
   は修正が必要になります。

PyObject* PyUnicode_AsCharmapString(PyObject *unicode, PyObject *mapping)
    *Return value: New reference.*

   Unicode オブジェクトを *mapping* に指定されたオブジェクトを使ってエ
   ンコードし、結果を Python 文字列オブジェクトとして返します。エラー
   処理は "strict" です。 codec が例外を送出した場合には *NULL* を返し
   ます。

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

PyObject* PyUnicode_TranslateCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *table, const char *errors)
    *Return value: New reference.*

   *size* で指定された長さを持つ "Py_UNICODE" バッファを、文字変換マッ
   プ *table* を適用して変換し、変換結果を Unicode オブジェクトで返し
   ます。 codec が例外を発行した場合には *NULL* を返します。

   *mapping* テーブルは、Unicode 序数を表す整数を Unicode 序数を表す整
   数または "None" (その文字を削除する) に対応付けなければなりません。

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

   バージョン 2.5 で変更: この関数は以前は *size* の型に "int" を利用
   していました。この変更により、 64bit システムを正しくサポートするに
   は修正が必要になります。


Windows 用の MBCS codec
-----------------------

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

PyObject* PyUnicode_DecodeMBCS(const char *s, Py_ssize_t size, const char *errors)
    *Return value: New reference.*

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

   バージョン 2.5 で変更: この関数は以前は *size* の型に "int" を利用
   していました。この変更により、 64bit システムを正しくサポートするに
   は修正が必要になります。

PyObject* PyUnicode_DecodeMBCSStateful(const char *s, int size, const char *errors, int *consumed)

   *consumed* が *NULL* のとき、 "PyUnicode_DecodeMBCS()" と同じ動作を
   します。 *consumed* が *NULL* でないとき、
   "PyUnicode_DecodeMBCSStateful()" は文字列の最後にあるマルチバイト文
   字の前半バイトをデコードせず、 *consumed* にデコードしたバイト数を
   格納します。

   バージョン 2.5 で追加.

PyObject* PyUnicode_EncodeMBCS(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
    *Return value: New reference.*

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

   バージョン 2.5 で変更: この関数は以前は *size* の型に "int" を利用
   していました。この変更により、 64bit システムを正しくサポートするに
   は修正が必要になります。

PyObject* PyUnicode_AsMBCSString(PyObject *unicode)
    *Return value: New reference.*

   MBCS で Unicode オブジェクトをエンコードし、結果を Python 文字列オ
   ブジェクトとして返します。エラー処理は "strict" です。 codec が例外
   を送出した場合には *NULL* を返します。


メソッドとスロット
------------------


メソッドおよびスロット関数 (slot function)
==========================================

以下の API は Unicode オブジェクトおよび文字列を入力に取り (説明では、
どちらも文字列と表記しています)、場合に応じて Unicode オブジェクトか整
数を返す機能を持っています。

これらの関数は全て、例外が発生した場合には *NULL* または "-1" を返しま
す。

PyObject* PyUnicode_Concat(PyObject *left, PyObject *right)
    *Return value: New reference.*

   二つの文字列を結合して、新たな Unicode 文字列を生成します。

PyObject* PyUnicode_Split(PyObject *s, PyObject *sep, Py_ssize_t maxsplit)
    *Return value: New reference.*

   Unicode 文字列のリストを分割して、 Unicode 文字列からなるリストを返
   します。 *sep* が *NULL* の場合、全ての空白文字を使って分割を行いま
   す。それ以外の場合、指定された文字を使って分割を行います。最大で
   *maxsplit* 個までの分割を行います。 *maxsplit* が負ならば分割数に制
   限を設けません。分割結果のリスト内には分割文字は含みません。

   バージョン 2.5 で変更: この関数は以前は *maxsplit* の型に "int" を
   利用していました。この変更により、 64bit システムを正しくサポートす
   るには修正が必要になります。

PyObject* PyUnicode_Splitlines(PyObject *s, int keepend)
    *Return value: New reference.*

   Unicode 文字列を改行文字で区切り、Unicode 文字列からなるリストを返
   します。 CRLF は一個の改行文字とみなします。 *keepend* が "0" の場
   合、分割結果のリスト内に改行文字を含めません。

PyObject* PyUnicode_Translate(PyObject *str, PyObject *table, const char *errors)
    *Return value: New reference.*

   文字列に文字変換マップ *table* を適用して変換し、変換結果を Unicode
   オブジェクトで返します。

   対応表は、Unicode 序数を表す整数を Unicode 序数を表す整数または
   "None" (その文字を削除する) に対応付けなければなりません。

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

   *errors* は codecs で通常使われるのと同じ意味を持ちます。 *errors*
   は *NULL* にしてもよく、デフォルトエラー処理の使用を意味します。

PyObject* PyUnicode_Join(PyObject *separator, PyObject *seq)
    *Return value: New reference.*

   指定した *separator* で文字列からなるシーケンスを連結 (join) し、連
   結結果を Unicode 文字列で返します。

Py_ssize_t PyUnicode_Tailmatch(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)

   *substr* が "str[start:end]" の末端 (*direction* == "-1" は先頭一致
   、 *direction* == "1" は末尾一致) でとマッチする場合に "1" を返し、
   それ以外の場合には "0" を返します。 エラーが発生した時は "-1" を返
   します。

   バージョン 2.5 で変更: この関数は以前は *start*, *end* の型に "int"
   を利用していました。この変更により、 64bit システムを正しくサポート
   するには修正が必要になります。

Py_ssize_t PyUnicode_Find(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)

   "str[start:end]" 中に *substr* が最初に出現する場所を返します。 こ
   のとき指定された検索方向 *direction* (*direction* == "1" は順方向検
   索、 *direction* == "-1" は逆方向検索) で検索します。 戻り値は最初
   にマッチが見つかった場所のインデックスです; 戻り値 "-1" はマッチが
   見つからなかったことを表し、 "-2" はエラーが発生して例外情報が設定
   されていることを表します。

   バージョン 2.5 で変更: この関数は以前は *start*, *end* の型に "int"
   を利用していました。この変更により、 64bit システムを正しくサポート
   するには修正が必要になります。

Py_ssize_t PyUnicode_Count(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end)

   "str[start:end]" に *substr* が重複することなく出現する回数を返しま
   す。エラーが発生した場合には "-1" を返します。

   バージョン 2.5 で変更: この関数は以前は *start*, *end* と戻り値の型
   に "int" を利用していました。この変更により、 64bit システムを正し
   くサポートするには修正が必要になります。

PyObject* PyUnicode_Replace(PyObject *str, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount)
    *Return value: New reference.*

   *str* 中に出現する *substr* を最大で *maxcount* 個 *replstr* に置換
   し、置換結果である Unicode オブジェクトを返します。 *maxcount* ==
   "-1" にすると、文字列中に現れる全ての *substr* を置換します。

   バージョン 2.5 で変更: この関数は以前は *maxcount* の型に "int" を
   利用していました。この変更により、 64bit システムを正しくサポートす
   るには修正が必要になります。

int PyUnicode_Compare(PyObject *left, PyObject *right)

   二つの文字列を比較して、左引数が右引数より小さい場合、左右引数が等
   価の場合、左引数が右引数より大きい場合に対して、それぞれ "-1", "0",
   "1" を返します。

int PyUnicode_RichCompare(PyObject *left, PyObject *right, int op)

   二つのunicode文字列を比較して、下のうちの一つを返します:

   * "NULL" を、例外が発生したときに返します。

   * "Py_True" もしくは "Py_False" を、正しく比較できた時に返します
     。

   * "Py_NotImplemented" を、 *left* と *right* のどちらかに対する
     "PyUnicode_FromObject()" が失敗したときに返します。(原文: in case
     the type combination is unknown)

   "Py_EQ" と "Py_NE" の比較は、引数からUnicodeへの変換が
   "UnicodeDecodeError" で失敗した時に、 "UnicodeWarning" を発生する可
   能性があることに注意してください。

   *op* に入れられる値は、 "Py_GT", "Py_GE", "Py_EQ", "Py_NE",
   "Py_LT", and "Py_LE" のどれかです。

PyObject* PyUnicode_Format(PyObject *format, PyObject *args)
    *Return value: New reference.*

   新たな文字列オブジェクトを *format* および *args* から生成して返し
   ます; このメソッドは "format % args" のようなものです。

int PyUnicode_Contains(PyObject *container, PyObject *element)

   *element* が *container* 内にあるか調べ、その結果に応じて真または偽
   を返します。

   *element* は単要素の Unicode 文字に型強制できなければなりません。エ
   ラーが生じた場合には "-1" を返します。
