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


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


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

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

Py_UNICODE

   This type represents the storage type which is used by Python
   internally as basis for holding Unicode ordinals.  Python’s default
   builds use a 16-bit type for "Py_UNICODE" and store Unicode values
   internally as UCS2. It is also possible to build a UCS4 version of
   Python (most recent Linux distributions come with UCS4 builds of
   Python). These builds then use a 32-bit type for "Py_UNICODE" and
   store Unicode data internally as UCS4. On platforms where "wchar_t"
   is available and compatible with the chosen Python Unicode build
   variant, "Py_UNICODE" is a typedef alias for "wchar_t" to enhance
   native platform compatibility. On all other platforms, "Py_UNICODE"
   is a typedef alias for either "unsigned short" (UCS2) or "unsigned
   long" (UCS4).

Note that UCS2 and UCS4 Python builds are not binary compatible.
Please keep this in mind when writing extensions or interfaces.

PyUnicodeObject

   This subtype of "PyObject" represents a Python Unicode object.

PyTypeObject PyUnicode_Type

   This instance of "PyTypeObject" represents the Python Unicode type.
   It is exposed to Python code as "unicode" and "types.UnicodeType".

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

int PyUnicode_Check(PyObject *o)

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

   バージョン 2.2 で変更: Allowed subtypes to be accepted.

int PyUnicode_CheckExact(PyObject *o)

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

   バージョン 2.2 で追加.

Py_ssize_t PyUnicode_GET_SIZE(PyObject *o)

   Return the size of the object.  *o* has to be a "PyUnicodeObject"
   (not checked).

   バージョン 2.5 で変更: This function returned an "int" type. This
   might require changes in your code for properly supporting 64-bit
   systems.

Py_ssize_t PyUnicode_GET_DATA_SIZE(PyObject *o)

   Return the size of the object’s internal buffer in bytes.  *o* has
   to be a "PyUnicodeObject" (not checked).

   バージョン 2.5 で変更: This function returned an "int" type. This
   might require changes in your code for properly supporting 64-bit
   systems.

Py_UNICODE* PyUnicode_AS_UNICODE(PyObject *o)

   Return a pointer to the internal "Py_UNICODE" buffer of the object.
   *o* has to be a "PyUnicodeObject" (not checked).

const char* PyUnicode_AS_DATA(PyObject *o)

   Return a pointer to the internal buffer of the object. *o* has to
   be a "PyUnicodeObject" (not checked).

int PyUnicode_ClearFreeList()

   free list をクリアします。解放された要素数を返します。

   バージョン 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.*

   Create a Unicode object from the Py_UNICODE buffer *u* of the given
   size. *u* may be *NULL* which causes the contents to be undefined.
   It is the user’s responsibility to fill in the needed data.  The
   buffer is copied into the new object. If the buffer is not *NULL*,
   the return value might be a shared object. Therefore, modification
   of the resulting Unicode object is only allowed when *u* is *NULL*.

   バージョン 2.5 で変更: This function used an "int" type for *size*.
   This might require changes in your code for properly supporting
   64-bit systems.

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

   Create a Unicode object from the char buffer *u*.  The bytes will
   be interpreted as being UTF-8 encoded.  *u* may also be *NULL*
   which causes the contents to be undefined. It is the user’s
   responsibility to fill in the needed data.  The buffer is copied
   into the new object. If the buffer is not *NULL*, the return value
   might be a shared object. Therefore, modification of the resulting
   Unicode object is only allowed when *u* is *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.*

   Take a C "printf()"-style *format* string and a variable number of
   arguments, calculate the size of the resulting Python unicode
   string and return a string with the values formatted into it.  The
   variable arguments must be C types and must correspond exactly to
   the format characters in the *format* string.  The following format
   characters are allowed:

   +---------------------+-----------------------+----------------------------------+
   | 書式指定文字        | 型                    | 備考                             |
   +=====================+=======================+==================================+
   | "%%"                | *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*             | The result of calling            |
   |                     |                       | "PyObject_Unicode()".            |
   +---------------------+-----------------------+----------------------------------+
   | "%R"                | PyObject*             | The result of calling            |
   |                     |                       | "PyObject_Repr()".               |
   +---------------------+-----------------------+----------------------------------+

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

   バージョン 2.6 で追加.

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

   Identical to "PyUnicode_FromFormat()" except that it takes exactly
   two arguments.

   バージョン 2.6 で追加.

