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