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


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

Python 3.3 で **PEP 393** が実装されて以来、Unicode オブジェクトは内部
で複数の表現形式を使っています。 これにより、メモリ効率を維持しながら
Unicode 文字の全範囲を扱えます。 すべてのコードポイントが 128 未満、
256 未満、または 65536 未満の文字列は特別に扱います。 それ以外のコード
ポイントは 1114112 未満 (Unicode の全範囲) でなければなりません。

UTF-8 表現は必要に応じて作成され、Unicode オブジェクト内にキャッシュさ
れます。

内部バッファには、null 終端の C 文字列との互換性のため、末尾に常に追加
の null 文字が含まれます。 この追加文字は "PyUnicode_GetLength()" や、
以下の関数の各種 *size* 引数には数えません。

注釈:

  "Py_UNICODE" 表現は、非推奨の API とともに Python 3.12 で削除されま
  した。 詳細は **PEP 623** を参照してください。


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

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

PyTypeObject PyUnicode_Type
    * 次に属します: Stable ABI.*

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

PyTypeObject PyUnicodeIter_Type
    * 次に属します: Stable ABI.*

   この "PyTypeObject" のインスタンスは Python の Unicode イテレータ型
   を表します。 Unicode 文字列オブジェクトの反復処理に使われます。

type Py_UCS4
type Py_UCS2
type Py_UCS1
    * 次に属します: Stable ABI.*

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

   Added in version 3.3.

type PyASCIIObject
type PyCompactUnicodeObject
type PyUnicodeObject

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

   Added in version 3.3.

   特定のオブジェクトの構造は、次のマクロで判定できます。 これらのマク
   ロは失敗しませんが、引数が Python の Unicode オブジェクトでなければ
   動作は未定義です。

   PyUnicode_IS_COMPACT(o)

      *o* が "PyCompactUnicodeObject" 構造体を使っていれば真です。

      Added in version 3.3.

   PyUnicode_IS_COMPACT_ASCII(o)

      *o* が "PyASCIIObject" 構造体を使っていれば真です。

      Added in version 3.3.

以下の API は、Unicode オブジェクトの高速な検査や、内部の読み出し専用
データへのアクセスのための C マクロと静的インライン関数です:

int PyUnicode_Check(PyObject *obj)

   オブジェクト *obj* が Unicode オブジェクトか Unicode 型のサブタイプ
   のインスタンスである場合に真を返します。この関数は常に成功します。

int PyUnicode_CheckExact(PyObject *obj)

   オブジェクト *obj* が Unicode オブジェクトだがサブタイプのインスタ
   ンスでない場合に真を返します。この関数は常に成功します。

Py_ssize_t PyUnicode_GET_LENGTH(PyObject *unicode)

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

   Added in version 3.3.

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

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

   Added in version 3.3.

PyUnicode_1BYTE_KIND
PyUnicode_2BYTE_KIND
PyUnicode_4BYTE_KIND

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

   Added in version 3.3.

   バージョン 3.12 で変更: "PyUnicode_WCHAR_KIND" は削除されました。

int PyUnicode_KIND(PyObject *unicode)

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

   Added in version 3.3.

void *PyUnicode_DATA(PyObject *unicode)

   生の Unicode バッファへの void ポインタを返します。 *unicode* は "
   正統な" 表現形式の Unicode オブジェクトでなければなりません (ただし
   チェックはしません)。

   Added in version 3.3.

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

   文字列のゼロから始まる *index* の位置に、コードポイント *value* を
   書き込みます。

   *kind* の値と *data* ポインタは、文字列からそれぞれ
   "PyUnicode_KIND()" と "PyUnicode_DATA()" で取得したものでなければな
   りません。 "PyUnicode_WRITE()" の呼び出し中は、その文字列への参照を
   保持する必要があります。 "PyUnicode_WriteChar()" のすべての要件も適
   用されます。

   この関数は要件が満たされているか一切検査せず、ループ内での使用を想
   定しています。

   Added in version 3.3.

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

   正統な表現形式の *data* ("PyUnicode_DATA()" で取得したもの) からコ
   ードポイントを読み取ります。 検査は行いません。

   "PyUnicode_GetLength()" が返すインデックスの位置にある、末尾の null
   文字を読み取れます。

   Added in version 3.3.

Py_UCS4 PyUnicode_READ_CHAR(PyObject *unicode, Py_ssize_t index)

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

   "PyUnicode_GetLength()" が返すインデックスの位置にある、末尾の null
   文字を読み取れます。

   Added in version 3.3.

Py_UCS4 PyUnicode_MAX_CHAR_VALUE(PyObject *unicode)

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

   Added in version 3.3.

int PyUnicode_IsIdentifier(PyObject *unicode)
    * 次に属します: Stable ABI.*

   文字列が、 名前 (識別子とキーワード) 節の言語定義における有効な識別
   子であれば "1" を返します。それ以外の場合は "0" を返します。

   バージョン 3.9 で変更: 文字列が使用可能な状態でなくても、
   "Py_FatalError()" を呼び出さなくなりました。

unsigned int PyUnicode_IS_ASCII(PyObject *unicode)

   文字列に ASCII 文字しか含まれていなければ真を返します。
   "str.isascii()" と等価です。

   Added in version 3.2.

Py_hash_t PyUnstable_Unicode_GET_CACHED_HASH(PyObject *str)

   *これは Unstable APIです。マイナーリリースで予告なく変更されること
   があります。*

   "PyObject_Hash()" が返す *str* のハッシュ値がキャッシュ済みですぐに
   取得できれば、その値を返します。 それ以外の場合は例外を設定 *せずに
   * "-1" を返します。

   *str* が文字列でない場合 (つまり "PyUnicode_Check(obj)" が偽の場合)
   、動作は未定義です。

   この関数が例外で失敗することはありません。

   オブジェクトのハッシュ値がいつキャッシュされるかは保証されず、キャ
   ッシュされたハッシュ値の有無が文字列の他の性質を示すわけではないこ
   とに注意してください。


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

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

int Py_UNICODE_ISSPACE(Py_UCS4 ch)

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

int Py_UNICODE_ISLOWER(Py_UCS4 ch)

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

int Py_UNICODE_ISUPPER(Py_UCS4 ch)

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

int Py_UNICODE_ISTITLE(Py_UCS4 ch)

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

int Py_UNICODE_ISLINEBREAK(Py_UCS4 ch)

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

int Py_UNICODE_ISDECIMAL(Py_UCS4 ch)

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

int Py_UNICODE_ISDIGIT(Py_UCS4 ch)

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

int Py_UNICODE_ISNUMERIC(Py_UCS4 ch)

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

int Py_UNICODE_ISALPHA(Py_UCS4 ch)

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

int Py_UNICODE_ISALNUM(Py_UCS4 ch)

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

int Py_UNICODE_ISPRINTABLE(Py_UCS4 ch)

   *ch* が "str.isprintable()" の意味で表示可能な文字かどうかに応じて
   、"1" または "0" を返します。

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

Py_UCS4 Py_UNICODE_TOLOWER(Py_UCS4 ch)

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

Py_UCS4 Py_UNICODE_TOUPPER(Py_UCS4 ch)

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

Py_UCS4 Py_UNICODE_TOTITLE(Py_UCS4 ch)

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

int Py_UNICODE_TODECIMAL(Py_UCS4 ch)

   Return the character *ch* converted to a decimal positive integer.
   Return "-1" if this is not possible.  This function does not raise
   exceptions.