Py_UNICODE* PyUnicode_AsUnicode(PyObject *unicode)

   Return a read-only pointer to the Unicode object’s internal
   "Py_UNICODE" buffer, *NULL* if *unicode* is not a Unicode object.
   Note that the resulting "Py_UNICODE*" string may contain embedded
   null characters, which would cause the string to be truncated when
   used in most C functions.

Py_ssize_t PyUnicode_GetSize(PyObject *unicode)

   Return the length of the Unicode object.

   バージョン 2.5 で変更: This function returned an "int" type. This
   might require changes in your code for properly supporting 64-bit
   systems.

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

   Coerce an encoded object *obj* to a Unicode object and return a
   reference with incremented refcount.

   String and other char buffer compatible objects are decoded
   according to the given encoding and using the error handling
   defined by errors.  Both can be *NULL* to have the interface use
   the default values (see the next section for details).

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

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

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

   Shortcut for "PyUnicode_FromEncodedObject(obj, NULL, "strict")"
   which is used throughout the interpreter whenever coercion to
   Unicode is needed.

If the platform supports "wchar_t" and provides a header file wchar.h,
Python can interface directly to this type using the following
functions. Support is optimized if Python’s own "Py_UNICODE" type is
identical to the system’s "wchar_t".


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

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

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

   Create a Unicode object from the "wchar_t" buffer *w* of the given
   *size*. Return *NULL* on failure.

   バージョン 2.5 で変更: This function used an "int" type for *size*.
   This might require changes in your code for properly supporting
   64-bit systems.

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

   Copy the Unicode object contents into the "wchar_t" buffer *w*.  At
   most *size* "wchar_t" characters are copied (excluding a possibly
   trailing 0-termination character).  Return the number of "wchar_t"
   characters copied or "-1" in case of an error.  Note that the
   resulting "wchar_t" string may or may not be 0-terminated.  It is
   the responsibility of the caller to make sure that the "wchar_t"
   string is 0-terminated in case this is required by the application.
   Also, note that the "wchar_t*" string might contain null
   characters, which would cause the string to be truncated when used
   with most C functions.

   バージョン 2.5 で変更: This function returned an "int" type and
   used an "int" type for *size*. This might require changes in your
   code for properly supporting 64-bit systems.


組み込み codec (built-in codec)
===============================

Python には、処理速度を高めるために C で書かれた codec が揃えてありま
す。これら全ての codec は以下の関数を介して直接利用できます。

Many of the following APIs take two arguments encoding and errors, and
they have the same semantics as the ones of the built-in "unicode()"
Unicode object constructor.

