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_bestunit' gives a suggested unit based on the amount of
00027  *      resolution provided in the string, or -1 for NaT.
00028  * 'out_special' gets set to 1 if the parsed time was 'today',
00029  *      'now', or ''/'NaT'. For 'today', the unit recommended is
00030  *      'D', for 'now', the unit recommended is 's', and for 'NaT'
00031  *      the unit recommended is 'Y'.
00032  *
00033  * Returns 0 on success, -1 on failure.
00034  */
00035 NPY_NO_EXPORT int
00036 parse_iso_8601_datetime(char *str, Py_ssize_t len,
00037                     NPY_DATETIMEUNIT unit,
00038                     NPY_CASTING casting,
00039                     npy_datetimestruct *out,
00040                     NPY_DATETIMEUNIT *out_bestunit,
00041                     npy_bool *out_special);
00042 
00043 /*
00044  * Provides a string length to use for converting datetime
00045  * objects with the given local and unit settings.
00046  */
00047 NPY_NO_EXPORT int
00048 get_datetime_iso_8601_strlen(int local, NPY_DATETIMEUNIT base);
00049 
00050 /*
00051  * Converts an npy_datetimestruct to an (almost) ISO 8601
00052  * NULL-terminated string.
00053  *
00054  * If 'local' is non-zero, it produces a string in local time with
00055  * a +-#### timezone offset, otherwise it uses timezone Z (UTC).
00056  *
00057  * 'base' restricts the output to that unit. Set 'base' to
00058  * -1 to auto-detect a base after which all the values are zero.
00059  *
00060  *  'tzoffset' is used if 'local' is enabled, and 'tzoffset' is
00061  *  set to a value other than -1. This is a manual override for
00062  *  the local time zone to use, as an offset in minutes.
00063  *
00064  *  'casting' controls whether data loss is allowed by truncating
00065  *  the data to a coarser unit. This interacts with 'local', slightly,
00066  *  in order to form a date unit string as a local time, the casting
00067  *  must be unsafe.
00068  *
00069  *  Returns 0 on success, -1 on failure (for example if the output
00070  *  string was too short).
00071  */
00072 NPY_NO_EXPORT int
00073 make_iso_8601_datetime(npy_datetimestruct *dts, char *outstr, int outlen,
00074                     int local, int utc, NPY_DATETIMEUNIT base, int tzoffset,
00075                     NPY_CASTING casting);
00076 
00077 /*
00078  * This is the Python-exposed datetime_as_string function.
00079  */
00080 NPY_NO_EXPORT PyObject *
00081 array_datetime_as_string(PyObject *NPY_UNUSED(self), PyObject *args,
00082                                 PyObject *kwds);
00083 
00084 #endif