# 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（除非另有指定），必須在持有 GIL 的情況下呼叫函式。

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()` 以取得詳細資訊。

## 原始時鐘函式

類似於時鐘函式，但不會在出錯時設定例外，也不需要讓呼叫者持有 GIL。

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

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

int PyTime_MonotonicRaw(PyTime_t *result)

  類似於 `PyTime_Monotonic()`，但不會在出錯時設定例外，也不需要持有 GIL。

int PyTime_PerfCounterRaw(PyTime_t *result)

  類似於 `PyTime_PerfCounter()`，但不會在出錯時設定例外，也不需要持有 GIL。

int PyTime_TimeRaw(PyTime_t *result)

  類似於 `PyTime_Time()`，但不會在出錯時設定例外，也不需要持有 GIL。

## 轉換函式

double PyTime_AsSecondsDouble(PyTime_t t)

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

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