Setting encoding to *NULL* causes the default encoding to be used
which is ASCII.  The file system calls should use
"Py_FileSystemDefaultEncoding" as the encoding for file names. This
variable should be treated as read-only: on some systems, it will be a
pointer to a static string, on others, it will change at run-time
(such as when the application invokes 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.*

   Create a Unicode object by decoding *size* bytes of the encoded
   string *s*. *encoding* and *errors* have the same meaning as the
   parameters of the same name in the "unicode()" built-in function.
   The codec to be used is looked up using the Python codec registry.
   Return *NULL* if an exception was raised by the codec.

   バージョン 2.5 で変更: This function used an "int" type for *size*.
   This might require changes in your code for properly supporting
   64-bit systems.

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

   Encode the "Py_UNICODE" buffer *s* of the given *size* and return a
   Python string object.  *encoding* and *errors* have the same
   meaning as the parameters of the same name in the Unicode
   "encode()" method.  The codec to be used is looked up using the
   Python codec registry.  Return *NULL* if an exception was raised by
   the codec.

   バージョン 2.5 で変更: This function used an "int" type for *size*.
   This might require changes in your code for properly supporting
   64-bit systems.

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

   Encode a Unicode object and return the result as Python string
   object. *encoding* and *errors* have the same meaning as the
   parameters of the same name in the Unicode "encode()" method. The
   codec to be used is looked up using the Python codec registry.
   Return *NULL* if an exception was raised by the codec.


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 で変更: This function used an "int" type for *size*.
   This might require changes in your code for properly supporting
   64-bit systems.

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 で変更: This function used an "int" type for *size*.
   This might require changes in your code for properly supporting
   64-bit systems.

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

   Encode the "Py_UNICODE" buffer *s* of the given *size* using UTF-8
   and return a Python string object.  Return *NULL* if an exception
   was raised by the codec.

   バージョン 2.5 で変更: This function used an "int" type for *size*.
   This might require changes in your code for properly supporting
   64-bit systems.

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

   Encode a Unicode object using UTF-8 and return the result as Python
   string object.  Error handling is 「strict」.  Return *NULL* if an
   exception was raised by the codec.


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 バイトが byte order mark
   (BOM) ならば、デコーダはこのバイトオーダーに切り替え、BOM は結果の
   Unicode 文字列にコピーされません。 "*byteorder" が "-1" または "1"
   ならば、全ての byte order mark は出力にコピーされます。

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

   In a narrow build code points outside the BMP will be decoded as
   surrogate pairs.

   *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)

   Return a Python string using the UTF-32 encoding in native byte
   order. The string always starts with a BOM mark.  Error handling is
   「strict」.  Return *NULL* if an exception was raised by the codec.

   バージョン 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 で変更: This function used an "int" type for *size*.
   This might require changes in your code for properly supporting
   64-bit systems.

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 で変更: This function used an "int" type for *size*
   and an "int *" type for *consumed*. This might require changes in
   your code for properly supporting 64-bit systems.

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

   Return a Python string object holding the UTF-16 encoded value of
   the Unicode data in *s*.  Output is written according to the
   following byte order:

      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 で変更: This function used an "int" type for *size*.
   This might require changes in your code for properly supporting
   64-bit systems.

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

   Return a Python string using the UTF-16 encoding in native byte
   order. The string always starts with a BOM mark.  Error handling is
   「strict」.  Return *NULL* if an exception was raised by the codec.


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 で変更: This function used an "int" type for *size*.
   This might require changes in your code for properly supporting
   64-bit systems.

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

   Encode the "Py_UNICODE" buffer of the given *size* using Unicode-
   Escape and return a Python string object.  Return *NULL* if an
   exception was raised by the codec.

   バージョン 2.5 で変更: This function used an "int" type for *size*.
   This might require changes in your code for properly supporting
   64-bit systems.

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

   Encode a Unicode object using Unicode-Escape and return the result
   as Python string object.  Error handling is 「strict」. Return
   *NULL* if an exception was raised by the codec.


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 で変更: This function used an "int" type for *size*.
   This might require changes in your code for properly supporting
   64-bit systems.

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

   Encode the "Py_UNICODE" buffer of the given *size* using Raw-
   Unicode-Escape and return a Python string object.  Return *NULL* if
   an exception was raised by the codec.

   バージョン 2.5 で変更: This function used an "int" type for *size*.
   This might require changes in your code for properly supporting
   64-bit systems.

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

   Encode a Unicode object using Raw-Unicode-Escape and return the
   result as Python string object. Error handling is 「strict」.
   Return *NULL* if an exception was raised by the codec.


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 で変更: This function used an "int" type for *size*.
   This might require changes in your code for properly supporting
   64-bit systems.

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

   Encode the "Py_UNICODE" buffer of the given *size* using Latin-1
   and return a Python string object.  Return *NULL* if an exception
   was raised by the codec.

   バージョン 2.5 で変更: This function used an "int" type for *size*.
   This might require changes in your code for properly supporting
   64-bit systems.

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

   Encode a Unicode object using Latin-1 and return the result as
   Python string object.  Error handling is 「strict」.  Return *NULL*
   if an exception was raised by the codec.


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 で変更: This function used an "int" type for *size*.
   This might require changes in your code for properly supporting
   64-bit systems.

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

   Encode the "Py_UNICODE" buffer of the given *size* using ASCII and
   return a Python string object.  Return *NULL* if an exception was
   raised by the codec.

   バージョン 2.5 で変更: This function used an "int" type for *size*.
   This might require changes in your code for properly supporting
   64-bit systems.

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

   Encode a Unicode object using ASCII and return the result as Python
   string object.  Error handling is 「strict」.  Return *NULL* if an
   exception was raised by the codec.


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