int Py_UNICODE_TODIGIT(Py_UCS4 ch)

   文字 *ch* を 1 桁の整数に変換して返します。 変換できなければ "-1"
   を返します。 この関数は例外を送出しません。

double Py_UNICODE_TONUMERIC(Py_UCS4 ch)

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

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

int Py_UNICODE_IS_SURROGATE(Py_UCS4 ch)

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

int Py_UNICODE_IS_HIGH_SURROGATE(Py_UCS4 ch)

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

int Py_UNICODE_IS_LOW_SURROGATE(Py_UCS4 ch)

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

Py_UCS4 Py_UNICODE_HIGH_SURROGATE(Py_UCS4 ch)

   "[0x10000; 0x10FFFF]" の範囲の Unicode コードポイントに対応する、
   UTF-16 の上位サロゲート ("0xD800" から "0xDBFF") を返します。

Py_UCS4 Py_UNICODE_LOW_SURROGATE(Py_UCS4 ch)

   "[0x10000; 0x10FFFF]" の範囲の Unicode コードポイントに対応する、
   UTF-16 の下位サロゲート ("0xDC00" から "0xDFFF") を返します。

Py_UCS4 Py_UNICODE_JOIN_SURROGATES(Py_UCS4 high, Py_UCS4 low)

   2 つのサロゲートコードポイントを結合し、1 つの "Py_UCS4" 値を返しま
   す。 *high* と *low* は、サロゲートペアのそれぞれ先頭と末尾のサロゲ
   ートです。 *high* は "[0xD800; 0xDBFF]"、*low* は "[0xDC00;
   0xDFFF]" の範囲内でなければなりません。


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

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

PyObject *PyUnicode_New(Py_ssize_t size, Py_UCS4 maxchar)
    *戻り値: 新しい参照。*

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

   エラー時には例外を設定して "NULL" を返します。

   作成後の文字列には、"PyUnicode_WriteChar()"、
   "PyUnicode_CopyCharacters()"、"PyUnicode_Fill()"、
   "PyUnicode_WRITE()" などで内容を書き込めます。 文字列はイミュータブ
   ルであることを想定しているため、変更中の結果を「使用」しないように
   注意してください。 特に、最終的な内容を書き込み終える前の文字列に対
   しては、以下を守る必要があります:

   * ハッシュ値を計算してはいけません。

   * "UTF-8 に変換" したり、他の「正統でない」表現形式に変換したりして
     はいけません。

   * 参照カウントを変更してはいけません。

   * 上記のいずれかを行う可能性のあるコードと共有してはいけません。

   この一覧はすべてを網羅しているわけではありません。 これらの使用を避
   けるのは利用側の責任であり、Python が常にこれらの要件を検査するとは
   限りません。

   書き込み途中の文字列オブジェクトを誤って公開しないよう、
   "PyUnicodeWriter" API または以下の "PyUnicode_From*" 関数のいずれか
   を使うことを推奨します。

   Added in version 3.3.

PyObject *PyUnicode_FromKindAndData(int kind, const void *buffer, Py_ssize_t size)
    *戻り値: 新しい参照。*

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

   必要に応じて、入力の *buffer* をコピーして正統な表現形式に変換しま
   す。 例えば *buffer* が UCS4 文字列 ("PyUnicode_4BYTE_KIND") で、
   UCS1 の範囲内のコードポイントだけで構成されていれば、UCS1
   ("PyUnicode_1BYTE_KIND") に変換します。

   すべての文字は [U+0000; U+10ffff] の範囲内でなければなりません。
   *kind* が "PyUnicode_4BYTE_KIND" で、文字列に無効な文字が含まれてい
   る場合、動作は未定義です。

   Added in version 3.3.

PyObject *PyUnicode_FromStringAndSize(const char *str, Py_ssize_t size)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

   char 型のバッファ *str* から Unicode オブジェクトを作成します。 バ
   イト列は UTF-8 でエンコードされているものとして解釈します。 バッフ
   ァの内容を新しいオブジェクトにコピーします。 戻り値は共有オブジェク
   トの場合があるため、データの変更は許されません。

   次の場合、この関数は "SystemError" を送出します:

   * *size* < 0 の場合。

   * *str* が "NULL" で、*size* > 0 の場合。

   バージョン 3.12 で変更: *size* > 0 のときに *str* == "NULL" を指定
   できなくなりました。

PyObject *PyUnicode_FromString(const char *str)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

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

