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


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

Python3.3 の **PEP 393** 実装から、メモリ効率を維持しながらUnicode文字
の完全な範囲を扱えるように、Unicodeオブジェクトは内部的に多様な表現形
式を用いています。すべてのコードポイントが128、256または65536以下の文
字列に対して特別なケースが存在しますが、それ以外ではコードポイントは
1114112以下(これはすべてのUnicode範囲です)でなければなりません。

"Py_UNICODE*" 表現形式および UTF-8表現形式はオンデマンドで作成され、
Unicode オブジェクト内にキャッシュされます。"Py_UNICODE*" 表現は推奨さ
れず、非効率ですので、重要なタスクを実行し、メモリを消費している状況下
では避けるべきです。

Due to the transition between the old APIs and the new APIs, Unicode
objects can internally be in two states depending on how they were
created:

* "canonical" Unicode objects are all objects created by a non-
  deprecated Unicode API.  They use the most efficient representation
  allowed by the implementation.

* "legacy" Unicode objects have been created through one of the
  deprecated APIs (typically "PyUnicode_FromUnicode()") and only bear
  the "Py_UNICODE*" representation; you will have to call
  "PyUnicode_READY()" on them before calling any other API.


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

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

Py_UCS4
Py_UCS2
Py_UCS1

   これらの型は、それぞれ、32ビット、16ビット、そして8ビットの文字を保
   持するのに充分な幅を持つ符号なしの整数型のtypedefです。単一の
   Unicode文字を扱う場合は、 "Py_UCS4" を用いてください。

   バージョン 3.3 で追加.

Py_UNICODE

   これは、"wchar_t" のtypedef で、プラットフォームに依存して16ビット
   か32ビットの型になります。

   バージョン 3.3 で変更: 以前のバージョンでは、Pythonをビルドした際に
   "narrow" または "wide" Unicode バージョンのどちらを選択したかによっ
   て、 16ビットか32ビットのどちらかの型になっていました。

PyASCIIObject
PyCompactUnicodeObject
PyUnicodeObject

   これらの "PyObject" のサブタイプは Python Unicode オブジェクトを表
   現します。 Unicode オブジェクトを扱う全ての API 関数は "PyObject"
   へのポインタを受け取って PyObject へのポインタを返すので、ほとんど
   の場合、これらの型を直接使うべきではありません。

   バージョン 3.3 で追加.

PyTypeObject PyUnicode_Type

   この "PyTypeObject" のインスタンスは、Python Unicode型を表します。
   これは、Pythonコードに "str" として露出されます。

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

int PyUnicode_Check(PyObject *o)

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

int PyUnicode_CheckExact(PyObject *o)

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

int PyUnicode_READY(PyObject *o)

   文字列オブジェクト *o* が "正統な" 表現形式であることを保証します。
   このマクロは、下で説明しているどのアクセスマクロを使うときも必要と
   なります。

   成功のときには "0" を返し、失敗のときには例外を設定し "-1" を返しま
   す。 後者は、メモリ確保に失敗したときに特に起きやすいです。

   バージョン 3.3 で追加.

Py_ssize_t PyUnicode_GET_LENGTH(PyObject *o)

   Unicode 文字列のコードポイントでの長さを返します。 *o* は "正統な"
   表現形式の Unicode オブジェクトでなければなりません (ただしチェック
   はしません)。

   バージョン 3.3 で追加.

Py_UCS1* PyUnicode_1BYTE_DATA(PyObject *o)
Py_UCS2* PyUnicode_2BYTE_DATA(PyObject *o)
Py_UCS4* PyUnicode_4BYTE_DATA(PyObject *o)

   文字に直接アクセスするために、 UCS1, UCS2, UCS4 のいずれかの整数型
   にキャストされた正統な表現形式へのポインタを返します。 正統な表現が
   適正な文字サイズになっているかどうかのチェックはしません;
   "PyUnicode_KIND()" を使って正しいマクロを選んでください。 このオブ
   ジェクトにアクセスする前に、忘れずに "PyUnicode_READY()" を呼び出し
   てください。

   バージョン 3.3 で追加.

PyUnicode_WCHAR_KIND
PyUnicode_1BYTE_KIND
PyUnicode_2BYTE_KIND
PyUnicode_4BYTE_KIND

   "PyUnicode_KIND()" マクロの返り値です。

   バージョン 3.3 で追加.

int PyUnicode_KIND(PyObject *o)

   この Unicode がデータを保存するのに1文字あたり何バイト使っているか
   を示す PyUnicode 種別の定数 (上を読んでください) のうち1つを返しま
   す。 *o* は "正統な" 表現形式の Unicode オブジェクトでなければなり
   ません (ただしチェックはしません)。

   バージョン 3.3 で追加.

void* PyUnicode_DATA(PyObject *o)

   Return a void pointer to the raw Unicode buffer.  *o* has to be a
   Unicode object in the "canonical" representation (not checked).

   バージョン 3.3 で追加.

void PyUnicode_WRITE(int kind, void *data, Py_ssize_t index, Py_UCS4 value)

   正統な表現形式となっている ("PyUnicode_DATA()" で取得した) *data*
   に書き込みます。 このマクロは正常性のチェックを一切行わない、ループ
   で使われるためのものです。 呼び出し側は、他のマクロを呼び出して取得
   した *kind* 値と *data* ポインタをキャッシュすべきです。 *index* は
   文字列の (0始まりの) インデックスで、 *value* はその場所に書き込ま
   れることになる新しいコードポイントの値です。

   バージョン 3.3 で追加.