This codec is special in that it can be used to implement many
different codecs (and this is in fact what was done to obtain most of
the standard codecs included in the "encodings" package). The codec
uses mapping to encode and decode characters.

Decoding mappings must map single string characters to single Unicode
characters, integers (which are then interpreted as Unicode ordinals)
or "None" (meaning 「undefined mapping」 and causing an error).

Encoding mappings must map single Unicode characters to single string
characters, integers (which are then interpreted as Latin-1 ordinals)
or "None" (meaning 「undefined mapping」 and causing an error).

The mapping objects provided must only support the __getitem__ mapping
interface.

If a character lookup fails with a LookupError, the character is
copied as-is meaning that its ordinal value will be interpreted as
Unicode or Latin-1 ordinal resp. Because of this, mappings only need
to contain those mappings which map characters to different code
points.

以下は mapping codec の APIです:

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

   Create a Unicode object by decoding *size* bytes of the encoded
   string *s* using the given *mapping* object.  Return *NULL* if an
   exception was raised by the codec. If *mapping* is *NULL* latin-1
   decoding will be done. Else it can be a dictionary mapping byte or
   a unicode string, which is treated as a lookup table. Byte values
   greater that the length of the string and U+FFFE 「characters」 are
   treated as 「undefined mapping」.

   バージョン 2.4 で変更: Allowed unicode string as mapping argument.

   バージョン 2.5 で変更: This function used an "int" type for *size*.
   This might require changes in your code for properly supporting
   64-bit systems.

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

   Encode the "Py_UNICODE" buffer of the given *size* using the given
   *mapping* object and return a Python string object. Return *NULL*
   if an exception was raised by the codec.

   バージョン 2.5 で変更: This function used an "int" type for *size*.
   This might require changes in your code for properly supporting
   64-bit systems.

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

   Encode a Unicode object using the given *mapping* object and return
   the result as Python string object.  Error handling is 「strict」.
   Return *NULL* if an exception was raised by the codec.

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

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

   Translate a "Py_UNICODE" buffer of the given *size* by applying a
   character mapping *table* to it and return the resulting Unicode
   object.  Return *NULL* when an exception was raised by the codec.

   The *mapping* table must map Unicode ordinal integers to Unicode
   ordinal integers or "None" (causing deletion of the character).

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

   バージョン 2.5 で変更: This function used an "int" type for *size*.
   This might require changes in your code for properly supporting
   64-bit systems.


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 で変更: This function used an "int" type for *size*.
   This might require changes in your code for properly supporting
   64-bit systems.

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.*

   Encode the "Py_UNICODE" buffer of the given *size* using MBCS and
   return a Python string object.  Return *NULL* if an exception was
   raised by the codec.

   バージョン 2.5 で変更: This function used an "int" type for *size*.
   This might require changes in your code for properly supporting
   64-bit systems.

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

   Encode a Unicode object using MBCS and return the result as Python
   string object.  Error handling is 「strict」.  Return *NULL* if an
   exception was raised by the codec.


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


メソッドおよびスロット関数 (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 で変更: This function used an "int" type for
   *maxsplit*. This might require changes in your code for properly
   supporting 64-bit systems.

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 で変更: This function used an "int" type for *start*
   and *end*. This might require changes in your code for properly
   supporting 64-bit systems.

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 で変更: This function used an "int" type for *start*
   and *end*. This might require changes in your code for properly
   supporting 64-bit systems.

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

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

   バージョン 2.5 で変更: This function returned an "int" type and
   used an "int" type for *start* and *end*. This might require
   changes in your code for properly supporting 64-bit systems.

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 で変更: This function used an "int" type for
   *maxcount*. This might require changes in your code for properly
   supporting 64-bit systems.

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)

   Note that "Py_EQ" and "Py_NE" comparisons can cause a
   "UnicodeWarning" in case the conversion of the arguments to Unicode
   fails with a "UnicodeDecodeError".

   *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" を返します。