PyObject *PyUnicode_FromFormat(const char *format, ...)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

   C の "printf()" 形式の書式文字列 *format* と可変個数の引数を受け取
   り、結果の Python Unicode 文字列のサイズを計算し、値を書式化した文
   字列を返します。 可変個数の引数は C の型でなければならず、ASCII で
   エンコードされた *format* 文字列の書式指定文字に厳密に対応していな
   ければなりません。

   一つの変換指定子は 2 またはそれ以上の文字を含み、その構成要素は以下
   からなりますが、示した順に出現しなければなりません:

   1. 指定子の開始を示す文字 "'%'" 。

   2. 変換フラグ (オプション)。一部の変換型の結果に影響します。

   3. 最小フィールド幅 (省略可能)。 "'*'" (アスタリスク) を指定した場
      合は、次の引数に実際の幅を int 型で渡します。 変換するオブジェク
      トは、最小フィールド幅と、省略可能な精度の後に渡します。

   4. 精度 (省略可能)。 "'.'" (ドット) の後に精度を指定します。 "'*'"
      (アスタリスク) を指定した場合は、次の引数に実際の精度を int 型で
      渡します。 変換する値は精度の後に渡します。

   5. 長さ修飾子 (省略可能)。

   6. 変換型。

   変換フラグ文字を以下に示します:

   +---------+---------------------------------------------------------------+
   | Flag    | 意味                                                          |
   |=========|===============================================================|
   | "0"     | 数値型に対してゼロによるパディングを行います。                |
   +---------+---------------------------------------------------------------+
   | "-"     | 変換した値を左寄せにします ("0" フラグも指定されている場合は  |
   |         | 、こち らが優先されます)。                                    |
   +---------+---------------------------------------------------------------+

   次の整数変換 ("d"、"i"、"o"、"u"、"x"、"X") の長さ修飾子は、引数の
   型 (デフォルトは int) を指定します:

   +------------+-------------------------------------------------------+
   | 修飾子     | 型                                                    |
   |============|=======================================================|
   | "l"        | long または unsigned long                             |
   +------------+-------------------------------------------------------+
   | "ll"       | long long または unsigned long long                   |
   +------------+-------------------------------------------------------+
   | "j"        | "intmax_t" または "uintmax_t"                         |
   +------------+-------------------------------------------------------+
   | "z"        | "size_t" または "ssize_t"                             |
   +------------+-------------------------------------------------------+
   | "t"        | "ptrdiff_t"                                           |
   +------------+-------------------------------------------------------+

   変換 "s" または "V" に付ける長さ修飾子 "l" は、引数の型が const
   wchar_t* であることを指定します。

   変換指定子を以下に示します:

   +-----------------------------------+-----------------------------------+-----------------------------------+
   | 変換指定子                        | 型                                | 備考                              |
   |===================================|===================================|===================================|
   | "%"                               | *n/a*                             | 文字 "%" そのもの。               |
   +-----------------------------------+-----------------------------------+-----------------------------------+
   | "d", "i"                          | 長さ修飾子で指定                  | 符号付き C 整数の 10 進表現。     |
   +-----------------------------------+-----------------------------------+-----------------------------------+
   | "u"                               | 長さ修飾子で指定                  | 符号なし C 整数の 10 進表現。     |
   +-----------------------------------+-----------------------------------+-----------------------------------+
   | "o"                               | 長さ修飾子で指定                  | 符号なし C 整数の 8 進表現。      |
   +-----------------------------------+-----------------------------------+-----------------------------------+
   | "x"                               | 長さ修飾子で指定                  | 符号なし C 整数の 16 進表現 (小文 |
   |                                   |                                   | 字)。                             |
   +-----------------------------------+-----------------------------------+-----------------------------------+
   | "X"                               | 長さ修飾子で指定                  | 符号なし C 整数の 16 進表現 (大文 |
   |                                   |                                   | 字)。                             |
   +-----------------------------------+-----------------------------------+-----------------------------------+
   | "c"                               | int                               | 1 文字。                          |
   +-----------------------------------+-----------------------------------+-----------------------------------+
   | "s"                               | const char* または const wchar_t* | null で終端された C の文字列。    |
   +-----------------------------------+-----------------------------------+-----------------------------------+
   | "p"                               | const void*                       | C ポインタの 16 進表記。          |
   |                                   |                                   | "printf("%p")" とほとんど同じです |
   |                                   |                                   | が、プラッ トフォームにおける     |
   |                                   |                                   | "printf" の定義に関わりなく先頭に |
   |                                   |                                   | リテラル "0x" が付きます。        |
   +-----------------------------------+-----------------------------------+-----------------------------------+
   | "A"                               | PyObject*                         | "ascii()" の戻り値。              |
   +-----------------------------------+-----------------------------------+-----------------------------------+
   | "U"                               | PyObject*                         | Unicode オブジェクト。            |
   +-----------------------------------+-----------------------------------+-----------------------------------+
   | "V"                               | PyObject*、const char*、または    | Unicode オブジェクト ("NULL" でも |
   |                                   | const wchar_t*                    | 構いません) と、2 番目の引数とし  |
   |                                   |                                   | て null 終端の C 文字配列を渡しま |
   |                                   |                                   | す (最初の引数が "NULL" の場合に  |
   |                                   |                                   | 使わ れます)。                    |
   +-----------------------------------+-----------------------------------+-----------------------------------+
   | "S"                               | PyObject*                         | "PyObject_Str()" の戻り値。       |
   +-----------------------------------+-----------------------------------+-----------------------------------+
   | "R"                               | PyObject*                         | "PyObject_Repr()" の戻り値。      |
   +-----------------------------------+-----------------------------------+-----------------------------------+
   | "T"                               | PyObject*                         | オブジェクトの型の完全修飾名を取  |
   |                                   |                                   | 得します。                        |
   |                                   |                                   | "PyType_GetFullyQualifiedName()"  |
   |                                   |                                   | を呼び出します。                  |
   +-----------------------------------+-----------------------------------+-----------------------------------+
   | "#T"                              | PyObject*                         | "T" 形式と同様ですが、モジュール  |
   |                                   |                                   | 名と修飾名の区切りにコロン (":")  |
   |                                   |                                   | を 使います。                     |
   +-----------------------------------+-----------------------------------+-----------------------------------+
   | "N"                               | PyTypeObject*                     | 型の完全修飾名を取得します。      |
   |                                   |                                   | "PyType_GetFullyQualifiedName()"  |
   |                                   |                                   | を呼 び出します。                 |
   +-----------------------------------+-----------------------------------+-----------------------------------+
   | "#N"                              | PyTypeObject*                     | "N" 形式と同様ですが、モジュール  |
   |                                   |                                   | 名と修飾名の区切りにコロン (":")  |
   |                                   |                                   | を 使います。                     |
   +-----------------------------------+-----------------------------------+-----------------------------------+

   注釈:

     幅の単位はバイト数ではなく文字数です。 精度の単位は、""%s"" と
     "PyObject*" 引数が "NULL" の場合の ""%V"" では、バイト数または
     "wchar_t" 要素数 (長さ修飾子 "l" を使う場合) です。 ""%A""、
     ""%U""、""%S""、""%R""、および "PyObject*" 引数が "NULL" でない場
     合の ""%V"" では、文字数です。

   注釈:

     C の "printf()" とは異なり、整数変換 ("d"、"i"、"u"、"o"、"x"、
     "X") で精度を指定しても "0" フラグは有効です。

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

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

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

   バージョン 3.12 で変更: 変換指定子 "o" と "X"、長さ修飾子 "j" と
   "t" に対応しました。 長さ修飾子をすべての整数変換に適用するようにな
   りました。 長さ修飾子 "l" を変換指定子 "s" と "V" に適用するように
   なりました。 可変の幅と精度 "*"、フラグ "-" に対応しました。認識で
   きない書式指定文字があると、"SystemError" を設定するようになりまし
   た。 以前のバージョンでは、書式文字列の残りすべてをそのまま結果の文
   字列にコピーし、余分な引数を無視していました。

   バージョン 3.13 で変更: "%T"、"%#T"、"%N"、"%#N" 形式のサポートが追
   加されました。

PyObject *PyUnicode_FromFormatV(const char *format, va_list vargs)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

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

PyObject *PyUnicode_FromObject(PyObject *obj)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

   必要に応じて、Unicode のサブタイプのインスタンスを、サブタイプでは
   ない新しい Unicode オブジェクトにコピーします。 *obj* がすでにサブ
   タイプではない Unicode オブジェクトの場合は、そのオブジェクトへの新
   しい *強参照* を返します。

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

PyObject *PyUnicode_FromOrdinal(int ordinal)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

   指定された Unicode コードポイント *ordinal* から Unicode オブジェク
   トを作成します。

   "ordinal" は "range(0x110000)" の範囲内でなければなりません。 範囲
   外の場合は "ValueError" を送出します。

PyObject *PyUnicode_FromEncodedObject(PyObject *obj, const char *encoding, const char *errors)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

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

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

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

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

void PyUnicode_Append(PyObject **p_left, PyObject *right)
    * 次に属します: Stable ABI.*

   文字列 *right* を *p_left* の末尾に追加します。 *p_left* は Unicode
   オブジェクトへの *強参照* を指す必要があります。
   "PyUnicode_Append()" はこの参照を解放します (「*盗みます*」)。

   エラー時には **p_left* に "NULL" を設定し、例外を設定します。

   成功すると **p_left* に結果への新しい強参照を設定します。

void PyUnicode_AppendAndDel(PyObject **p_left, PyObject *right)
    * 次に属します: Stable ABI.*

   "PyUnicode_Append()" と同様ですが、*right* の参照カウントを 1 減ら
   す点だけが異なります。

PyObject *PyUnicode_BuildEncodingMap(PyObject *string)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

   Return a mapping suitable for decoding a custom single-byte
   encoding. Given a Unicode string *string* of up to 256 characters
   representing an encoding table, returns either a compact internal
   mapping object or a dictionary mapping character ordinals to byte
   values. Raises a "TypeError" and return "NULL" on invalid input.

   Added in version 3.2.

