numpy 2.0.0
|
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