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

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

`Py_UNICODE`
  この型は 16 ビットの符号なしストレージ型を表し、Unicode 序数 (Unicode ordinal) を保持するための基礎単位として Python が内部的 に使います。`wchar_t` が利用でき、かつ 16 ビットである場合、 `Py_UNICODE` は `wchar_t` を typedef でエイリアスされ、 ネイティブプラットフォームに対する互換性を高めます。その他の プラットフォームでは全て、`Py_UNICODE` は `unsigned short` の typedef によるエイリアスになります。

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

PyTypeObject `PyUnicode_Type`
  この `PyTypeObject` のインスタンスは Python の Unicode 型を 表現します。

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

int `PyUnicode_Check`( | PyObject *o)

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

int `PyUnicode_CheckExact`( | PyObject *o)

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

int `PyUnicode_GET_SIZE`( | PyObject *o)

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

int `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, int size)

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

Py_UNICODE* `PyUnicode_AsUnicode`( | PyObject *unicode)

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

int `PyUnicode_GetSize`( | PyObject *unicode)

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

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

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

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

  1. obj が Unicode オブジェクトの場合、オブジェクトそのままを、 参照カウントをインクリメントして返します。注意: Unicode オブジェクトは デコードできません; encoding に `NULL` でない値を渡すと、 `TypeError` になります。

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

  3. その他のオブジェクトは例外を引き起こします。

  この 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, int size)

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

int `PyUnicode_AsWideChar`( | PyUnicodeObject *unicode, wchar_t *w, int size)

  Unicode オブジェクトの内容を `wchar_t` バッファ w にコピーします。最大で size 個の `wchar_t` 文字を コピーします。コピーされた`wchar_t` 文字の個数を返します。 エラーの時には -1 を返します。