const char *PyUnicode_GetDefaultEncoding(void)
    * 次に属します: Stable ABI.*

   デフォルトの文字列エンコーディングの名前 ""utf-8"" を返します。
   "sys.getdefaultencoding()" を参照してください。

   返された文字列を解放する必要はなく、インタープリタの終了まで有効で
   す。

Py_ssize_t PyUnicode_GetLength(PyObject *unicode)
    * 次に属します: Stable ABI (バージョン 3.7 より).*

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

   エラー時には例外を設定して "-1" を返します。

   長さには末尾の null 文字を数えません。

   Added in version 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" を返し、例外を設定します。そうでない場合は、コ
   ピーした文字数を返します。

   文字列はまだ「使用」していないものでなければなりません。 詳細は
   "PyUnicode_New()" を参照してください。

   Added in version 3.3.

int PyUnicode_Resize(PyObject **unicode, Py_ssize_t length);
    * 次に属します: Stable ABI.*

   Unicode オブジェクト **unicode* のサイズを、コードポイント数で指定
   した新しい *length* に変更します。

   文字列をその場でサイズ変更しようと試みるか、新しい文字列を作成しま
   す。 その場での変更は通常、新しい文字列を割り当てて文字をコピーする
   より高速です。

   成功すると **unicode* が新しい (サイズ変更後の) オブジェクトを指す
   ように変更し、"0" を返します。 それ以外の場合は "-1" を返して例外を
   設定し、**unicode* は変更しません。

   この関数は文字列の内容を検査しないため、結果は正統な表現形式の文字
   列でない場合があります。

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つ以上の参
   照を持ってた場合は失敗します。

   文字列はまだ「使用」していないものでなければなりません。 詳細は
   "PyUnicode_New()" を参照してください。

   書き込んだ文字数を返します。 エラー時には "-1" を返して例外を送出し
   ます。

   Added in version 3.3.

int PyUnicode_WriteChar(PyObject *unicode, Py_ssize_t index, Py_UCS4 character)
    * 次に属します: Stable ABI (バージョン 3.7 より).*

   文字列 *unicode* のゼロから始まる *index* の位置に *character* を書
   き込みます。 成功すると "0"、エラー時には例外を設定して "-1" を返し
   ます。

   この関数は *unicode* が Unicode オブジェクトであること、インデック
   スが範囲内であること、オブジェクトの参照カウントが 1 であることを検
   査します。 これらの検査を省略し、利用側の責任とする版については
   "PyUnicode_WRITE()" を参照してください。

   文字列はまだ「使用」していないものでなければなりません。 詳細は
   "PyUnicode_New()" を参照してください。

   Added in version 3.3.

Py_UCS4 PyUnicode_ReadChar(PyObject *unicode, Py_ssize_t index)
    * 次に属します: Stable ABI (バージョン 3.7 より).*

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

   成功すると文字を返します。 エラー時には例外を設定して "-1" を返しま
   す。

   "PyUnicode_GetLength()" が返すインデックスの位置にある、末尾の null
   文字は読み取れません。

   Added in version 3.3.

PyObject *PyUnicode_Substring(PyObject *unicode, Py_ssize_t start, Py_ssize_t end)
    *戻り値: 新しい参照。** 次に属します: Stable ABI (バージョン 3.7
   より).*

   文字インデックス *start* (含む) から *end* (含まない) までの
   *unicode* の部分文字列を返します。 負のインデックスはサポートしませ
   ん。 エラー時には例外を設定して "NULL" を返します。

   Added in version 3.3.

Py_UCS4 *PyUnicode_AsUCS4(PyObject *unicode, Py_UCS4 *buffer, Py_ssize_t buflen, int copy_null)
    * 次に属します: Stable ABI (バージョン 3.7 より).*

   文字列 *unicode* を UCS4 バッファにコピーします。 *copy_null* が設
   定されている場合は null 文字も含めます。 エラー時には "NULL" を返し
   て例外を設定します (特に *buflen* が *unicode* の長さより小さい場合
   は "SystemError" を設定します)。 成功すると *buffer* を返します。

   Added in version 3.3.

Py_UCS4 *PyUnicode_AsUCS4Copy(PyObject *unicode)
    * 次に属します: Stable ABI (バージョン 3.7 より).*

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

   Added in version 3.3.


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

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

PyObject *PyUnicode_DecodeLocaleAndSize(const char *str, Py_ssize_t length, const char *errors)
    *戻り値: 新しい参照。** 次に属します: Stable ABI (バージョン 3.7
   より).*

   Android と VxWorks では UTF-8、それ以外のプラットフォームでは現在の
   ロケールエンコーディングで文字列をデコードします。 対応するエラーハ
   ンドラは ""strict"" と ""surrogateescape"" (**PEP 383**) です。
   *errors* が "NULL" の場合、デコーダは ""strict"" エラーハンドラを使
   います。 *str* は null 文字で終端されている必要がありますが、内部に
   null 文字を含めることはできません。

   *ファイルシステムのエンコーディングとエラーハンドラ* で文字列をデコ
   ードするには、"PyUnicode_DecodeFSDefaultAndSize()" を使ってください
   。

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

   参考: "Py_DecodeLocale()" 関数。

   Added in version 3.3.

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

PyObject *PyUnicode_DecodeLocale(const char *str, const char *errors)
    *戻り値: 新しい参照。** 次に属します: Stable ABI (バージョン 3.7
   より).*

   "PyUnicode_DecodeLocaleAndSize()" と同様ですが、文字列の長さを
   "strlen()" で計算します。

   Added in version 3.3.

PyObject *PyUnicode_EncodeLocale(PyObject *unicode, const char *errors)
    *戻り値: 新しい参照。** 次に属します: Stable ABI (バージョン 3.7
   より).*

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

   *ファイルシステムのエンコーディングとエラーハンドラ* で文字列をエン
   コードするには、"PyUnicode_EncodeFSDefault()" を使ってください。

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

   参考: "Py_EncodeLocale()" 関数。

   Added in version 3.3.

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


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

*ファイルシステムのエンコーディングとエラーハンドラ* でエンコードとデ
コードを行う関数です (**PEP 383** と **PEP 529**)。

引数の解析中にファイル名を "bytes" にエンコードするには、変換関数に
"PyUnicode_FSConverter()" を渡して ""O&"" コンバータを使ってください:

int PyUnicode_FSConverter(PyObject *obj, void *result)
    * 次に属します: Stable ABI.*

   PyArg_Parse* コンバータ です。 直接、または "os.PathLike" インター
   フェースを通じて取得した "str" オブジェクトを、
   "PyUnicode_EncodeFSDefault()" で "bytes" にエンコードします。
   "bytes" オブジェクトはそのまま出力します。 *result* は PyObject* 型
   (または PyBytesObject* 型) の C 変数のアドレスでなければなりません
   。 成功すると、その変数に bytes オブジェクト への新しい *強参照* を
   設定し、ゼロ以外の値 ("Py_CLEANUP_SUPPORTED") を返します。 この参照
   は使わなくなったら解放する必要があります。 結果の内部に null バイト
   を含めることはできません。 失敗すると例外を設定して "0" を返します
   。

   *obj* が "NULL" の場合、*result* が指す変数に格納された強参照を解放
   し、"1" を返します。

   Added in version 3.1.

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

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

