目次

前のトピックへ

文字列/バイトオブジェクト

次のトピックへ

バッファーオブジェクト

このページ

Unicode オブジェクトと codec

Unicode オブジェクト

Unicode type

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

Py_UNICODE

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

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

PyUnicodeObject

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

PyTypeObject PyUnicode_Type

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

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

int PyUnicode_Check(PyObject *o)

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

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

int PyUnicode_CheckExact(PyObject *o)

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

バージョン 2.2 で追加.

Py_ssize_t PyUnicode_GET_SIZE(PyObject *o)

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

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

Py_ssize_t PyUnicode_GET_DATA_SIZE(PyObject *o)

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

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

Py_UNICODE* PyUnicode_AS_UNICODE(PyObject *o)

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

const char* PyUnicode_AS_DATA(PyObject *o)

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

int PyUnicode_ClearFreeList()

free list をクリアします。 開放できなかった要素数を返します。

バージョン 2.6 で追加.

Unicode 文字プロパティ

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

int Py_UNICODE_ISSPACE(Py_UNICODE ch)

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

int Py_UNICODE_ISLOWER(Py_UNICODE ch)

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

int Py_UNICODE_ISUPPER(Py_UNICODE ch)

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

int Py_UNICODE_ISTITLE(Py_UNICODE ch)

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

int Py_UNICODE_ISLINEBREAK(Py_UNICODE ch)

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

int Py_UNICODE_ISDECIMAL(Py_UNICODE ch)

ch が 10 進の数字文字かどうかに応じて 1 または 0 を返します。

int Py_UNICODE_ISDIGIT(Py_UNICODE ch)

ch が 2 進の数字文字かどうかに応じて 1 または 0 を返します。

int Py_UNICODE_ISNUMERIC(Py_UNICODE ch)

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

int Py_UNICODE_ISALPHA(Py_UNICODE ch)

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

int Py_UNICODE_ISALNUM(Py_UNICODE ch)

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

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

Py_UNICODE Py_UNICODE_TOLOWER(Py_UNICODE ch)

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

Py_UNICODE Py_UNICODE_TOUPPER(Py_UNICODE ch)

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

Py_UNICODE Py_UNICODE_TOTITLE(Py_UNICODE ch)

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

int Py_UNICODE_TODECIMAL(Py_UNICODE ch)

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

int Py_UNICODE_TODIGIT(Py_UNICODE ch)

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

double Py_UNICODE_TONUMERIC(Py_UNICODE ch)

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

Plain Py_UNICODE

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

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

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

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

Py_UNICODE* PyUnicode_AsUnicode(PyObject *unicode)

Unicode オブジェクトの内部バッファ Py_UNICODE に対する読み出し専用のポインタを返します。 unicode が Unicode オブジェクトでなければ NULL を返します。

Py_ssize_t PyUnicode_GetSize(PyObject *unicode)

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

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

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

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

型強制は以下のようにして行われます:

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

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

この API は、エラーが生じたときには NULL を返します。呼び出し側は返されたオブジェクトを decref する責任があります。

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

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

プラットフォームで wchar_t がサポートされていて、かつ wchar.h が提供されている場合、Python は以下の関数を使って wchar_t に対するインタフェースを確立することがあります。このサポートは、Python 自体の Py_UNICODE 型がシステムの wchar_t と同一の場合に最適化をもたらします。

wchar_t サポート

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

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

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

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

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

Unicode オブジェクトの内容を wchar_t バッファ w にコピーします。最大で size 個の wchar_t 文字を (末尾の 0-終端文字を除いて) コピーします。コピーした wchar_t 文字の個数を返します。エラーの時には -1 を返します。 wchar_t 文字列は 0-終端されている場合も、されていない場合も あります。関数の呼び出し手の責任で、アプリケーションの必要に応じて wchar_t 文字列を 0-終端してください。

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

組み込み codec (built-in codec)

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

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

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

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

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

Generic Codecs

以下は汎用 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 オブジェクトを生成します。 encodingerrors は、組み込み関数 unicode() の同名のパラメタと同じ意味を持ちます。使用する codec の検索は、 Python の codec レジストリを使って行います。codec が例外を送出した場合には NULL を返します。

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

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

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

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

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

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

UTF-8 Codecs

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

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

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

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

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

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

