Datetime API#

NumPy 在內部使用 int64 計數器和單位元資料結構來表示日期。時間差也以類似方式使用 int64 和單位元資料結構來表示。以下描述的函式可用於協助在 C 語言中於 ISO 8601 日期字串、NumPy datetime 和 Python datetime 物件之間進行轉換。

資料型別#

除了 npy_datetime 和 npy_timedelta 這兩個 npy_int64 的 typedef 之外，NumPy 還定義了兩個額外的結構，用於表示時間單位元資料和 datetime 的「展開」檢視。

type PyArray_DatetimeMetaData#

表示 datetime 單位元資料。

typedef struct {
    NPY_DATETIMEUNIT base;
    int num;
} PyArray_DatetimeMetaData;
NPY_DATETIMEUNIT base#

datetime 的單位。

int num#

單位的乘數。

type npy_datetimestruct#

datetime 值的「展開」檢視

typedef struct {
    npy_int64 year;
    npy_int32 month, day, hour, min, sec, us, ps, as;
} npy_datetimestruct;
enum NPY_DATETIMEUNIT#

NumPy 支援的時間單位。列舉變體名稱中的 “FR” 是 frequency（頻率）的縮寫。

enumerator NPY_FR_ERROR#

錯誤或未確定的單位。

enumerator NPY_FR_Y#

年

enumerator NPY_FR_M#

月

enumerator NPY_FR_W#

週

enumerator NPY_FR_D#

天

enumerator NPY_FR_h#

小時

enumerator NPY_FR_m#

分鐘

enumerator NPY_FR_s#

秒

enumerator NPY_FR_ms#

毫秒

enumerator NPY_FR_us#

微秒

enumerator NPY_FR_ns#

奈秒

enumerator NPY_FR_ps#

皮秒

enumerator NPY_FR_fs#

飛秒

enumerator NPY_FR_as#

阿秒

enumerator NPY_FR_GENERIC#

無界限單位，可以轉換為任何單位

轉換函式#

int NpyDatetime_ConvertDatetimeStructToDatetime64(PyArray_DatetimeMetaData *meta, const npy_datetimestruct *dts, npy_datetime *out)#

將 datetime 從 datetimestruct 轉換為單位元資料指定的單位之 datetime。假設日期有效。

如果元資料結構的 num 成員很大，則此函式中可能會發生整數溢位。

成功時傳回 0，失敗時傳回 -1。

int NpyDatetime_ConvertDatetime64ToDatetimeStruct(PyArray_DatetimeMetaData *meta, npy_datetime dt, npy_datetimestruct *out)#

將單位元資料指定的單位之 datetime 轉換為展開的 datetime 結構。

成功時傳回 0，失敗時傳回 -1。

int NpyDatetime_ConvertPyDateTimeToDatetimeStruct(PyObject *obj, npy_datetimestruct *out, NPY_DATETIMEUNIT *out_bestunit, int apply_tzinfo)#

測試並將 Python datetime.datetime 或 datetime.date 物件轉換為 NumPy npy_datetimestruct。

out_bestunit 根據物件是 datetime.date 還是 datetime.datetime 物件，提供建議的單位。

如果 apply_tzinfo 為 1，則此函式會使用 tzinfo 轉換為 UTC 時間，否則會傳回具有當地時間的結構。

如果發生錯誤則傳回 -1，成功則傳回 0，如果 obj 沒有所需的 date 或 datetime 屬性，則傳回 1（且未設定錯誤）。

int NpyDatetime_ParseISO8601Datetime(char const *str, Py_ssize_t len, NPY_DATETIMEUNIT unit, NPY_CASTING casting, npy_datetimestruct *out, NPY_DATETIMEUNIT *out_bestunit, npy_bool *out_special)#

剖析（幾乎）標準 ISO 8601 日期字串。差異如下：

  • 日期 “20100312” 會剖析為年份 20100312，而不是等同於 “2010-03-12”。日期中的 ‘-’ 並非選用。

  • 只有秒可以有小數點，最多可有 18 位小數位數（最大阿秒精度）。

  • 可以使用 ‘T’（如 ISO 8601 中所示）或 ‘ ’ 來分隔日期和時間。兩者都被視為等效。

  • （尚未）處理 “YYYY-DDD” 或 “YYYY-Www” 格式。

  • 不處理閏秒（在這些情況下，秒值為 60）。

  • 不將 24:00:00 視為明天午夜 (00:00:00) 的同義詞

  • 接受特殊值 “NaT”（非時間）、“Today”（根據當地時間的當天）和 “Now”（UTC 的目前時間）。

str 必須是以 NULL 結尾的字串，而 len 必須是其長度。

如果單位未知，則 unit 應包含 -1；如果單位已知，則應包含將使用的單位。

casting 控制字串中偵測到的單位如何強制轉換為 ‘unit’ 參數。

out 會填入剖析的日期時間。

out_bestunit 根據字串中提供的解析度，提供建議的單位，或針對 NaT 提供 -1。

如果剖析的時間是 ‘today’、‘now’、空字串或 ‘NaT’，則 out_special 會設定為 1。對於 ‘today’，建議的單位是 ‘D’；對於 ‘now’，建議的單位是 ‘s’；對於 ‘NaT’，建議的單位是 ‘Y’。

成功時傳回 0，失敗時傳回 -1。

int NpyDatetime_GetDatetimeISO8601StrLen(int local, NPY_DATETIMEUNIT base)#

傳回字串長度，用於將具有給定當地時間和單位設定的 datetime 物件轉換為字串。在建構要提供給 NpyDatetime_MakeISO8601Datetime 的字串時使用此函式。

int NpyDatetime_MakeISO8601Datetime(npy_datetimestruct *dts, char *outstr, npy_intp outlen, int local, int utc, NPY_DATETIMEUNIT base, int tzoffset, NPY_CASTING casting)#

將 npy_datetimestruct 轉換為（幾乎）ISO 8601 以 NULL 結尾的字串。如果字串正好符合空間，它會省略 NULL 終止符並傳回成功。

與 ISO 8601 的差異在於 ‘NaT’ 字串，以及年份位數 >= 4 而不是嚴格的 4 位數。

如果 local 為非零值，則會產生具有 +-#### 時區偏移的當地時間字串。如果 local 為零且 utc 為非零值，則會產生以 ‘Z’ 結尾的字串以表示 UTC。預設情況下，不會附加時區資訊。

base 將輸出限制為該單位。將 base 設定為 -1 可自動偵測在所有值都為零之後的基準。

如果啟用 local 且 tzoffset 設定為 -1 以外的值，則會使用 tzoffset。這是要使用的當地時區的手動覆寫，以分鐘為單位的偏移量。

casting 控制是否允許透過將資料截斷為較粗的單位來造成資料遺失。這與 local 略有互動，為了形成作為當地時間的日期單位字串，強制轉換必須是不安全的。

成功時傳回 0，失敗時傳回 -1（例如，如果輸出字串太短）。

本頁內容