numpy 2.0.0
src/multiarray/datetime_strings.h
Go to the documentation of this file.
00001 #ifndef _NPY_PRIVATE__DATETIME_STRINGS_H_
00002 #define _NPY_PRIVATE__DATETIME_STRINGS_H_
00003 
00004 /*
00005  * Parses (almost) standard ISO 8601 date strings. The differences are:
00006  *
00007  * + The date "20100312" is parsed as the year 20100312, not as
00008  *   equivalent to "2010-03-12". The '-' in the dates are not optional.
00009  * + Only seconds may have a decimal point, with up to 18 digits after it
00010  *   (maximum attoseconds precision).
00011  * + Either a 'T' as in ISO 8601 or a ' ' may be used to separate
00012  *   the date and the time. Both are treated equivalently.
00013  * + Doesn't (yet) handle the "YYYY-DDD" or "YYYY-Www" formats.
00014  * + Doesn't handle leap seconds (seconds value has 60 in these cases).
00015  * + Doesn't handle 24:00:00 as synonym for midnight (00:00:00) tomorrow
00016  * + Accepts special values "NaT" (not a time), "Today", (current
00017  *   day according to local time) and "Now" (current time in UTC).
00018  *
00019  * 'str' must be a NULL-terminated string, and 'len' must be its length.
00020  * 'unit' should contain -1 if the unit is unknown, or the unit
00021  *      which will be used if it is.
00022  * 'casting' controls how the detected unit from the string is allowed
00023  *           to be cast to the 'unit' parameter.
00024  *
00025  * 'out' gets filled with the parsed date-time.
00026  * 'out_local' gets set to 1 if the parsed time was in local time,
00027  *      to 0 otherwise. The values 'now' and 'today' don't get counted
00028  *      as local, and neither do UTC +/-#### timezone offsets, because
00029  *      they aren't using the computer's local timezone offset.
00030  * 'out_bestunit' gives a suggested unit based on the amount of
00031  *      resolution provided in the string, or -1 for NaT.
00032  * 'out_special' gets set to 1 if the parsed time was 'today',
00033  *      'now', or ''/'NaT'. For 'today', the unit recommended is
00034  *      'D', for 'now', the unit recommended is 's', and for 'NaT'
00035  *      the unit recommended is 'Y'.
00036  *
00037  * Returns 0 on success, -1 on failure.
00038  */
00039 NPY_NO_EXPORT int
00040 parse_iso_8601_datetime(char *str, int len,
00041                     NPY_DATETIMEUNIT unit,
00042                     NPY_CASTING casting,
00043                     npy_datetimestruct *out,
00044                     npy_bool *out_local,
00045                     NPY_DATETIMEUNIT *out_bestunit,
00046                     npy_bool *out_special);
00047 
00048 /*
00049  * Provides a string length to use for converting datetime
00050  * objects with the given local and unit settings.
00051  */
00052 NPY_NO_EXPORT int
00053 get_datetime_iso_8601_strlen(int local, NPY_DATETIMEUNIT base);
00054 
00055 /*
00056  * Converts an npy_datetimestruct to an (almost) ISO 8601
00057  * NULL-terminated string.
00058  *
00059  * If 'local' is non-zero, it produces a string in local time with
00060  * a +-#### timezone offset, otherwise it uses timezone Z (UTC).
00061  *
00062  * 'base' restricts the output to that unit. Set 'base' to
00063  * -1 to auto-detect a base after which all the values are zero.
00064  *
00065  *  'tzoffset' is used if 'local' is enabled, and 'tzoffset' is
00066  *  set to a value other than -1. This is a manual override for
00067  *  the local time zone to use, as an offset in minutes.
00068  *
00069  *  'casting' controls whether data loss is allowed by truncating
00070  *  the data to a coarser unit. This interacts with 'local', slightly,
00071  *  in order to form a date unit string as a local time, the casting
00072  *  must be unsafe.
00073  *
00074  *  Returns 0 on success, -1 on failure (for example if the output
00075  *  string was too short).
00076  */
00077 NPY_NO_EXPORT int
00078 make_iso_8601_datetime(npy_datetimestruct *dts, char *outstr, int outlen,
00079                     int local, NPY_DATETIMEUNIT base, int tzoffset,
00080                     NPY_CASTING casting);
00081 
00082 /*
00083  * This is the Python-exposed datetime_as_string function.
00084  */
00085 NPY_NO_EXPORT PyObject *
00086 array_datetime_as_string(PyObject *NPY_UNUSED(self), PyObject *args,
00087                                 PyObject *kwds);
00088 
00089 #endif