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