Py_UCS4 PyUnicode_READ(int kind, void *data, Py_ssize_t index)

   正統な表現形式となっている ("PyUnicode_DATA()" で取得した) *data*
   からコードポイントを読み取ります。 チェックや事前確認のマクロ呼び出
   しは一切行われません。

   バージョン 3.3 で追加.

Py_UCS4 PyUnicode_READ_CHAR(PyObject *o, Py_ssize_t index)

   Unicode オブジェクト *o* から文字を読み取ります。 この Unicode オブ
   ジェクトは "正統な" 表現形式でなければなりません。 何度も連続して読
   み取る場合には、このマクロは "PyUnicode_READ()" よりも非効率的です
   。

   バージョン 3.3 で追加.

PyUnicode_MAX_CHAR_VALUE(PyObject *o)

   *o* に基づいて他の文字列を作るのに適した最大のコードポイントを返し
   ます。 この Unicode オブジェクトは "正統な" 表現形式でなければなり
   ません。 この値は常に概算値ですが、文字列全体を調べるよりも効率的で
   す。

   バージョン 3.3 で追加.

int PyUnicode_ClearFreeList()

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

Py_ssize_t PyUnicode_GET_SIZE(PyObject *o)

   非推奨の "Py_UNICODE" 表現形式のサイズをコード単位で返します (サロ
   ゲートペアを2つとしています)。 *o* は Unicode オブジェクトでなけれ
   ばなりません (ただしチェックはしません)。

   Deprecated since version 3.3, will be removed in version 4.0: 古い
   スタイルの Unicode APIの一部なので、 "PyUnicode_GET_LENGTH()" を使
   用するように移行してください。

Py_ssize_t PyUnicode_GET_DATA_SIZE(PyObject *o)

   非推奨の "Py_UNICODE" 表現形式のサイズをバイト単位で返します。 *o*
   は Unicode オブジェクトでなければなりません (ただしチェックはしませ
   ん)。

   Deprecated since version 3.3, will be removed in version 4.0: 古い
   スタイルの Unicode APIの一部なので、 "PyUnicode_GET_LENGTH()" を使
   用するように移行してください。

Py_UNICODE* PyUnicode_AS_UNICODE(PyObject *o)
const char* PyUnicode_AS_DATA(PyObject *o)

   与えられたオブジェクトの "Py_UNICODE" 表現形式へのポインタを返しま
   す。 返されるバッファは常に終端に null コードポイントが1つ余分に付
   いています。 それとは別の null コードポイントがバッファに含まれるこ
   ともあるかもしれませんが、たいていの C 関数ではそのような文字列は切
   り詰められてしまうでしょう。 "AS_DATA" の方はポインタを "const char
   *" にキャストしています。 引数 *o* は Unicode オブジェクトでなけれ
   ばなりません (ただしチェックはしません)。

   バージョン 3.3 で変更: このマクロは今では非効率なものになりました。
   というのも、多くのケースで "Py_UNICODE" 表現形式が登場せず、作成さ
   れず、そして失敗し得ます (例外を設定して "NULL" を返します)。 コー
   ドを修正して、 "PyUnicode_nBYTE_DATA()" マクロを使うか
   "PyUnicode_WRITE()" や "PyUnicode_READ()" を使うようにしてください
   。

   Deprecated since version 3.3, will be removed in version 4.0: 古い
   スタイルの Unicode APIの一部なので、 "PyUnicode_nBYTE_DATA()" 系の
   マクロを使用するように移行してください。


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

int Py_UNICODE_ISPRINTABLE(Py_UNICODE ch)

   *ch* が文字が印字可能な文字かどうかに基づいて "1" または "0" を返し
   ます。 非印字可能文字は、 Unicode 文字データベースで "Other" または
   "Separator" と定義されている文字の、印字可能と見なされる ASCII
   space (0x20) 以外のものです。 (なお、この文脈での印字可能文字は、文
   字列に "repr()" が呼び出されるときにエスケープすべきでない文字のこ
   とです。これは "sys.stdout" や "sys.stderr" に書き込まれる文字列の
   操作とは関係ありません。)

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

Py_UNICODE Py_UNICODE_TOLOWER(Py_UNICODE ch)

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

   バージョン 3.3 で非推奨: この関数は単純な大文字小文字変換を使ってま
   す。

Py_UNICODE Py_UNICODE_TOUPPER(Py_UNICODE ch)

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

   バージョン 3.3 で非推奨: この関数は単純な大文字小文字変換を使ってま
   す。

Py_UNICODE Py_UNICODE_TOTITLE(Py_UNICODE ch)

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

   バージョン 3.3 で非推奨: この関数は単純な大文字小文字変換を使ってま
   す。

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" を返
   します。このマクロは例外を送出しません。

これらの API はサロゲートにも使えます:

Py_UNICODE_IS_SURROGATE(ch)

   *ch* がサロゲートかどうか ("0xD800 <= ch <= 0xDFFF") をチェックしま
   す。

Py_UNICODE_IS_HIGH_SURROGATE(ch)

   *ch* が上位サロゲートかどうか ("0xD800 <= ch <= 0xDBFF") をチェック
   します。

Py_UNICODE_IS_LOW_SURROGATE(ch)

   *ch* が下位サロゲートかどうか ("0xDC00 <= ch <= 0xDFFF") をチェック
   します。

Py_UNICODE_JOIN_SURROGATES(high, low)

   2つのサロゲート文字を組み合わせて単一の Py_UCS4 値を返します。
   *high* と *low* はそれぞれサロゲートペアの前半分と後半分です。


