Datetime API#

NumPy 在内部使用 int64 计数器和单元元数据结构来表示日期。时间差的表示方式类似，使用 int64 和单元元数据结构。下面描述的函数可用于在 C 中方便地转换 ISO 8601 日期字符串、NumPy 日期时间以及 Python datetime 对象。

数据类型#

除了用于 npy_int64 的 npy_datetime 和 npy_timedelta 类型定义之外，NumPy 还定义了两个额外的结构，用于表示时间单元元数据和日期的“展开”视图。

type PyArray_DatetimeMetaData#

表示日期时间单元的元数据。

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

NPY_DATETIMEUNIT base#: 日期时间的单元。

int num#: 单元的乘数。

type npy_datetimestruct#

日期时间值的“展开”视图。

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)#

将 datetimestruct 中的日期时间转换为由单元元数据指定的单元中的日期时间。假定日期有效。

如果元数据结构中的 num 成员很大，此函数可能会发生整数溢出。

成功时返回 0，失败时返回 -1。

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

将具有由单元元数据指定的单元的日期时间转换为展开的日期时间结构。

成功时返回 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 表示成功，1（未设置错误）表示 obj 没有所需的日期或日期时间属性。

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 根据字符串中提供的分辨率量给出建议的单元，或 -1 表示 NaT。

out_special 设置为 1，如果解析的时间是“today”、“now”、空字符串或“NaT”。对于“today”，推荐的单元是“D”；对于“now”，推荐的单元是“s”；对于“NaT”，推荐的单元是“Y”。

成功时返回 0，失败时返回 -1。

int NpyDatetime_GetDatetimeISO8601StrLen(int local, NPY_DATETIMEUNIT base)#: 返回将日期时间对象（根据给定的本地时间和单元设置）转换为字符串时应使用的字符串长度。在构建要传递给 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 以自动检测一个基础，之后所有值都为零。

tzoffset 用于 local 启用且 tzoffset 设置为非 -1 值时。这是一个本地时区的手动覆盖，以分钟为偏移量。

casting 控制是否允许通过截断数据到更粗的单元来丢失数据。这与 local 有轻微的交互，以便形成本地时间的日期单元字符串，casting 必须是 unsafe。

成功时返回 0，失败时返回 -1（例如，如果输出字符串太短）。