データ整列化 (data marshalling) のサポート

以下のルーチン群は、 marshal モジュールと同じ形式を使った整列化オブジェクトを C コードから使えるようにします。整列化形式でデータを書き出す関数に加えて、データを読み戻す関数もあります。整列化されたデータを記録するファイルはバイナリモードで開かれていなければなりません。

数値は最小桁が先にくるように記録されます。

このモジュールでは、3つのバージョンのデータ形式をサポートしています。バージョン 0 は従来のもので、バージョン 1 は intern 化された文字列をファイル内で共有し、逆マーシャル化の時にも共有されるようにします。バージョン2は、浮動小数点数に対してバイナリフォーマットを利用します。Py_MARSHAL_VERSION は現在のバージョン (バージョン 2) を示します。

void PyMarshal_WriteLongToFile(long value, FILE *file, int version)

long 型の整数値 valuefile へ整列化します。この関数は value の下桁 32 ビットを書き込むだけです; ネイティブの long 型サイズには関知しません。 version はファイルフォーマットを示します。

void PyMarshal_WriteObjectToFile(PyObject *value, FILE *file, int version)

Python オブジェクト valuefile へ整列化します。version はファイルフォーマットを示します。

PyObject* PyMarshal_WriteObjectToString(PyObject *value, int version)
Return value: New reference.

value の整列化表現が入ったバイト列オブジェクトを返します。version はファイルフォーマットを示します。

以下の関数を使うと、整列化された値を読み戻せます。

XXX エラー検知はどうなってる? ファイルの末尾を読み出すと、 (それが関連したところでは) 常に負の数値が結果として生じるようであるけれども、エラーがない時に負の値が適切に処理されないことはクリアではない。それを知るための正しい方法は? これらのルーチンを使って非負の値だけ書くべきなのか?

long PyMarshal_ReadLongFromFile(FILE *file)

読み出し用に開かれた FILE* 内のデータストリームから、 C の long 型データを読み出して返します。この関数は、ネイティブの long のサイズに関係なく、 32 ビットの値だけを読み出せます。

エラーの場合例外を送出し -1 を返します。

int PyMarshal_ReadShortFromFile(FILE *file)

読み出し用に開かれた FILE* 内のデータストリームから、 C の short 型データを読み出して返します。この関数は、ネイティブの short のサイズに関係なく、 16 ビットの値だけを読み出せます。

エラーの場合例外を送出し -1 を返します。

PyObject* PyMarshal_ReadObjectFromFile(FILE *file)
Return value: New reference.

読み出し用に開かれた FILE* 内のデータストリームから Python オブジェクトを返します。

エラーの場合適切な例外 (EOFErrorTypeError) を設定し NULL を返します。

PyObject* PyMarshal_ReadLastObjectFromFile(FILE *file)
Return value: New reference.

読み出し用に開かれた FILE* 内のデータストリームから、 Python オブジェクトを読み出して返します。 PyMarshal_ReadObjectFromFile() と違い、この関数はファイル中に後続のオブジェクトが存在しないと仮定し、ファイルからメモリ上にファイルデータを一気にメモリにロードして、逆整列化機構がファイルから一バイトづつ読み出す代わりにメモリ上のデータを操作できるようにします。対象のファイルから他に何も読み出さないと分かっている場合にのみ、この関数を使ってください。

エラーの場合適切な例外 (EOFErrorTypeError) を設定し NULL を返します。

PyObject* PyMarshal_ReadObjectFromString(const char *data, Py_ssize_t len)
Return value: New reference.

data が指す len バイトのバイト列バッファ内のデータストリームから Python オブジェクトを返します。

エラーの場合適切な例外 (EOFErrorTypeError) を設定し NULL を返します。