7.3.2 Unicode オブジェクト (Unicode object)

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

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

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

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

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

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

int PyUnicode_Check( PyObject *o): o が Unicode 文字列型か Unicode 文字列型のサブタイプであるときに真を返します。バージョン 2.2 で変更された仕様: サブタイプを引数にとれるようになりました

int PyUnicode_CheckExact( PyObject *o): o が Unicode 文字列型で、かつ Unicode 文字列型のサブタイプでないときに真を返します。バージョン 2.2 で新たに追加された仕様です。

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

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

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

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

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): ch を double に変換したものを返します。不可能ならば -1.0 を返します。このマクロは例外を送出しません。

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

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

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

Py_ssize_t PyUnicode_GetSize( PyObject *unicode): Unicode オブジェクトの長さを返します。

PyObject* PyUnicode_FromEncodedObject( PyObject *obj, const char *encoding, const char *errors)

戻り値: 新たな参照.

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

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

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

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

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

PyObject* PyUnicode_FromObject( PyObject *obj): 戻り値: 新たな参照.
PyUnicode_FromEncodedObject(obj, NULL, "strict") を行うショートカットで、インタプリタは Unicode への型強制が必要な際に常にこの関数を使います。

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

PyObject* PyUnicode_FromWideChar( const wchar_t *w, Py_ssize_t size): 戻り値: 新たな参照.
size の wchar_t バッファ w から Unicode オブジェクトを生成します。失敗すると NULL を返します。

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-終端してください。

ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。