Unicode 文字列の生成とアクセス
------------------------------

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

PyObject* PyUnicode_New(Py_ssize_t size, Py_UCS4 maxchar)
    *Return value: New reference.*

   新しい Unicode オブジェクトを生成します。 *maxchar* は文字列に並べ
   るコードポイントの正しい最大値にすべきです。 その値は概算値として
   127, 255, 65535, 1114111 の一番近い値に切り上げられます。

   これは新しい Unicode オブジェクトを生成する推奨された方法です。 こ
   の関数を使って生成されたオブジェクトはサイズ変更は不可能です。

   バージョン 3.3 で追加.

PyObject* PyUnicode_FromKindAndData(int kind, const void *buffer, Py_ssize_t size)
    *Return value: New reference.*

   与えられた *kind* (取り得る値は "PyUnicode_1BYTE_KIND" などの
   "PyUnicode_KIND()" が返す値です) の Unicode オブジェクトを生成しま
   す。 *buffer* は、与えられた kind に従って1文字あたり 1, 2, 4 バイ
   トのいずれかを単位として、長さ *size* の配列へのポインタでなければ
   なりません。

   バージョン 3.3 で追加.

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

   char 型バッファ *u* から Unicode オブジェクトを生成します。 *u* の
   内容は UTF-8 でエンコードされているものとします。 バッファの内容は
   新たなオブジェクトにコピーされます。 バッファが "NULL" でない場合、
   帰り値は共有されたオブジェクトになることがあります。 つまり、この関
   数が返す Unicode オブジェクトの変更は許されていません。

   *u* が "NULL" の場合は、この関数は "PyUnicode_FromUnicode()" でバッ
   ファ *u* を "NULL" にセットしたのと同じように振る舞います。 この関
   数は非推奨です。変わりに "PyUnicode_New()" を使ってください。

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

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

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* ASCII-encoded string. The
   following format characters are allowed:

   +---------------------+-----------------------+------------------------------------+
   | 書式指定文字        | 型                    | 備考                               |
   |=====================|=======================|====================================|
   | "%%"                | *n/a*                 | リテラルの % 文字                  |
   +---------------------+-----------------------+------------------------------------+
   | "%c"                | int                   | C の整数型で表現される単一の文字。 |
   +---------------------+-----------------------+------------------------------------+
   | "%d"                | int                   | "printf("%d")" と同等。 [1]        |
   +---------------------+-----------------------+------------------------------------+
   | "%u"                | unsigned int          | "printf("%u")" と同等。 [1]        |
   +---------------------+-----------------------+------------------------------------+
   | "%ld"               | long                  | "printf("%ld")" と同等。 [1]       |
   +---------------------+-----------------------+------------------------------------+
   | "%li"               | long                  | "printf("%li")" と同等。 [1]       |
   +---------------------+-----------------------+------------------------------------+
   | "%lu"               | unsigned long         | "printf("%lu")" と同等。 [1]       |
   +---------------------+-----------------------+------------------------------------+
   | "%lld"              | long long             | "printf("%lld")" と同等。 [1]      |
   +---------------------+-----------------------+------------------------------------+
   | "%lli"              | long long             | "printf("%lli")" と同等。 [1]      |
   +---------------------+-----------------------+------------------------------------+
   | "%llu"              | unsigned long long    | "printf("%llu")" と同等。 [1]      |
   +---------------------+-----------------------+------------------------------------+
   | "%zd"               | Py_ssize_t            | "printf("%zd")" と同等。 [1]       |
   +---------------------+-----------------------+------------------------------------+
   | "%zi"               | Py_ssize_t            | "printf("%zi")" と同等。 [1]       |
   +---------------------+-----------------------+------------------------------------+
   | "%zu"               | size_t                | "printf("%zu")" と同等。 [1]       |
   +---------------------+-----------------------+------------------------------------+
   | "%i"                | int                   | "printf("%i")" と同等。 [1]        |
   +---------------------+-----------------------+------------------------------------+
   | "%x"                | int                   | "printf("%x")" と同等。 [1]        |
   +---------------------+-----------------------+------------------------------------+
   | "%s"                | const char*           | null で終端された C の文字列。     |
   +---------------------+-----------------------+------------------------------------+
   | "%p"                | const void*           | C ポインタの 16 進表記。           |
   |                     |                       | "printf("%p")" とほとんど同じです  |
   |                     |                       | が、プラッ トフォームにおける      |
   |                     |                       | "printf" の定義に関わりなく先頭に  |
   |                     |                       | リテラル "0x" が付きます。         |
   +---------------------+-----------------------+------------------------------------+
   | "%A"                | PyObject*             | "ascii()" の戻り値。               |
   +---------------------+-----------------------+------------------------------------+
   | "%U"                | PyObject*             | A Unicode object.                  |
   +---------------------+-----------------------+------------------------------------+
   | "%V"                | PyObject*, const      | A Unicode object (which may be     |
   |                     | char*                 | "NULL") and a null-terminated C    |
   |                     |                       | character array as a second        |
   |                     |                       | parameter (which will be used, if  |
   |                     |                       | the first parameter is "NULL").    |
   +---------------------+-----------------------+------------------------------------+
   | "%S"                | PyObject*             | "PyObject_Str()" の戻り値。        |
   +---------------------+-----------------------+------------------------------------+
   | "%R"                | PyObject*             | "PyObject_Repr()" の戻り値。       |
   +---------------------+-----------------------+------------------------------------+

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

   注釈:

     The width formatter unit is number of characters rather than
     bytes. The precision formatter unit is number of bytes for ""%s""
     and ""%V"" (if the "PyObject*" argument is "NULL"), and a number
     of characters for ""%A"", ""%U"", ""%S"", ""%R"" and ""%V"" (if
     the "PyObject*" argument is not "NULL").

   [1] For integer specifiers (d, u, ld, li, lu, lld, lli, llu, zd,
       zi, zu, i, x): the 0-conversion flag has effect even when a
       precision is given.

   バージョン 3.2 で変更: ""%lld"", ""%llu"" のサポートが追加されまし
   た。

   バージョン 3.3 で変更: ""%li"", ""%lli"", ""%zi"" のサポートが追加
   されました。

   バージョン 3.4 で変更: ""%s"", ""%A"", ""%U"", ""%V"", ""%S"",
   ""%R"" での幅フォーマッタおよび精度フォーマッタのサポートが追加され
   ました。

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

   ちょうど２つの引数を取ることを除いて、 "PyUnicode_FromFormat()" と
   同じです。

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

   エンコードされている *obj* を Unicode オブジェクトにデコードします
   。

   "bytes" や "bytearray" や他の *bytes-like objects* は、与えられた
   *encoding* に従ってデコードされ、 *errors* で定義されたエラーハンド
   リングが使われます。 これらの引数は両方とも "NULL" にでき、その場合
   この API はデフォルト値を使います (詳しことは 組み込み codec
   (built-in codec) を参照してください)。

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

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

