numpy  2.0.0
src/multiarray/_datetime.h
Go to the documentation of this file.
00001 #ifndef _NPY_PRIVATE__DATETIME_H_
00002 #define _NPY_PRIVATE__DATETIME_H_
00003 
00004 extern NPY_NO_EXPORT char *_datetime_strings[NPY_DATETIME_NUMUNITS];
00005 extern NPY_NO_EXPORT int _days_per_month_table[2][12];
00006 
00007 NPY_NO_EXPORT void
00008 numpy_pydatetime_import(void);
00009 
00010 /*
00011  * Returns 1 if the given year is a leap year, 0 otherwise.
00012  */
00013 NPY_NO_EXPORT int
00014 is_leapyear(npy_int64 year);
00015 
00016 /*
00017  * Calculates the days offset from the 1970 epoch.
00018  */
00019 NPY_NO_EXPORT npy_int64
00020 get_datetimestruct_days(const npy_datetimestruct *dts);
00021 
00022 /*
00023  * Creates a datetime or timedelta dtype using a copy of the provided metadata.
00024  */
00025 NPY_NO_EXPORT PyArray_Descr *
00026 create_datetime_dtype(int type_num, PyArray_DatetimeMetaData *meta);
00027 
00028 /*
00029  * Creates a datetime or timedelta dtype using the given unit.
00030  */
00031 NPY_NO_EXPORT PyArray_Descr *
00032 create_datetime_dtype_with_unit(int type_num, NPY_DATETIMEUNIT unit);
00033 
00034 /*
00035  * This function returns a pointer to the DateTimeMetaData
00036  * contained within the provided datetime dtype.
00037  */
00038 NPY_NO_EXPORT PyArray_DatetimeMetaData *
00039 get_datetime_metadata_from_dtype(PyArray_Descr *dtype);
00040 
00041 /*
00042  * Both type1 and type2 must be either NPY_DATETIME or NPY_TIMEDELTA.
00043  * Applies the type promotion rules between the two types, returning
00044  * the promoted type.
00045  */
00046 NPY_NO_EXPORT PyArray_Descr *
00047 datetime_type_promotion(PyArray_Descr *type1, PyArray_Descr *type2);
00048 
00049 /*
00050  * Converts a datetime from a datetimestruct to a datetime based
00051  * on some metadata.
00052  */
00053 NPY_NO_EXPORT int
00054 convert_datetimestruct_to_datetime(PyArray_DatetimeMetaData *meta,
00055                                     const npy_datetimestruct *dts,
00056                                     npy_datetime *out);
00057 
00058 /*
00059  * Extracts the month number, within the current year,
00060  * from a 'datetime64[D]' value. January is 1, etc.
00061  */
00062 NPY_NO_EXPORT int
00063 days_to_month_number(npy_datetime days);
00064 
00065 /*
00066  * Parses the metadata string into the metadata C structure.
00067  *
00068  * Returns 0 on success, -1 on failure.
00069  */
00070 NPY_NO_EXPORT int
00071 parse_datetime_metadata_from_metastr(char *metastr, Py_ssize_t len,
00072                                     PyArray_DatetimeMetaData *out_meta);
00073 
00074 
00075 /*
00076  * Converts a datetype dtype string into a dtype descr object.
00077  * The "type" string should be NULL-terminated, and len should
00078  * contain its string length.
00079  */
00080 NPY_NO_EXPORT PyArray_Descr *
00081 parse_dtype_from_datetime_typestr(char *typestr, Py_ssize_t len);
00082 
00083 /*
00084  * Converts a substring given by 'str' and 'len' into
00085  * a date time unit enum value. The 'metastr' parameter
00086  * is used for error messages, and may be NULL.
00087  *
00088  * Returns 0 on success, -1 on failure.
00089  */
00090 NPY_NO_EXPORT NPY_DATETIMEUNIT
00091 parse_datetime_unit_from_string(char *str, Py_ssize_t len, char *metastr);
00092 
00093 /*
00094  * Translate divisors into multiples of smaller units.
00095  * 'metastr' is used for the error message if the divisor doesn't work,
00096  * and can be NULL if the metadata didn't come from a string.
00097  *
00098  * Returns 0 on success, -1 on failure.
00099  */
00100 NPY_NO_EXPORT int
00101 convert_datetime_divisor_to_multiple(PyArray_DatetimeMetaData *meta,
00102                                     int den, char *metastr);
00103 
00104 /*
00105  * Determines whether the 'divisor' metadata divides evenly into
00106  * the 'dividend' metadata.
00107  */
00108 NPY_NO_EXPORT npy_bool
00109 datetime_metadata_divides(
00110                         PyArray_DatetimeMetaData *dividend,
00111                         PyArray_DatetimeMetaData *divisor,
00112                         int strict_with_nonlinear_units);
00113 
00114 /*
00115  * This provides the casting rules for the DATETIME data type units.
00116  *
00117  * Notably, there is a barrier between 'date units' and 'time units'
00118  * for all but 'unsafe' casting.
00119  */
00120 NPY_NO_EXPORT npy_bool
00121 can_cast_datetime64_units(NPY_DATETIMEUNIT src_unit,
00122                           NPY_DATETIMEUNIT dst_unit,
00123                           NPY_CASTING casting);
00124 
00125 /*
00126  * This provides the casting rules for the DATETIME data type metadata.
00127  */
00128 NPY_NO_EXPORT npy_bool
00129 can_cast_datetime64_metadata(PyArray_DatetimeMetaData *src_meta,
00130                              PyArray_DatetimeMetaData *dst_meta,
00131                              NPY_CASTING casting);
00132 
00133 /*
00134  * This provides the casting rules for the TIMEDELTA data type units.
00135  *
00136  * Notably, there is a barrier between the nonlinear years and
00137  * months units, and all the other units.
00138  */
00139 NPY_NO_EXPORT npy_bool
00140 can_cast_timedelta64_units(NPY_DATETIMEUNIT src_unit,
00141                           NPY_DATETIMEUNIT dst_unit,
00142                           NPY_CASTING casting);
00143 
00144 /*
00145  * This provides the casting rules for the TIMEDELTA data type metadata.
00146  */
00147 NPY_NO_EXPORT npy_bool
00148 can_cast_timedelta64_metadata(PyArray_DatetimeMetaData *src_meta,
00149                              PyArray_DatetimeMetaData *dst_meta,
00150                              NPY_CASTING casting);
00151 
00152 /*
00153  * Computes the conversion factor to convert data with 'src_meta' metadata
00154  * into data with 'dst_meta' metadata.
00155  *
00156  * If overflow occurs, both out_num and out_denom are set to 0, but
00157  * no error is set.
00158  */
00159 NPY_NO_EXPORT void
00160 get_datetime_conversion_factor(PyArray_DatetimeMetaData *src_meta,
00161                                 PyArray_DatetimeMetaData *dst_meta,
00162                                 npy_int64 *out_num, npy_int64 *out_denom);
00163 
00164 /*
00165  * Given a pointer to datetime metadata,
00166  * returns a tuple for pickling and other purposes.
00167  */
00168 NPY_NO_EXPORT PyObject *
00169 convert_datetime_metadata_to_tuple(PyArray_DatetimeMetaData *meta);
00170 
00171 /*
00172  * Converts a metadata tuple into a datetime metadata C struct.
00173  *
00174  * Returns 0 on success, -1 on failure.
00175  */
00176 NPY_NO_EXPORT int
00177 convert_datetime_metadata_tuple_to_datetime_metadata(PyObject *tuple,
00178                                         PyArray_DatetimeMetaData *out_meta);
00179 
00180 /*
00181  * Gets a tzoffset in minutes by calling the fromutc() function on
00182  * the Python datetime.tzinfo object.
00183  */
00184 NPY_NO_EXPORT int
00185 get_tzoffset_from_pytzinfo(PyObject *timezone, npy_datetimestruct *dts);
00186 
00187 /*
00188  * Converts an input object into datetime metadata. The input
00189  * may be either a string or a tuple.
00190  *
00191  * Returns 0 on success, -1 on failure.
00192  */
00193 NPY_NO_EXPORT int
00194 convert_pyobject_to_datetime_metadata(PyObject *obj,
00195                                         PyArray_DatetimeMetaData *out_meta);
00196 
00197 /*
00198  * 'ret' is a PyUString containing the datetime string, and this
00199  * function appends the metadata string to it.
00200  *
00201  * If 'skip_brackets' is true, skips the '[]'.
00202  *
00203  * This function steals the reference 'ret'
00204  */
00205 NPY_NO_EXPORT PyObject *
00206 append_metastr_to_string(PyArray_DatetimeMetaData *meta,
00207                                     int skip_brackets,
00208                                     PyObject *ret);
00209 
00210 /*
00211  * Tests for and converts a Python datetime.datetime or datetime.date
00212  * object into a NumPy npy_datetimestruct.
00213  *
00214  * 'out_bestunit' gives a suggested unit based on whether the object
00215  *      was a datetime.date or datetime.datetime object.
00216  *
00217  * If 'apply_tzinfo' is 1, this function uses the tzinfo to convert
00218  * to UTC time, otherwise it returns the struct with the local time.
00219  *
00220  * Returns -1 on error, 0 on success, and 1 (with no error set)
00221  * if obj doesn't have the needed date or datetime attributes.
00222  */
00223 NPY_NO_EXPORT int
00224 convert_pydatetime_to_datetimestruct(PyObject *obj, npy_datetimestruct *out,
00225                                      NPY_DATETIMEUNIT *out_bestunit,
00226                                      int apply_tzinfo);
00227 
00228 /*
00229  * Converts a PyObject * into a datetime, in any of the forms supported.
00230  *
00231  * If the units metadata isn't known ahead of time, set meta->base
00232  * to -1, and this function will populate meta with either default
00233  * values or values from the input object.
00234  *
00235  * The 'casting' parameter is used to control what kinds of inputs
00236  * are accepted, and what happens. For example, with 'unsafe' casting,
00237  * unrecognized inputs are converted to 'NaT' instead of throwing an error,
00238  * while with 'safe' casting an error will be thrown if any precision
00239  * from the input will be thrown away.
00240  *
00241  * Returns -1 on error, 0 on success.
00242  */
00243 NPY_NO_EXPORT int
00244 convert_pyobject_to_datetime(PyArray_DatetimeMetaData *meta, PyObject *obj,
00245                                 NPY_CASTING casting, npy_datetime *out);
00246 
00247 /*
00248  * Converts a PyObject * into a timedelta, in any of the forms supported
00249  *
00250  * If the units metadata isn't known ahead of time, set meta->base
00251  * to -1, and this function will populate meta with either default
00252  * values or values from the input object.
00253  *
00254  * The 'casting' parameter is used to control what kinds of inputs
00255  * are accepted, and what happens. For example, with 'unsafe' casting,
00256  * unrecognized inputs are converted to 'NaT' instead of throwing an error,
00257  * while with 'safe' casting an error will be thrown if any precision
00258  * from the input will be thrown away.
00259  *
00260  * Returns -1 on error, 0 on success.
00261  */
00262 NPY_NO_EXPORT int
00263 convert_pyobject_to_timedelta(PyArray_DatetimeMetaData *meta, PyObject *obj,
00264                                 NPY_CASTING casting, npy_timedelta *out);
00265 
00266 /*
00267  * Converts a datetime into a PyObject *.
00268  *
00269  * For days or coarser, returns a datetime.date.
00270  * For microseconds or coarser, returns a datetime.datetime.
00271  * For units finer than microseconds, returns an integer.
00272  */
00273 NPY_NO_EXPORT PyObject *
00274 convert_datetime_to_pyobject(npy_datetime dt, PyArray_DatetimeMetaData *meta);
00275 
00276 /*
00277  * Converts a timedelta into a PyObject *.
00278  *
00279  * Not-a-time is returned as the string "NaT".
00280  * For microseconds or coarser, returns a datetime.timedelta.
00281  * For units finer than microseconds, returns an integer.
00282  */
00283 NPY_NO_EXPORT PyObject *
00284 convert_timedelta_to_pyobject(npy_timedelta td, PyArray_DatetimeMetaData *meta);
00285 
00286 /*
00287  * Converts a datetime based on the given metadata into a datetimestruct
00288  */
00289 NPY_NO_EXPORT int
00290 convert_datetime_to_datetimestruct(PyArray_DatetimeMetaData *meta,
00291                                     npy_datetime dt,
00292                                     npy_datetimestruct *out);
00293 
00294 /*
00295  * Converts a datetime from a datetimestruct to a datetime based
00296  * on some metadata. The date is assumed to be valid.
00297  *
00298  * TODO: If meta->num is really big, there could be overflow
00299  *
00300  * Returns 0 on success, -1 on failure.
00301  */
00302 NPY_NO_EXPORT int
00303 convert_datetimestruct_to_datetime(PyArray_DatetimeMetaData *meta,
00304                                     const npy_datetimestruct *dts,
00305                                     npy_datetime *out);
00306 
00307 /*
00308  * Adjusts a datetimestruct based on a seconds offset. Assumes
00309  * the current values are valid.
00310  */
00311 NPY_NO_EXPORT void
00312 add_seconds_to_datetimestruct(npy_datetimestruct *dts, int seconds);
00313 
00314 /*
00315  * Adjusts a datetimestruct based on a minutes offset. Assumes
00316  * the current values are valid.
00317  */
00318 NPY_NO_EXPORT void
00319 add_minutes_to_datetimestruct(npy_datetimestruct *dts, int minutes);
00320 
00321 /*
00322  * Returns true if the datetime metadata matches
00323  */
00324 NPY_NO_EXPORT npy_bool
00325 has_equivalent_datetime_metadata(PyArray_Descr *type1, PyArray_Descr *type2);
00326 
00327 /*
00328  * Casts a single datetime from having src_meta metadata into
00329  * dst_meta metadata.
00330  *
00331  * Returns 0 on success, -1 on failure.
00332  */
00333 NPY_NO_EXPORT int
00334 cast_datetime_to_datetime(PyArray_DatetimeMetaData *src_meta,
00335                           PyArray_DatetimeMetaData *dst_meta,
00336                           npy_datetime src_dt,
00337                           npy_datetime *dst_dt);
00338 
00339 /*
00340  * Casts a single timedelta from having src_meta metadata into
00341  * dst_meta metadata.
00342  *
00343  * Returns 0 on success, -1 on failure.
00344  */
00345 NPY_NO_EXPORT int
00346 cast_timedelta_to_timedelta(PyArray_DatetimeMetaData *src_meta,
00347                           PyArray_DatetimeMetaData *dst_meta,
00348                           npy_timedelta src_dt,
00349                           npy_timedelta *dst_dt);
00350 
00351 /*
00352  * Returns true if the object is something that is best considered
00353  * a Datetime or Timedelta, false otherwise.
00354  */
00355 NPY_NO_EXPORT npy_bool
00356 is_any_numpy_datetime_or_timedelta(PyObject *obj);
00357 
00358 /*
00359  * Implements a datetime-specific arange
00360  */
00361 NPY_NO_EXPORT PyArrayObject *
00362 datetime_arange(PyObject *start, PyObject *stop, PyObject *step,
00363                 PyArray_Descr *dtype);
00364 
00365 /*
00366  * Examines all the objects in the given Python object by
00367  * recursively descending the sequence structure. Returns a
00368  * datetime or timedelta type with metadata based on the data.
00369  */
00370 NPY_NO_EXPORT PyArray_Descr *
00371 find_object_datetime_type(PyObject *obj, int type_num);
00372 
00373 #endif