int PyUnicode_FSDecoder(PyObject *obj, void *result)
    * 次に属します: Stable ABI.*

   PyArg_Parse* コンバータ です。 直接、または "os.PathLike" インター
   フェースを通じて間接的に取得した "bytes" オブジェクトを、
   "PyUnicode_DecodeFSDefaultAndSize()" で "str" にデコードします。
   "str" オブジェクトはそのまま出力します。 *result* は PyObject* 型 (
   または PyUnicodeObject* 型) の C 変数のアドレスでなければなりません
   。 成功すると、その変数に Unicode オブジェクト への新しい *強参照*
   を設定し、ゼロ以外の値 ("Py_CLEANUP_SUPPORTED") を返します。 この参
   照は使わなくなったら解放する必要があります。 結果の内部に null 文字
   を含めることはできません。 失敗すると例外を設定して "0" を返します
   。

   *obj* が "NULL" の場合、*result* が指すオブジェクトへの強参照を解放
   し、"1" を返します。

   Added in version 3.2.

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

PyObject *PyUnicode_DecodeFSDefaultAndSize(const char *str, Py_ssize_t size)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

   *ファイルシステムのエンコーディングとエラーハンドラ* で文字列をデコ
   ードします。

   現在のロケールエンコーディングで文字列をデコードするには、
   "PyUnicode_DecodeLocaleAndSize()" を使ってください。

   参考: "Py_DecodeLocale()" 関数。

   バージョン 3.6 で変更: *ファイルシステムのエラーハンドラ* を使うよ
   うになりました。

PyObject *PyUnicode_DecodeFSDefault(const char *str)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

   *ファイルシステムのエンコーディングとエラーハンドラ* で null 終端の
   文字列をデコードします。

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

   バージョン 3.6 で変更: *ファイルシステムのエラーハンドラ* を使うよ
   うになりました。

PyObject *PyUnicode_EncodeFSDefault(PyObject *unicode)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

   *ファイルシステムのエンコーディングとエラーハンドラ* で Unicode オ
   ブジェクトをエンコードし、"bytes" を返します。 結果の "bytes" オブ
   ジェクトには null バイトが含まれる場合があることに注意してください
   。

   現在のロケールエンコーディングで文字列をエンコードするには、
   "PyUnicode_EncodeLocale()" を使ってください。

   参考: "Py_EncodeLocale()" 関数。

   Added in version 3.2.

   バージョン 3.6 で変更: *ファイルシステムのエラーハンドラ* を使うよ
   うになりました。


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

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

PyObject *PyUnicode_FromWideChar(const wchar_t *wstr, Py_ssize_t size)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

   指定された *size* の "wchar_t" バッファ *wstr* から Unicode オブジ
   ェクトを作成します。 *size* に "-1" を渡すと、この関数自身が
   "wcslen()" を使って長さを計算します。 失敗すると "NULL" を返します
   。

Py_ssize_t PyUnicode_AsWideChar(PyObject *unicode, wchar_t *wstr, Py_ssize_t size)
    * 次に属します: Stable ABI.*

   Unicode オブジェクトの内容を "wchar_t" バッファ *wstr* にコピーしま
   す。 最大で *size* 個の "wchar_t" 文字をコピーします (末尾に付く場
   合がある終端の null 文字を除きます)。 コピーした "wchar_t" 文字の数
   、またはエラー時には "-1" を返します。

   *wstr* が "NULL" の場合は、代わりに終端の null 文字も含めて
   *unicode* 全体を格納するのに必要な *size* を返します。

   結果の wchar_t* 文字列は、null 終端される場合とされない場合があるこ
   とに注意してください。 アプリケーションが null 終端を必要とする場合
   、wchar_t* 文字列が null 終端されていることを保証するのは呼び出し側
   の責任です。 また、wchar_t* 文字列の内部に null 文字が含まれる場合
   があり、その場合はほとんどの C 関数で文字列が途中で切れてしまうこと
   にも注意してください。

wchar_t *PyUnicode_AsWideCharString(PyObject *unicode, Py_ssize_t *size)
    * 次に属します: Stable ABI (バージョン 3.7 より).*

   Unicode オブジェクトをワイド文字列に変換します。 出力文字列は常に
   null 文字で終わります。 *size* が "NULL" でなければ、ワイド文字の数
   (末尾の終端 null 文字を除く) を **size* に書き込みます。 結果の
   "wchar_t" 文字列の内部に null 文字が含まれる場合があり、その場合は
   ほとんどの C 関数で文字列が途中で切れてしまうことに注意してください
   。 *size* が "NULL" で、wchar_t* 文字列の内部に null 文字が含まれて
   いる場合は、"ValueError" を送出します。

   成功すると、"PyMem_New" で割り当てたバッファを返します
   ("PyMem_Free()" で解放してください)。 エラー時には "NULL" を返し、
   **size* は未定義です。 メモリの割り当てに失敗すると "MemoryError"
   を送出します。

   Added in version 3.2.

   バージョン 3.7 で変更: *size* が "NULL" で、wchar_t* 文字列の内部に
   null 文字が含まれている場合は、"ValueError" を送出するようになりま
   した。


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

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

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

"encoding" に "NULL" を設定すると、デフォルトのエンコーディングである
UTF-8 を使います。 ファイルシステムの呼び出しでファイル名をエンコード
するには、"PyUnicode_FSConverter()" を使ってください。 これは内部で *
ファイルシステムのエンコーディングとエラーハンドラ* を使います。

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

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


汎用 codec
----------

次のマクロが用意されています:

Py_UNICODE_REPLACEMENT_CHARACTER

   Unicode コードポイント "U+FFFD" (置換文字)。

   *errors* 引数が "replace" の場合、この Unicode 文字をデコード時の置
   換文字として使います。

以下は汎用 codec の API です:

PyObject *PyUnicode_Decode(const char *str, Py_ssize_t size, const char *encoding, const char *errors)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

   エンコードされた文字列 *str* の *size* バイトをデコードし、Unicode
   オブジェクトを作成します。 *encoding* と *errors* の意味は、組み込
   み関数 "str()" の同名の引数と同じです。 使用する codec は Python の
   codec レジストリで検索します。 codec が例外を送出した場合は "NULL"
   を返します。

PyObject *PyUnicode_AsEncodedString(PyObject *unicode, const char *encoding, const char *errors)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

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


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

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

PyObject *PyUnicode_DecodeUTF8(const char *str, Py_ssize_t size, const char *errors)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

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

PyObject *PyUnicode_DecodeUTF8Stateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

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

PyObject *PyUnicode_AsUTF8String(PyObject *unicode)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

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

   文字列にサロゲートコードポイント ("U+D800" - "U+DFFF") が含まれてい
   ると、この関数は失敗します。

const char *PyUnicode_AsUTF8AndSize(PyObject *unicode, Py_ssize_t *size)
    * 次に属します: Stable ABI (バージョン 3.10 より).*

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

   エラー時には例外を設定し、*size* が "NULL" でなければ "-1" を格納し
   て、"NULL" を返します。

   文字列にサロゲートコードポイント ("U+D800" - "U+DFFF") が含まれてい
   ると、この関数は失敗します。

   この関数は Unicode オブジェクト内に文字列の UTF-8 表現をキャッシュ
   し、それ以降の呼び出しでは同じバッファへのポインタを返します。 呼び
   出し側がバッファを解放する必要はありません。 Unicode オブジェクトが
   ガベージコレクションで回収されるとバッファは解放され、それを指すポ
   インタは無効になります。

   Added in version 3.3.

   バージョン 3.7 で変更: 戻り値の型が "char *" から "const char *" に
   変更されました。

   バージョン 3.10 で変更: この関数が 制限付き API の一部になりました
   。