Py_ssize_t PyUnicode_GetLength(PyObject *unicode)

   Unicode オブジェクトの長さをコードポイントで返します。

   バージョン 3.3 で追加.

Py_ssize_t PyUnicode_CopyCharacters(PyObject *to, Py_ssize_t to_start, PyObject *from, Py_ssize_t from_start, Py_ssize_t how_many)

   ある Unicode オブジェクトから他へ文字をコピーします。 この関数は必
   要なときに文字変換を行い、可能な場合は "memcpy()" へ差し戻します。
   失敗のときには "-1" を返し、例外を設定します。そうでない場合は、コ
   ピーした文字数を返します。

   バージョン 3.3 で追加.

Py_ssize_t PyUnicode_Fill(PyObject *unicode, Py_ssize_t start, Py_ssize_t length, Py_UCS4 fill_char)

   文字列を文字で埋めます: "unicode[start:start+length]" で
   *fill_char* を埋めることになります。

   *fill_char* が文字列の最大文字よりも大きい場合や、文字列2つ以上の参
   照を持ってた場合は失敗します。

   書き込んだ文字数を返すか、失敗のときには "-1" を返し例外を送出しま
   す。

   バージョン 3.3 で追加.

int PyUnicode_WriteChar(PyObject *unicode, Py_ssize_t index, Py_UCS4 character)

   文字列に文字を書き込みます。 文字列は "PyUnicode_New()" で作成しな
   ければなりません。 Unicode 文字列は不変とされているので、この文字列
   は共有されていたり、これまでにハッシュ化されていてはいけません。

   この関数は *unicode* が Unicode オブジェクトであること、インデック
   スが範囲内であること、オブジェクトが安全に変更できる (つまり参照カ
   ウントが1である) ことをチェックします。

   バージョン 3.3 で追加.

Py_UCS4 PyUnicode_ReadChar(PyObject *unicode, Py_ssize_t index)

   文字列から文字を読み取ります。 マクロ版の "PyUnicode_READ_CHAR()"
   とは対照的に、この関数は *unicode* が Unicode オブジェクトであるこ
   と、インデックスが範囲内であることをチェックします。

   バージョン 3.3 で追加.

PyObject* PyUnicode_Substring(PyObject *str, Py_ssize_t start, Py_ssize_t end)
    *Return value: New reference.*

   *str* の文字インデックス *start* (端点を含む) から文字インデックス
   *end* (端点を含まず) までの部分文字列を返します。 負のインデックス
   はサポートされていません。

   バージョン 3.3 で追加.

Py_UCS4* PyUnicode_AsUCS4(PyObject *u, Py_UCS4 *buffer, Py_ssize_t buflen, int copy_null)

   文字列 *u* を UCS4 のバッファへコピーします。 *copy_null* が設定さ
   れている場合は、ヌル文字も含めます。 エラーが起きたときは、 "NULL"
   を返し、例外を設定します (*buflen* が *u* の長さより短かった場合に
   ついては、 "SystemError" が設定されます)。 成功したときは  *buffer*
   を返します。

   バージョン 3.3 で追加.

Py_UCS4* PyUnicode_AsUCS4Copy(PyObject *u)

   文字列 *u* を "PyMem_Malloc()" でメモリ確保された新しい UCS4 型のバ
   ッファにコピーします。 これが失敗した場合は、 "NULL" を返し
   "MemoryError" をセットします。 返されたバッファは必ず null コードポ
   イントが追加されています。

   バージョン 3.3 で追加.


廃止予定の Py_UNICODE API群
---------------------------

Deprecated since version 3.3, will be removed in version 4.0.

これらのAPI 関数は **PEP 393** の実装により廃止予定です。Python 3.x で
は削除されないため、拡張モジュールはこれらの関数を引き続き使えますが、
これらの関数の使用はパフォーマンスとメモリに影響があることを念頭に置い
てください。

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" のときだけです。

   バッファが "NULL" の場合、文字列の内容が埋められたなら
   "PyUnicode_KIND()" のようなアクセスマクロを使う前に
   "PyUnicode_READY()" を呼び出さなければなりません。

   "PyUnicode_FromKindAndData()", "PyUnicode_New()",
   "PyUnicode_FromWideChar()" のいずれかを使用するように移行してくださ
   い。

