資料 marshal 操作的支援
***********************

這些例程允許 C 程式碼使用與 "marshal" 模組相同的資料格式來處理序列化物
件。有函式可以將資料寫入序列化格式，還有其他函式可以用來讀取回資料。用
來儲存 marshal 過的資料的檔案必須以二進位模式開啟。

數值會以最低有效位元組 (the least significant byte) 優先的方式儲存。

這個模組支援兩個版本的資料格式：版本 0 是歷史版本，版本 1 在檔案中共享
駐留字串 (interned strings)，並在 unmarshal 時使用。版本 2 使用二進位
格式來儲存浮點數。"Py_MARSHAL_VERSION" 表示目前的檔案格式（目前為 2）
。

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

   將一個 long 整數 *value* marshal 為 *file*。這只會寫入 *value* 的最
   低有效 32 位元；無論原生 long 型別的大小如何。*version* 表示檔案的
   格式。

   這個函式可能會失敗，這時會設定錯誤指示器。使用 "PyErr_Occurred()"
   來檢查是否發生錯誤。

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

   將一個 Python 物件 *value* marshal 為 *file*。*version* 表示檔案的
   格式。

   這個函式可能會失敗，這時會設定錯誤指示器。使用 "PyErr_Occurred()"
   來檢查是否發生錯誤。

PyObject *PyMarshal_WriteObjectToString(PyObject *value, int version)
    *回傳值：新的參照。*

   回傳一個位元組物件，包含 *value* 的 marshal 表示。*version* 為檔案
   的格式。

以下函式允許將 marshal 過後的值讀取回來。

long PyMarshal_ReadLongFromFile(FILE *file)

   從一個為讀取而開啟的 FILE* 中的資料串流回傳一個 C long。無論 long
   的原生大小如何，這個函式只能讀取 32 位元的值。

   在錯誤發生時，會設定合適的例外（"EOFError"）並回傳 "-1"。

int PyMarshal_ReadShortFromFile(FILE *file)

   從一個為讀取而開啟的 FILE* 中的資料串流回傳一個 C short。無論 short
   的原生大小如何，這個函式只能讀取 16 位元的值。

   在錯誤發生時，會設定合適的例外（"EOFError"）並回傳 "-1"。

PyObject *PyMarshal_ReadObjectFromFile(FILE *file)
    *回傳值：新的參照。*

   從一個為讀取而開啟的 FILE* 中的資料串流回傳一個 Python 物件。

   在錯誤發生時，會設定合適的例外（"EOFError"、"ValueError" 或
   "TypeError"）並回傳 "NULL"。

PyObject *PyMarshal_ReadLastObjectFromFile(FILE *file)
    *回傳值：新的參照。*

   Return a Python object from the data stream in a FILE* opened for
   reading.  Unlike "PyMarshal_ReadObjectFromFile()", this function
   assumes that no further objects will be read from the file,
   allowing it to aggressively load file data into memory so that the
   de-serialization can operate from data in memory rather than
   reading a byte at a time from the file.  Only use this variant if
   you are certain that you won't be reading anything else from the
   file.

   在錯誤發生時，會設定合適的例外（"EOFError"、"ValueError" 或
   "TypeError"）並回傳 "NULL"。

PyObject *PyMarshal_ReadObjectFromString(const char *data, Py_ssize_t len)
    *回傳值：新的參照。*

   從一個包含 *len* 位元組、被 *data* 指向的位元組緩衝區中的資料串流回
   傳一個 Python 物件。

   在錯誤發生時，會設定合適的例外（"EOFError"、"ValueError" 或
   "TypeError"）並回傳 "NULL"。