const char *PyUnicode_AsUTF8(PyObject *unicode)

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

   警告:

     この関数は、*unicode* の内部に含まれる null 文字 を特別に扱いませ
     ん。 そのため、返された文字列にも null 文字が残り、一部の C 関数
     はそれを文字列の末尾と解釈するため、途中で切れてしまう場合があり
     ます。 これが問題になる場合は、代わりに
     "PyUnicode_AsUTF8AndSize()" を使うことを推奨します。

   Added in version 3.3.

   バージョン 3.7 で変更: 戻り値の型が "char *" から "const char *" に
   変更されました。


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

以下は UTF-32 codec API です:

PyObject *PyUnicode_DecodeUTF32(const char *str, Py_ssize_t size, const char *errors, int *byteorder)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

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

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

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

   "*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 *str, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

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

PyObject *PyUnicode_AsUTF32String(PyObject *unicode)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

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


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

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

PyObject *PyUnicode_DecodeUTF16(const char *str, Py_ssize_t size, const char *errors, int *byteorder)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

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

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

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

   "*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 *str, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

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

PyObject *PyUnicode_AsUTF16String(PyObject *unicode)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

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


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

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

PyObject *PyUnicode_DecodeUTF7(const char *str, Py_ssize_t size, const char *errors)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

   UTF-7 でエンコードされた文字列 *str* の *size* バイトをデコードし、
   Unicode オブジェクトを作成します。 codec が例外を送出した場合は
   "NULL" を返します。

PyObject *PyUnicode_DecodeUTF7Stateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

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


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

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

PyObject *PyUnicode_DecodeUnicodeEscape(const char *str, Py_ssize_t size, const char *errors)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

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

PyObject *PyUnicode_AsUnicodeEscapeString(PyObject *unicode)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

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


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

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

PyObject *PyUnicode_DecodeRawUnicodeEscape(const char *str, Py_ssize_t size, const char *errors)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

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

PyObject *PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

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


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

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

PyObject *PyUnicode_DecodeLatin1(const char *str, Py_ssize_t size, const char *errors)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

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

PyObject *PyUnicode_AsLatin1String(PyObject *unicode)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

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


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

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

PyObject *PyUnicode_DecodeASCII(const char *str, Py_ssize_t size, const char *errors)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

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

PyObject *PyUnicode_AsASCIIString(PyObject *unicode)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

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


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

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

以下は mapping codec の APIです:

PyObject *PyUnicode_DecodeCharmap(const char *str, Py_ssize_t length, PyObject *mapping, const char *errors)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

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

   *mapping* が "NULL" の場合は Latin-1 でデコードします。 それ以外の
   場合、*mapping* はバイト値 (0 から 255 の範囲の整数) を、Unicode 文
   字列、整数 (Unicode の序数として解釈)、または "None" に対応づける必
   要があります。 対応のないバイト、つまり "LookupError" を引き起こす
   バイトや、"None"、"0xFFFE"、"'\ufffe'" に対応づけられたバイトは、未
   定義の対応として扱い、エラーになります。

PyObject *PyUnicode_AsCharmapString(PyObject *unicode, PyObject *mapping)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

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

   *mapping* オブジェクトは、Unicode の序数を表す整数を、bytes オブジ
   ェクト、0 から 255 の範囲の整数、または "None" に対応づける必要があ
   ります。 対応のない文字の序数 ("LookupError" を引き起こすもの) や、
   "None" に対応づけられたものは「未定義の対応」として扱い、エラーにな
   ります。

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

PyObject *PyUnicode_Translate(PyObject *unicode, PyObject *table, const char *errors)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

   文字列に文字対応表 *table* を適用して変換し、変換結果を Unicode オ
   ブジェクトで返します。codec が例外を発行した場合には "NULL" を返し
   ます。

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

   対応表には "__getitem__()" インターフェースだけが必要で、辞書やシー
   ケンスを使えます。 対応のない文字の序数 ("LookupError" を引き起こす
   もの) は変更せず、そのままコピーします。

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


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

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

PyObject *PyUnicode_DecodeMBCS(const char *str, Py_ssize_t size, const char *errors)
    *戻り値: 新しい参照。** 次に属します: Stable ABI on Windows (バー
   ジョン 3.7 より).*

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

PyObject *PyUnicode_DecodeMBCSStateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)
    *戻り値: 新しい参照。** 次に属します: Stable ABI on Windows (バー
   ジョン 3.7 より).*

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

PyObject *PyUnicode_DecodeCodePageStateful(int code_page, const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)
    *戻り値: 新しい参照。** 次に属します: Stable ABI on Windows (バー
   ジョン 3.7 より).*

   "PyUnicode_DecodeMBCSStateful()" と同様ですが、*code_page* で指定し
   たコードページを使います。

PyObject *PyUnicode_AsMBCSString(PyObject *unicode)
    *戻り値: 新しい参照。** 次に属します: Stable ABI on Windows (バー
   ジョン 3.7 より).*

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

PyObject *PyUnicode_EncodeCodePage(int code_page, PyObject *unicode, const char *errors)
    *戻り値: 新しい参照。** 次に属します: Stable ABI on Windows (バー
   ジョン 3.7 より).*

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

   Added in version 3.3.


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

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

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

PyObject *PyUnicode_Concat(PyObject *left, PyObject *right)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

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

PyObject *PyUnicode_Split(PyObject *unicode, PyObject *sep, Py_ssize_t maxsplit)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

   文字列を分割し、Unicode 文字列のリストを返します。 *sep* が "NULL"
   の場合は、すべての空白部分で分割します。 それ以外の場合は、指定され
   た区切り文字列で分割します。 分割回数は最大で *maxsplit* 回です。
   負の値なら回数に制限はありません。 結果のリストには区切り文字列を含
   めません。

   エラー時には例外を設定して "NULL" を返します。

   "str.split()" と等価です。

PyObject *PyUnicode_RSplit(PyObject *unicode, PyObject *sep, Py_ssize_t maxsplit)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

   "PyUnicode_Split()" と同様ですが、文字列の末尾から分割します。

   エラー時には例外を設定して "NULL" を返します。

   "str.rsplit()" と等価です。

PyObject *PyUnicode_Splitlines(PyObject *unicode, int keepends)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

   Unicode 文字列を改行位置で分割し、Unicode 文字列のリストを返します
   。 CRLF は 1 つの改行とみなします。 *keepends* が "0" の場合、結果
   の文字列に改行文字を含めません。

PyObject *PyUnicode_Partition(PyObject *unicode, PyObject *sep)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

   Unicode 文字列を *sep* が最初に現れる位置で分割し、区切り文字列より
   前の部分、区切り文字列自体、その後の部分を含む 3 要素のタプルを返し
   ます。 区切り文字列が見つからなければ、元の文字列と、その後に 2 つ
   の空文字列を含む 3 要素のタプルを返します。

   *sep* は空であってはなりません。

   エラー時には例外を設定して "NULL" を返します。

   "str.partition()" と等価です。

PyObject *PyUnicode_RPartition(PyObject *unicode, PyObject *sep)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

   "PyUnicode_Partition()" と同様ですが、Unicode 文字列を *sep* が最後
   に現れる位置で分割します。 区切り文字列が見つからなければ、2 つの空
   文字列と、その後に元の文字列を含む 3 要素のタプルを返します。

   *sep* は空であってはなりません。

   エラー時には例外を設定して "NULL" を返します。

   "str.rpartition()" と等価です。