Py_UNICODE* PyUnicode_AsUnicode(PyObject *unicode)

   Unicode オブジェクトの "Py_UNICODE" 型の内部バッファへの読み出し専
   用のポインタを返すか、失敗のときには "NULL" を返します。 オブジェク
   トの "Py_UNICODE*" 表現形式が無い場合には作成します。 結果の
   "Py_UNICODE" 文字列には null コードポイントが含まれていることがあり
   、たいていの C 関数では、そのような文字列は切り詰められてしまうこと
   に注意してください。

   "PyUnicode_AsUCS4()", "PyUnicode_AsWideChar()",
   "PyUnicode_ReadChar()" や類似の新しい API を使用するように移行して
   ください。

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

   与えられた長さ *size* を持つ "Py_UNICODE" 型のバッファにある全ての
   decimal digit を、それらの10進の値に対応する 0 から 9 までの ASCII
   数字に置き換えた Unicode オブジェクトを生成します。 例外が起きた場
   合は "NULL" を返します。

Py_UNICODE* PyUnicode_AsUnicodeAndSize(PyObject *unicode, Py_ssize_t *size)

   "PyUnicode_AsUnicode()" に似てますが、さらに (追加の null 終端子を
   除いた) "Py_UNICODE()" 配列の長さを *size* に保存します。 結果の
   "Py_UNICODE" 文字列には null コードポイントが含まれていることがあり
   、たいていの C 関数では、そのような文字列は切り詰められてしまうこと
   に注意してください。

   バージョン 3.3 で追加.

Py_UNICODE* PyUnicode_AsUnicodeCopy(PyObject *unicode)

   終端に null コードポイントが付加された Unicode 文字列のコピーを作成
   します。 メモリ確保に失敗したときは "NULL" を返し "MemoryError" 例
   外を送出します。 そうでないときは新しくメモリ確保されたバッファを返
   します (このバッファを解放するときには "PyMem_Free()" を使ってくだ
   さい)。 結果の "Py_UNICODE" 文字列には null コードポイントが含まれ
   ていることがあり、たいていの C 関数では、そのような文字列は切り詰め
   られてしまうことに注意してください。

   バージョン 3.2 で追加.

   "PyUnicode_AsUCS4Copy()" や類似の新しい API を使用するように移行し
   てください。

Py_ssize_t PyUnicode_GetSize(PyObject *unicode)

   非推奨の "Py_UNICODE" 表現形式のサイズをコード単位で返します (サロ
   ゲートペアを2つとしています)。

   "PyUnicode_GetLength()" を使用するように移行してください。

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

   Unicode のサブタイプのインスタンスを、必要な場合は本物の Unicode オ
   ブジェクトにコピーします。 *obj* が (サブタイプではない) 既に本物の
   Unicode オブジェクトだった場合は、参照カウントを1つ増やした参照を返
   します。

   Unicode やそのサブタイプ以外のオブジェクトでは "TypeError" が引き起
   こされます。


ロケールエンコーディング
------------------------

現在のロケールエンコーディングはオペレーティングシステムのテキストをデ
コードするのに使えます。

PyObject* PyUnicode_DecodeLocaleAndSize(const char *str, Py_ssize_t len, const char *errors)
    *Return value: New reference.*

   Android では UTF-8 の文字列を、それ以外のプラットフォームでは現在の
   ロケールエンコーディングの文字列をデコードします。 サポートされてい
   るエラーハンドラは ""strict"" および ""surrogateescape"" (**PEP
   383**) です。 *errors* が "NULL" の場合は、デコーダは ""strict"" エ
   ラーハンドラを使用します。 *str* は終端が null 文字でなければならず
   、 null 文字を含めることはできません。

   "PyUnicode_DecodeFSDefaultAndSize()" を使って (Python の起動時に読
   み込まれるロケールエンコーディングの)
   "Py_FileSystemDefaultEncoding" の文字列をデコードします。

   この関数は Python の UTF-8 モードを無視します。

   参考: "Py_DecodeLocale()" 関数。

   バージョン 3.3 で追加.

   バージョン 3.7 で変更: この関数は、 Android 以外では現在のロケール
   エンコーディングを "surrogateescape" エラーハンドラで使うようになり
   ました。 以前は、 "Py_DecodeLocale()" が "surrogateescape" で使われ
   、現在のロケールエンコーディングは "strict" で使われていました。

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

   "PyUnicode_DecodeLocaleAndSize()" と似てますが、 "strlen()" を使っ
   て文字列の長さを計算します。

   バージョン 3.3 で追加.

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

   Android では UTF-8 で、それ以外のプラットフォームでは現在のロケール
   エンコーディングで Unicode オブジェクトをエンコードします。 サポー
   トされているエラーハンドラは ""strict"" および ""surrogateescape""
   (**PEP 383**) です。 *errors* が "NULL" の場合は、エンコーダは
   ""strict"" エラーハンドラを使用します。 "bytes" オブジェクトを返し
   ます。 *unicode* には null 文字を含められません。

   "PyUnicode_EncodeFSDefault()" を使って (Python の起動時に読み込まれ
   るロケールエンコーディングの) "Py_FileSystemDefaultEncoding" の文字
   列へエンコードします。

   この関数は Python の UTF-8 モードを無視します。

   参考: "Py_EncodeLocale()" 関数。

   バージョン 3.3 で追加.

   バージョン 3.7 で変更: この関数は、 Android 以外では現在のロケール
   エンコーディングを "surrogateescape" エラーハンドラで使うようになり
   ました。 以前は、 "Py_EncodeLocale()" が "surrogateescape" で使われ
   、現在のロケールエンコーディングは "strict" で使われていました。


