Data types#

In addition to thenpy_datetime andnpy_timedelta typedefsfornpy_int64, NumPy defines two additional structs that representtime unit metadata and an “exploded” view of a datetime.

typePyArray_DatetimeMetaData#

Represents datetime unit metadata.

typedefstruct{NPY_DATETIMEUNITbase;intnum;}PyArray_DatetimeMetaData;

NPY_DATETIMEUNITbase#

The unit of the datetime.

intnum#

A multiplier for the unit.

typenpy_datetimestruct#

An “exploded” view of a datetime value

typedefstruct{npy_int64year;npy_int32month,day,hour,min,sec,us,ps,as;}npy_datetimestruct;

enumNPY_DATETIMEUNIT#

Time units supported by NumPy. The “FR” in the names of the enum variantsis short for frequency.

enumeratorNPY_FR_ERROR#

Error or undetermined units.

enumeratorNPY_FR_Y#

Years

enumeratorNPY_FR_M#

Months

enumeratorNPY_FR_W#

Weeks

enumeratorNPY_FR_D#

Days

enumeratorNPY_FR_h#

Hours

enumeratorNPY_FR_m#

Minutes

enumeratorNPY_FR_s#

Seconds

enumeratorNPY_FR_ms#

Milliseconds

enumeratorNPY_FR_us#

Microseconds

enumeratorNPY_FR_ns#

Nanoseconds

enumeratorNPY_FR_ps#

Picoseconds

enumeratorNPY_FR_fs#

Femtoseconds

enumeratorNPY_FR_as#

Attoseconds

enumeratorNPY_FR_GENERIC#

Unbound units, can convert to anything

Conversion functions#

intNpyDatetime_ConvertDatetimeStructToDatetime64(PyArray_DatetimeMetaData*meta,constnpy_datetimestruct*dts,npy_datetime*out)#

Converts a datetime from a datetimestruct to a datetime in the unitsspecified by the unit metadata. The date is assumed to be valid.

If thenum member of the metadata struct is large, there maybe integer overflow in this function.

Returns 0 on success and -1 on failure.

intNpyDatetime_ConvertDatetime64ToDatetimeStruct(PyArray_DatetimeMetaData*meta,npy_datetimedt,npy_datetimestruct*out)#

Converts a datetime with units specified by the unit metadata to anexploded datetime struct.

Returns 0 on success and -1 on failure.

intNpyDatetime_ConvertPyDateTimeToDatetimeStruct(PyObject*obj,npy_datetimestruct*out,NPY_DATETIMEUNIT*out_bestunit,intapply_tzinfo)#

Tests for and converts a Pythondatetime.datetime ordatetime.dateobject into a NumPynpy_datetimestruct.

out_bestunit gives a suggested unit based on whether the objectwas adatetime.date ordatetime.datetime object.

Ifapply_tzinfo is 1, this function uses the tzinfo to convertto UTC time, otherwise it returns the struct with the local time.

Returns -1 on error, 0 on success, and 1 (with no error set)if obj doesn’t have the needed date or datetime attributes.

intNpyDatetime_ParseISO8601Datetime(charconst*str,Py_ssize_tlen,NPY_DATETIMEUNITunit,NPY_CASTINGcasting,npy_datetimestruct*out,NPY_DATETIMEUNIT*out_bestunit,npy_bool*out_special)#

Parses (almost) standard ISO 8601 date strings. The differences are:

• The date “20100312” is parsed as the year 20100312, not asequivalent to “2010-03-12”. The ‘-’ in the dates are not optional.

• Only seconds may have a decimal point, with up to 18 digits after it(maximum attoseconds precision).

• Either a ‘T’ as in ISO 8601 or a ‘ ‘ may be used to separatethe date and the time. Both are treated equivalently.

• Doesn’t (yet) handle the “YYYY-DDD” or “YYYY-Www” formats.

• Doesn’t handle leap seconds (seconds value has 60 in these cases).

• Doesn’t handle 24:00:00 as synonym for midnight (00:00:00) tomorrow

• Accepts special values “NaT” (not a time), “Today”, (currentday according to local time) and “Now” (current time in UTC).

str must be a NULL-terminated string, andlen must be its length.

unit should contain -1 if the unit is unknown, or the unitwhich will be used if it is.

casting controls how the detected unit from the string is allowedto be cast to the ‘unit’ parameter.

out gets filled with the parsed date-time.

out_bestunit gives a suggested unit based on the amount ofresolution provided in the string, or -1 for NaT.

out_special gets set to 1 if the parsed time was ‘today’,‘now’, empty string, or ‘NaT’. For ‘today’, the unit recommended is‘D’, for ‘now’, the unit recommended is ‘s’, and for ‘NaT’the unit recommended is ‘Y’.

Returns 0 on success, -1 on failure.

intNpyDatetime_GetDatetimeISO8601StrLen(intlocal,NPY_DATETIMEUNITbase)#

Returns the string length to use for converting datetimeobjects with the given local time and unit settings to strings.Use this when constructing strings to supply toNpyDatetime_MakeISO8601Datetime.

intNpyDatetime_MakeISO8601Datetime(npy_datetimestruct*dts,char*outstr,npy_intpoutlen,intlocal,intutc,NPY_DATETIMEUNITbase,inttzoffset,NPY_CASTINGcasting)#

Converts annpy_datetimestruct to an (almost) ISO 8601NULL-terminated string. If the string fits in the space exactly,it leaves out the NULL terminator and returns success.

The differences from ISO 8601 are the ‘NaT’ string, andthe number of year digits is >= 4 instead of strictly 4.

Iflocal is non-zero, it produces a string in local time witha +-#### timezone offset. Iflocal is zero andutc is non-zero,produce a string ending with ‘Z’ to denote UTC. By default, no timezone information is attached.

base restricts the output to that unit. Setbase to-1 to auto-detect a base after which all the values are zero.

tzoffset is used iflocal is enabled, andtzoffset isset to a value other than -1. This is a manual override forthe local time zone to use, as an offset in minutes.

casting controls whether data loss is allowed by truncatingthe data to a coarser unit. This interacts withlocal, slightly,in order to form a date unit string as a local time, the castingmust be unsafe.

Returns 0 on success, -1 on failure (for example if the outputstring was too short).