PyObject *PyUnicode_Join(PyObject *separator, PyObject *seq)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

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

Py_ssize_t PyUnicode_Tailmatch(PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)
    * 次に属します: Stable ABI.*

   *substr* が "unicode[start:end]" の指定された側の端と一致すれば "1"
   、それ以外なら "0" を返します (*direction* == "-1" は前方一致、
   *direction* == "1" は後方一致を意味します)。 エラーが発生した場合は
   "-1" を返します。

Py_ssize_t PyUnicode_Find(PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)
    * 次に属します: Stable ABI.*

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

Py_ssize_t PyUnicode_FindChar(PyObject *unicode, Py_UCS4 ch, Py_ssize_t start, Py_ssize_t end, int direction)
    * 次に属します: Stable ABI (バージョン 3.7 より).*

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

   Added in version 3.3.

   バージョン 3.7 で変更: "unicode[start:end]" と同じ動作になるよう、
   *start* と *end* を調整するようになりました。

Py_ssize_t PyUnicode_Count(PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end)
    * 次に属します: Stable ABI.*

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

PyObject *PyUnicode_Replace(PyObject *unicode, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

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

int PyUnicode_Compare(PyObject *left, PyObject *right)
    * 次に属します: Stable ABI.*

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

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

   参考: "PyUnicode_Equal()" 関数。

int PyUnicode_Equal(PyObject *a, PyObject *b)
    * 次に属します: Stable ABI (バージョン 3.14 より).*

   2 つの文字列が等しいか調べます:

   * *a* と *b* が等しければ "1" を返します。

   * *a* と *b* が等しくなければ "0" を返します。

   * *a* または *b* が "str" オブジェクトでなければ、"TypeError" 例外
     を設定して "-1" を返します。

   *a* と *b* が "str" オブジェクトであれば、この関数は常に成功します
   。

   この関数は "str" のサブクラスにも使えますが、独自の "__eq__()" メソ
   ッドは考慮しません。

   参考: "PyUnicode_Compare()" 関数。

   Added in version 3.14.

int PyUnicode_EqualToUTF8AndSize(PyObject *unicode, const char *string, Py_ssize_t size)
    * 次に属します: Stable ABI (バージョン 3.13 より).*

   Unicode オブジェクトと、UTF-8 または ASCII でエンコードされていると
   解釈する char 型バッファを比較し、等しければ真 ("1")、それ以外なら
   偽 ("0") を返します。 Unicode オブジェクトにサロゲートコードポイン
   ト ("U+D800" - "U+DFFF") が含まれている場合や、C 文字列が有効な
   UTF-8 でない場合は、偽 ("0") を返します。

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

   Added in version 3.13.

int PyUnicode_EqualToUTF8(PyObject *unicode, const char *string)
    * 次に属します: Stable ABI (バージョン 3.13 より).*

   "PyUnicode_EqualToUTF8AndSize()" と同様ですが、*string* の長さを
   "strlen()" で計算します。 Unicode オブジェクトに null 文字が含まれ
   ている場合は、偽 ("0") を返します。

   Added in version 3.13.

int PyUnicode_CompareWithASCIIString(PyObject *unicode, const char *string)
    * 次に属します: Stable ABI.*

   Unicode オブジェクト *unicode* と *string* を比較して、左引数が右引
   数より小さい場合、左右引数が等価の場合、左引数が右引数より大きい場
   合に対して、それぞれ "-1", "0", "1" を返します。 ASCII エンコードさ
   れた文字列だけを渡すのが最も良いですが、入力文字列に非 ASCII 文字が
   含まれている場合は ISO-8859-1 として解釈します。

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

PyObject *PyUnicode_RichCompare(PyObject *left, PyObject *right, int op)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

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

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

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

   * 型の組み合わせが不明な場合は "Py_NotImplemented"。

   *op* に指定できる値は "Py_GT"、"Py_GE"、"Py_EQ"、"Py_NE"、"Py_LT"、
   "Py_LE" です。

PyObject *PyUnicode_Format(PyObject *format, PyObject *args)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

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

int PyUnicode_Contains(PyObject *unicode, PyObject *substr)
    * 次に属します: Stable ABI.*

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

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

void PyUnicode_InternInPlace(PyObject **p_unicode)
    * 次に属します: Stable ABI.*

   引数 *p_unicode をその場でインターンします。 引数は、Python の
   Unicode 文字列オブジェクトを指すポインタ変数のアドレスでなければな
   りません。 *p_unicode と同じ文字列がすでにインターンされていれば、
   *p_unicode をその文字列に設定します (元の文字列オブジェクトへの参照
   を解放し、インターン済み文字列オブジェクトへの新しい *強参照* を作
   成します)。 それ以外の場合は *p_unicode を変更せず、その文字列をイ
   ンターンします。

   (補足: 参照についての説明が多いですが、この関数は参照の数を変えない
   と考えてください。 渡すオブジェクトへの参照を所有している必要があり
   ます。 呼び出し後は渡した参照を所有しなくなり、代わりに結果への参照
   を新たに所有します。)

   この関数は例外を送出しません。 エラー時には、引数を変更せず、インタ
   ーンもしません。

   "str" のサブクラスのインスタンスはインターンできません。 つまり
   PyUnicode_CheckExact(*p_unicode) が真でなければなりません。 真でな
   ければ、他のエラーと同様に引数を変更しません。

   Note that interned strings are not “immortal”. You must keep a
   reference to the result to benefit from interning.

PyObject *PyUnicode_InternFromString(const char *str)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

   "PyUnicode_FromString()" と "PyUnicode_InternInPlace()" を組み合わ
   せたもので、静的に割り当てられた文字列用です。

   新しく作成してインターンした Unicode 文字列オブジェクト、または同じ
   値を持つ以前にインターン済みの文字列オブジェクトへの、新しい (「所
   有する」) 参照を返します。

   Python が結果への参照を保持したり、結果を *不死* にしたりすることで
   、すぐにはガベージコレクションで回収されない場合があります。 ユーザ
   ー入力など、異なる文字列を上限なくインターンする場合は、
   "PyUnicode_FromString()" と "PyUnicode_InternInPlace()" を直接呼び
   出すことを推奨します。

unsigned int PyUnicode_CHECK_INTERNED(PyObject *str)

   *str* がインターン済みならゼロ以外の値、そうでなければゼロを返しま
   す。 *str* 引数は文字列でなければなりませんが、検査は行いません。
   この関数は常に成功します。

   ゼロ以外の戻り値には、文字列が *どのように* インターンされているか
   についての追加情報が含まれる場合があります。 これらの値の意味や、各
   文字列のインターンに関する詳細は、CPython のバージョンによって変わ
   る可能性があります。


PyUnicodeWriter
===============

"PyUnicodeWriter" API を使って Python の "str" オブジェクトを作成でき
ます。

Added in version 3.14.

type PyUnicodeWriter

   Unicode ライターのインスタンスです。

   成功時には "PyUnicodeWriter_Finish()"、エラー時には
   "PyUnicodeWriter_Discard()" でインスタンスを破棄する必要があります
   。

   この API は **スレッドセーフではありません**。 複数のスレッドでライ
   ターを共有するには、クリティカルセクションまたはロックが必要です。

PyUnicodeWriter *PyUnicodeWriter_Create(Py_ssize_t length)

   Unicode ライターのインスタンスを作成します。

   *length* は "0" 以上でなければなりません。

   *length* が "0" より大きければ、*length* 文字分の内部バッファを事前
   に割り当てます。

   エラー時には例外を設定して "NULL" を返します。

PyObject *PyUnicodeWriter_Finish(PyUnicodeWriter *writer)

   最終的な Python の "str" オブジェクトを返し、ライターのインスタンス
   を破棄します。

   エラー時には例外を設定して "NULL" を返します。

   この呼び出しの後、ライターのインスタンスは無効になります。

void PyUnicodeWriter_Discard(PyUnicodeWriter *writer)

   内部の Unicode バッファを破棄し、ライターのインスタンスを破棄します
   。

   *writer* が "NULL" の場合は何もしません。

   この呼び出しの後、ライターのインスタンスは無効になります。

int PyUnicodeWriter_WriteChar(PyUnicodeWriter *writer, Py_UCS4 ch)

   Unicode 文字 *ch* を 1 文字、*writer* に書き込みます。

   成功すると "0" を返します。 エラー時には例外を設定し、ライターは変
   更せずに "-1" を返します。

int PyUnicodeWriter_WriteUTF8(PyUnicodeWriter *writer, const char *str, Py_ssize_t size)

   文字列 *str* を UTF-8 の strict モードでデコードし、結果を *writer*
   に書き込みます。

   *size* はバイト単位の文字列の長さです。 *size* が "-1" の場合は
   "strlen(str)" を呼び出して文字列の長さを取得します。

   成功すると "0" を返します。 エラー時には例外を設定し、ライターは変
   更せずに "-1" を返します。

   "PyUnicodeWriter_DecodeUTF8Stateful()" も参照してください。

int PyUnicodeWriter_WriteASCII(PyUnicodeWriter *writer, const char *str, Py_ssize_t size)

   ASCII 文字列 *str* を *writer* に書き込みます。

   *size* はバイト単位の文字列の長さです。 *size* が "-1" の場合は
   "strlen(str)" を呼び出して文字列の長さを取得します。

   *str* は ASCII 文字だけを含む必要があります。 非 ASCII 文字が含まれ
   ている場合、動作は未定義です。

   成功すると "0" を返します。 エラー時には例外を設定し、ライターは変
   更せずに "-1" を返します。

int PyUnicodeWriter_WriteWideChar(PyUnicodeWriter *writer, const wchar_t *str, Py_ssize_t size)

   ワイド文字列 *str* を *writer* に書き込みます。

   *size* はワイド文字の数です。 *size* が "-1" の場合は "wcslen(str)"
   を呼び出して文字列の長さを取得します。

   成功すると "0" を返します。 エラー時には例外を設定し、ライターは変
   更せずに "-1" を返します。

int PyUnicodeWriter_WriteUCS4(PyUnicodeWriter *writer, const Py_UCS4 *str, Py_ssize_t size)

   UCS4 文字列 *str* を *writer* に書き込みます。

   *size* は UCS4 文字の数です。

   すべての文字は [U+0000; U+10ffff] の範囲内でなければなりません。 文
   字列に無効な文字が含まれている場合、動作は未定義です。

   成功すると "0" を返します。 エラー時には例外を設定し、ライターは変
   更せずに "-1" を返します。

int PyUnicodeWriter_WriteStr(PyUnicodeWriter *writer, PyObject *obj)

   *obj* に対して "PyObject_Str()" を呼び出し、結果を *writer* に書き
   込みます。

   成功すると "0" を返します。 エラー時には例外を設定し、ライターは変
   更せずに "-1" を返します。

   "__str__()" メソッドをオーバーライドする "str" サブクラスを書き込む
   には、"PyUnicode_FromObject()" を使って元の文字列を取得できます。

int PyUnicodeWriter_WriteRepr(PyUnicodeWriter *writer, PyObject *obj)

   *obj* に対して "PyObject_Repr()" を呼び出し、結果を *writer* に書き
   込みます。

   *obj* が "NULL" の場合は、文字列 ""<NULL>"" を *writer* に書き込み
   ます。

   成功すると "0" を返します。 エラー時には例外を設定し、ライターは変
   更せずに "-1" を返します。

   バージョン 3.14.4 で変更: "NULL" のサポートが追加されました。

int PyUnicodeWriter_WriteSubstring(PyUnicodeWriter *writer, PyObject *str, Py_ssize_t start, Py_ssize_t end)

   部分文字列 "str[start:end]" を *writer* に書き込みます。

   *str* は Python の "str" オブジェクトでなければなりません。 *start*
   は 0 以上かつ *end* 以下、*end* は *str* の長さ以下でなければなりま
   せん。

   成功すると "0" を返します。 エラー時には例外を設定し、ライターは変
   更せずに "-1" を返します。

int PyUnicodeWriter_Format(PyUnicodeWriter *writer, const char *format, ...)

   "PyUnicode_FromFormat()" と同様ですが、出力を直接 *writer* に書き込
   みます。

   成功すると "0" を返します。 エラー時には例外を設定し、ライターは変
   更せずに "-1" を返します。

int PyUnicodeWriter_DecodeUTF8Stateful(PyUnicodeWriter *writer, const char *string, Py_ssize_t length, const char *errors, Py_ssize_t *consumed)

   エラーハンドラ *errors* を使って文字列 *str* を UTF-8 からデコード
   し、結果を *writer* に書き込みます。

   *size* はバイト単位の文字列の長さです。 *size* が "-1" の場合は
   "strlen(str)" を呼び出して文字列の長さを取得します。

   *errors* は ""replace"" などの エラーハンドラ の名前です。 *errors*
   が "NULL" の場合は strict エラーハンドラを使います。

   *consumed* が "NULL" でなければ、成功時に **consumed* にデコードし
   たバイト数を設定します。 *consumed* が "NULL" の場合は、末尾の不完
   全な UTF-8 バイト列をエラーとして扱います。

   成功すると "0" を返します。 エラー時には例外を設定し、ライターは変
   更せずに "-1" を返します。

   "PyUnicodeWriter_WriteUTF8()" も参照してください。


非推奨の API
============

以下の API は非推奨です。

type Py_UNICODE

   これは "wchar_t" の typedef であり、プラットフォームに応じて 16 ビ
   ットまたは 32 ビットの型になります。 代わりに "wchar_t" を直接使っ
   てください。

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

   バージョン 3.13 で非推奨、バージョン 3.15 で削除.

int PyUnicode_READY(PyObject *unicode)

   何もせずに "0" を返します。 この API は後方互換性のためだけに残され
   ていますが、削除する予定はありません。

   Added in version 3.3.

   バージョン 3.10 で非推奨: Python 3.12 以降、この API は何もしません
   。 以前は、古い API ("PyUnicode_FromUnicode()" など) で作成した文字
   列ごとに呼び出す必要がありました。

unsigned int PyUnicode_IS_READY(PyObject *unicode)

   何もせずに "1" を返します。 この API は後方互換性のためだけに残され
   ていますが、削除する予定はありません。

   Added in version 3.3.

   バージョン 3.14 で非推奨: Python 3.12 以降、この API は何もしません
   。 以前は、"PyUnicode_READY()" が必要かどうかを調べるために呼び出せ
   ました。