ファイルシステムエンコーディング
--------------------------------

ファイル名や他の環境文字列のエンコードやデコードを行うには、
"Py_FileSystemDefaultEncoding" をエンコーディングとして使い、
"Py_FileSystemDefaultEncodeErrors" をエラーハンドラとして使うべきです
(**PEP 383** および **PEP 529**)。 引数の構文解析中にファイル名を
"bytes" にエンコードするには、 ""O&"" コンバーターを使い、
"PyUnicode_FSConverter()" を変換関数として渡すべきです:

int PyUnicode_FSConverter(PyObject* obj, void* result)

   ParseTuple コンバーター: "PyUnicode_EncodeFSDefault()" を使い -- 直
   接あるいは "os.PathLike" インターフェースを通して取得した -- "str"
   オブジェクトを "bytes" へエンコードします; "bytes" オブジェクトはそ
   のまま出力されます。 *result* は "PyBytesObject*" でなければならず
   、使われなくなったときには解放されなければなりません。

   バージョン 3.1 で追加.

   バージョン 3.6 で変更: *path-like object* を受け入れるようになりま
   した。

引数の構文解析中にファイル名を "str" にデコードするには、 ""O&"" コン
バーターを使い、 "PyUnicode_FSDecoder()" を変換関数として渡すのがよい
です:

int PyUnicode_FSDecoder(PyObject* obj, void* result)

   ParseTuple コンバーター: "PyUnicode_DecodeFSDefaultAndSize()" を使
   い -- 直接的あるいは間接的に "os.PathLike" インターフェースを通して
   取得した -- "bytes" オブジェクトを "str" へエンコードします;
   "bytes" オブジェクトはそのまま出力されます。 *result* は
   "PyUnicodeObject*" でなければならず、使われなくなったときには解放さ
   れなければなりません。

   バージョン 3.2 で追加.

   バージョン 3.6 で変更: *path-like object* を受け入れるようになりま
   した。

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

   "Py_FileSystemDefaultEncoding" と
   "Py_FileSystemDefaultEncodeErrors" エラーハンドラを使い、文字列をデ
   コードします。

   "Py_FileSystemDefaultEncoding" が設定されていない場合は、ロケールエ
   ンコーディングに差し戻されます。

   "Py_FileSystemDefaultEncoding" は起動時にロケールエンコーディングで
   初期化され、それ以降は変更できません。 現在のロケールエンコーディン
   グで文字列をデコードする必要がある場合は、
   "PyUnicode_DecodeLocaleAndSize()" を使ってください。

   参考: "Py_DecodeLocale()" 関数。

   バージョン 3.6 で変更: "Py_FileSystemDefaultEncodeErrors" エラーハ
   ンドラを使うようになりました。

PyObject* PyUnicode_DecodeFSDefault(const char *s)
    *Return value: New reference.*

   "Py_FileSystemDefaultEncoding" と
   "Py_FileSystemDefaultEncodeErrors" エラーハンドラを使い、 null 終端
   文字列をデコードします。

   "Py_FileSystemDefaultEncoding" が設定されていない場合は、ロケールエ
   ンコーディングに差し戻されます。

   文字列の長さが分かっている場合は、
   "PyUnicode_DecodeFSDefaultAndSize()" を使ってください。

   バージョン 3.6 で変更: "Py_FileSystemDefaultEncodeErrors" エラーハ
   ンドラを使うようになりました。

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

   "Py_FileSystemDefaultEncoding" エラーハンドラで Unicode オブジェク
   トを "Py_FileSystemDefaultEncoding" にエンコードし、 "bytes" を返し
   ます。 返される "bytes" オブジェクトは null バイトを含んでいるかも
   しれないことに注意してください。

   "Py_FileSystemDefaultEncoding" が設定されていない場合は、ロケールエ
   ンコーディングに差し戻されます。

   "Py_FileSystemDefaultEncoding" は起動時にロケールエンコーディングで
   初期化され、それ以降は変更できません。 現在のロケールエンコーディン
   グで文字列をエンコードする必要がある場合は、
   "PyUnicode_EncodeLocale()" を使ってください。

   参考: "Py_EncodeLocale()" 関数。

   バージョン 3.2 で追加.

   バージョン 3.6 で変更: "Py_FileSystemDefaultEncodeErrors" エラーハ
   ンドラを使うようになりました。


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 オブジェクトを生成し
   ます。 *size* として "-1" を渡すことで、 wcslen を使い自身で長さを
   計算しなければならないことを関数に指示します。 失敗すると "NULL" を
   返します。

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

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

wchar_t* PyUnicode_AsWideCharString(PyObject *unicode, Py_ssize_t *size)

   Convert the Unicode object to a wide character string. The output
   string always ends with a null character. If *size* is not "NULL",
   write the number of wide characters (excluding the trailing null
   termination character) into **size*. Note that the resulting
   "wchar_t" string might contain null characters, which would cause
   the string to be truncated when used with most C functions. If
   *size* is "NULL" and the "wchar_t*" string contains null characters
   a "ValueError" is raised.

   Returns a buffer allocated by "PyMem_Alloc()" (use "PyMem_Free()"
   to free it) on success. On error, returns "NULL" and **size* is
   undefined. Raises a "MemoryError" if memory allocation is failed.

   バージョン 3.2 で追加.

   バージョン 3.7 で変更: *size* が  "NULL" かつ "wchar_t*" 文字列が
   null 文字を含んでいた場合、 "ValueError" を送出します。


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

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

