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_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 でなければなりません (チェックはしません)。

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

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

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

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

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

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

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)
戻り値: 新たな参照.
sizewchar_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-終端してください。



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