PyTime C API
************

在 3.13 版被加入.

時鐘 C API 提供對系統時鐘的存取。它類似於 Python 的 "time" 模組。

對於與 "datetime" 模組相關的 C API，請參閱 DateTime 物件。


型別
====

type PyTime_t

   以奈秒為單位的時間戳記或持續時長，以有符號的 64 位元整數表示。

   時間戳記的參照點取決於所使用的時鐘。例如 "PyTime_Time()" 回傳相對於
   UNIX 紀元 (UNIX epoch) 的時間戳記。

   支援的範圍約為 [-292.3 年；+292.3 年]。以 Unix 紀元 (1970 年 1 月 1
   日) 為參照，支援的日期範圍約為 [1677-09-21; 2262-04-11]。確切的限制
   是以常數的形式公開出來：

PyTime_t PyTime_MIN

   "PyTime_t" 的最小值。

PyTime_t PyTime_MAX

   "PyTime_t" 的最大值。


時鐘函式
========

以下的函式接受一個指向 PyTime_t 的指標，並將其設定為特定時鐘的值。每個
時鐘的詳細資訊紀錄在相對應的 Python 函式說明文件中。

函式成功時會回傳 "0" 或在失敗時回傳 "-1"（並設定一個例外）。

在整數溢位時，它們會設定 "PyExc_OverflowError" 例外，並將 "*result" 設
定為夾在 "[PyTime_MIN; PyTime_MAX]" 範圍內的值。（在目前的系統上，整數
溢位很可能是由於錯誤設定的系統時間所造成。）

如同任何其他 C API（除非另有指定），必須在具有 *attached thread state*
的情況下呼叫函式。

int PyTime_Monotonic(PyTime_t *result)

   讀取單調時鐘。請參閱 "time.monotonic()" 取得此時鐘的重要詳細資訊。

int PyTime_PerfCounter(PyTime_t *result)

   讀取效能計數器。請參閱 "time.perf_counter()" 以取得此時鐘的重要詳細
   資訊。

int PyTime_Time(PyTime_t *result)

   讀取「牆上時鐘 (wall clock)」的時間。請參閱 "time.time()" 以取得詳
   細資訊。


原始時鐘函式
============

類似於時鐘函式，但不會在出錯時設定例外，也不需要呼叫者擁有 *attached
thread state*。

成功時函式會回傳 "0"。

失敗時，它們會將 "*result" 設為 "0" 並回傳 "-1", 而*不*設定例外。要取
得錯誤原因，請*附加*一個 *thread state*，並呼叫常規（非 "Raw"）函式。
請注意，常規函式可能會在 "Raw" 的函式失敗後成功。

int PyTime_MonotonicRaw(PyTime_t *result)

   類似於 "PyTime_Monotonic()"，但不會在錯誤時設定例外，也不需要擁有
   *attached thread state*。

int PyTime_PerfCounterRaw(PyTime_t *result)

   類似於 "PyTime_PerfCounter()"，但不會在錯誤時設定例外，也不需要擁有
   *attached thread state*。

int PyTime_TimeRaw(PyTime_t *result)

   類似於 "PyTime_Time()"，但不會在錯誤時設定例外，也不需要擁有
   *attached thread state*。


轉換函式
========

double PyTime_AsSecondsDouble(PyTime_t t)

   將時間戳記轉換為 C double 的秒數。

   此函式不會失敗，但請注意 double 對於大數值的精確度有限。