以下の API の多くが、 *encoding* と *errors* という二つの引数をとりま
す。これらのパラメータは、組み込みの文字列コンストラクタである "str()"
における同名のパラメータと同じ意味を持ちます。

*encoding* を "NULL" にすると、デフォルトエンコーディングである ASCII
を使います。 ファイルシステムに関する関数の呼び出しでは、ファイル名に
対するエンコーディングとして "PyUnicode_FSConverter()" を使わねばなり
ません。 これは内部で変数 "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* は、組み込み関数
   "str()" の同名のパラメータと同じ意味を持ちます。 使用する codec の
   検索は、 Python の codec レジストリを使って行います。 codec が例外
   を送出した場合には "NULL" を返します。

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

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

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 の bytes オブジェクトを返します。 *encoding* および
   *errors* は Unicode 型の "encode()" メソッドに与える同名のパラメー
   タと同じ意味を持ちます。 使用する codec の検索は、 Python の codec
   レジストリを使って行います。 codec が例外を送出した場合には "NULL"
   を返します。

   Deprecated since version 3.3, will be removed in version 4.0: 古い
   スタイルの "Py_UNICODE" APIの一部です;
   "PyUnicode_AsEncodedString()" を使用するように移行してください。


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

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

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

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

const char* PyUnicode_AsUTF8AndSize(PyObject *unicode, Py_ssize_t *size)

   Unicode オブジェクトを UTF-8 でエンコードしたものへのポインタを返し
   、エンコードされた表現形式でのサイズ (バイト単位) を *size* に格納
   します。 *size* 引数は "NULL" でも構いません; その場合はサイズは格
   納されません。 返されるバッファには、 null コードポイントがあるかど
   うかに関わらず、常に null バイトが終端に付加されています (これは
   *size* には勘定されません)。

   エラーが起きた場合は、 "NULL" を返し、例外を設定し、 *size* には何
   も格納しません。

   この関数は、 Unicode オブジェクトの文字列の UTF-8 表現形式をキャッ
   シュし、それ以降の呼び出しでは同じバッファへのポインタを返します。
   呼び出し側にバッファを解放する責任はありません。

   バージョン 3.3 で追加.

   バージョン 3.7 で変更: 返り値の型が "char *" ではなく "const char
   *" になりました。

const char* PyUnicode_AsUTF8(PyObject *unicode)

   "PyUnicode_AsUTF8AndSize()" とほぼ同じですが、サイズを格納しません
   。

   バージョン 3.3 で追加.

   バージョン 3.7 で変更: 返り値の型が "char *" ではなく "const char
   *" になりました。

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

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

   Deprecated since version 3.3, will be removed in version 4.0: 古い
   スタイルの "Py_UNICODE" APIの一部です; "PyUnicode_AsUTF8String()",
   "PyUnicode_AsUTF8AndSize()", "PyUnicode_AsEncodedString()" のいずれ
   かを使用するように移行してください。


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

以下は UTF-32 codec API です:

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

   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* にセットします。

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

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

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

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

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

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

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

   *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 マーク
   は出力されません。

   If "Py_UNICODE_WIDE" is not defined, surrogate pairs will be output
   as a single code point.

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

   Deprecated since version 3.3, will be removed in version 4.0: 古い
   スタイルの "Py_UNICODE" APIの一部です; "PyUnicode_AsUTF32String()"
   または "PyUnicode_AsEncodedString()" を使用するように移行してくださ
   い。


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

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

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

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

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 の
   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 マーク
   は出力されません。

   If "Py_UNICODE_WIDE" is defined, a single "Py_UNICODE" value may
   get represented as a surrogate pair. If it is not defined, each
   "Py_UNICODE" values is interpreted as a UCS-2 character.

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

   Deprecated since version 3.3, will be removed in version 4.0: 古い
   スタイルの "Py_UNICODE" APIの一部です; "PyUnicode_AsUTF16String()"
   または "PyUnicode_AsEncodedString()" を使用するように移行してくださ
   い。


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

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

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

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

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

   *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)
    *Return value: New reference.*

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

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

   Deprecated since version 3.3, will be removed in version 4.0: 古い
   スタイルの "Py_UNICODE" APIの一部です;
   "PyUnicode_AsEncodedString()" を使用するように移行してください。


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

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

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

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

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

   Deprecated since version 3.3, will be removed in version 4.0: 古い
   スタイルの "Py_UNICODE" APIの一部です;
   "PyUnicode_AsUnicodeEscapeString()" を使用するように移行してくださ
   い。


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

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

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

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

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

   Deprecated since version 3.3, will be removed in version 4.0: 古い
   スタイルの "Py_UNICODE" APIの一部です;
   "PyUnicode_AsRawUnicodeEscapeString()" または
   "PyUnicode_AsEncodedString()" を使用するように移行してください。


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

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

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

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

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

   Deprecated since version 3.3, will be removed in version 4.0: 古い
   スタイルの "Py_UNICODE" APIの一部です; "PyUnicode_AsLatin1String()"
   または "PyUnicode_AsEncodedString()" を使用するように移行してくださ
   い。


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

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

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

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

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

   Deprecated since version 3.3, will be removed in version 4.0: 古い
   スタイルの "Py_UNICODE" APIの一部です; "PyUnicode_AsASCIIString()"
   または "PyUnicode_AsEncodedString()" を使用するように移行してくださ
   い。


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