バージョン 2.4 で追加.

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

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

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

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

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

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

UTF-32 Codecs

以下は UTF-32 codec API です。

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

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

byteorder が非 NULL の時、デコーダは与えられたオーダーでデコードを開始します。

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

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

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

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

byteorderNULL のとき、コーデックは native order モードで開始します。

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

バージョン 2.6 で追加.

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

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

バージョン 2.6 で追加.

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

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

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

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

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

コーデックが例外を発生させた場合、 NULL を返します。

バージョン 2.6 で追加.

PyObject* PyUnicode_AsUTF32String(PyObject *unicode)

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

バージョン 2.6 で追加.

UTF-16 Codecs

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

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

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

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

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

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

デコードを完結した後、**byteorder* は入力データの終点現在に おけるバイトオーダーに設定されます。

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

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

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

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

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

バージョン 2.4 で追加.

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

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

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

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

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

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

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

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

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

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

UTF-7 Codecs

以下は UTF-7 コーデックのAPIです。

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

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

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

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

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

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

If base64SetO is nonzero, “Set O” (punctuation that has no otherwise special meaning) will be encoded in base-64. If base64WhiteSpace is nonzero, whitespace will be encoded in base-64. Both are set to zero for the Python “utf-7” codec. base64SetO が非ゼロのとき、 “Set O” 文字 (他の場合には何も特別な意味を持たない句読点) を base-64 エンコードします。 base64WhiteSpace が非ゼロのとき、空白文字を base-64 エンコードします。 Python の “utf-7” コーデックでは、両方ともゼロに設定されています。

Unicode-Escape Codecs

以下は “Unicode Escape” codec の APIです:

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

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

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

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

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

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

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

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

Raw-Unicode-Escape Codecs

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

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

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

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

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

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

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

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

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

Latin-1 Codecs

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

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

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

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

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

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

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

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

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

ASCII Codecs

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

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

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

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

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

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

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

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

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

Character Map Codecs

以下は mapping codec の APIです:

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

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

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

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

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

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

エンコードされた size バイトの文字列 s から mapping に指定されたオブジェクトを使って Unicode オブジェクトを 生成します。codec が例外を送出した場合には NULL を返します。 もし、 mappingNULL だった場合、latin-1でデコーディングされます。それ以外の場合では、 mapping はbyteに対する辞書マップ (訳注: sに含まれる文字のunsignedな値をint型でキーとして、値として変換対象の Unicode文字を表すUnicode文字列になっているような辞書) か、ルックアップテーブルとして扱われるunicode文字列です。

文字列(訳注: mappingがunicode文字列として渡された場合)の長さより大きい byte値や、(訳注: mappingにしたがって変換した結果が) U+FFFE “characters” になる Byte値は、”undefined mapping” として扱われます。

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

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

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

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

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

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

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

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

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

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

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

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

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

MBCS codecs for Windows

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

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

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

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

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

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

バージョン 2.5 で追加.

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

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

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

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

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

Methods & Slots

メソッドおよびスロット関数 (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 文字列からなるリストを返します。 sepNULL の場合、全ての空白文字を使って 分割を行います。それ以外の場合、指定された文字を使って分割を行います。最大で maxsplit 個までの分割を行います。 maxsplit が負ならば分割数に制限を設けません。分割結果のリスト内には分割文字は含みません。

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

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

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

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

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

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

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

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

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

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

int PyUnicode_Tailmatch(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)
Return value: New reference.

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

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

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

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

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

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

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

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

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

str 中に出現する substr を最大で maxcountreplstr に置換し、置換結果を Unicode オブジェクトにして 返します。 maxcount == -1 にすると、全ての substr を置換します。

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

int PyUnicode_Compare(PyObject *left, PyObject *right)

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

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

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

  • NULL を、例外が発生したときに返します。
  • Py_True もしくは Py_False を、正しく比較できた時に返します。
  • Py_NotImplemented を、leftとrightがのどちらかに対する PyUnicode_FromObject() が失敗したときに返します。(原文: in case the type combination is unknown)

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

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

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

新たな文字列オブジェクトを format および args から生成して返します; このメソッドは format % args のようなものです。引数 args はタプルでなくてはなりません。

int PyUnicode_Contains(PyObject *container, PyObject *element)

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

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