この codec は、多くの様々な codec を実装する際に使われるという点で特殊
な codec です (実際、 "encodings" パッケージに入っている標準 codecs の
ほとんどは、この codec を使っています)。 この codec は、文字のエンコー
ドやデコードに対応表を使います。 提供される対応表のオブジェクトは
"__getitem__()" マッピングインターフェースをサポートしていなければなり
ません; 辞書やシーケンスがそれに適しています。

以下は mapping codec の APIです:

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

   与えられた *mapping* オブジェクトを使って、 *size* バイトのエンコー
   ドされた文字列 *s* をデコードして Unicode オブジェクトを作成します
   。 codec が例外を発生させたときは "NULL" を返します。

   If *mapping* is "NULL", Latin-1 decoding will be applied.  Else
   *mapping* must map bytes ordinals (integers in the range from 0 to
   255) to Unicode strings, integers (which are then interpreted as
   Unicode ordinals) or "None".  Unmapped data bytes -- ones which
   cause a "LookupError", as well as ones which get mapped to "None",
   "0xFFFE" or "'\ufffe'", are treated as undefined mappings and cause
   an error.

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

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

   The *mapping* object must map Unicode ordinal integers to bytes
   objects, integers in the range from 0 to 255 or "None".  Unmapped
   character ordinals (ones which cause a "LookupError") as well as
   mapped to "None" are treated as "undefined mapping" and cause an
   error.

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 the result as a bytes object.  Return
   "NULL" if an exception was raised by the codec.

   Deprecated since version 3.3, will be removed in version 4.0: 古い
   スタイルの "Py_UNICODE" APIの一部です;
   "PyUnicode_AsCharmapString()" または "PyUnicode_AsEncodedString()"
   を使用するように移行してください。

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

PyObject* PyUnicode_Translate(PyObject *unicode, PyObject *mapping, const char *errors)
    *Return value: New reference.*

   Translate a Unicode object using the given *mapping* object and
   return the resulting Unicode object.  Return "NULL" if an exception
   was raised by the codec.

   The *mapping* object must map Unicode ordinal integers to Unicode
   strings, integers (which are then interpreted as Unicode ordinals)
   or "None" (causing deletion of the character).  Unmapped character
   ordinals (ones which cause a "LookupError") are left untouched and
   are copied as-is.

PyObject* PyUnicode_TranslateCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *mapping, 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.

   Deprecated since version 3.3, will be removed in version 4.0: 古い
   スタイルの "Py_UNICODE" APIの一部です; "PyUnicode_Translate()". ま
   たは 汎用の codec ベースの API を使用するように移行してください。


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

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

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

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

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

PyObject* PyUnicode_EncodeCodePage(int code_page, PyObject *unicode, const char *errors)
    *Return value: New reference.*

   指定されたコードページを使い Unicode オブジェクトをエンコードし、
   Python bytes オブジェクトを返します。 codec が例外を送出した場合に
   は "NULL" を返します。 "CP_ACP" コードページを使い MBCS エンコーダ
   を取得してください。

   バージョン 3.3 で追加.

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

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

   Deprecated since version 3.3, will be removed in version 4.0: 古い
   スタイルの "Py_UNICODE" APIの一部です; "PyUnicode_AsMBCSString()",
   "PyUnicode_EncodeCodePage()", "PyUnicode_AsEncodedString()" のいず
   れかを使用するように移行してください。


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


メソッドおよびスロット関数 (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* が負ならば分割数に制
   限を設けません。分割結果のリスト内には分割文字は含みません。

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)

   文字列に文字対応表 *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" を返
   します。

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" はエラーが発生して例外情報が設定
   されていることを表します。

Py_ssize_t PyUnicode_FindChar(PyObject *str, Py_UCS4 ch, Py_ssize_t start, Py_ssize_t end, int direction)

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

   バージョン 3.3 で追加.

   バージョン 3.7 で変更: *start* and *end* are now adjusted to behave
   like "str[start:end]".

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

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

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* を置換します。

int PyUnicode_Compare(PyObject *left, PyObject *right)

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

   この関数は、失敗したときに "-1" を返すので、 "PyErr_Occurred()" を
   呼び出して、エラーをチェックすべきです。

int PyUnicode_CompareWithASCIIString(PyObject *uni, const char *string)

   Compare a Unicode object, *uni*, with *string* and return "-1",
   "0", "1" for less than, equal, and greater than, respectively. It
   is best to pass only ASCII-encoded strings, but the function
   interprets the input string as ISO-8859-1 if it contains non-ASCII
   characters.

   この関数は例外を送出しません。

PyObject* PyUnicode_RichCompare(PyObject *left, PyObject *right, int op)
    *Return value: New reference.*

   Rich compare two Unicode strings and return one of the following:

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

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

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

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

void PyUnicode_InternInPlace(PyObject **string)

   Intern the argument **string* in place.  The argument must be the
   address of a pointer variable pointing to a Python Unicode string
   object.  If there is an existing interned string that is the same
   as **string*, it sets **string* to it (decrementing the reference
   count of the old string object and incrementing the reference count
   of the interned string object), otherwise it leaves **string* alone
   and interns it (incrementing its reference count). (Clarification:
   even though there is a lot of talk about reference counts, think of
   this function as reference-count-neutral; you own the object after
   the call if and only if you owned it before the call.)

PyObject* PyUnicode_InternFromString(const char *v)
    *Return value: New reference.*

   A combination of "PyUnicode_FromString()" and
   "PyUnicode_InternInPlace()", returning either a new Unicode string
   object that has been interned, or a new ("owned") reference to an
   earlier interned string object with the same value.
