include get_localtime wrapper

Author: Jonathan Eliashiv

pandas/_libs/tslibs/src/datetime/np_datetime_strings.c

@@ -51,6 +51,77 @@ This file implements string parsing and creation for NumPy datetime.
  typedef time_t NPY_TIME_T;
 #endif
 
+/*
+ * Wraps `localtime` functionality for multiple platforms. This
+ * converts a time value to a time structure in the local timezone.
+ * If size(NPY_TIME_T) == 4, then years must be between 1970 and 2038. If
+ * size(NPY_TIME_T) == 8, then years must be later than 1970. If the years are
+ * not in this range, then get_localtime() will fail on some platforms.
+ *
+ * Returns 0 on success, -1 on failure.
+ *
+ * Notes:
+ * 1) If NPY_TIME_T is 32 bit (i.e. sizeof(NPY_TIME_T) == 4), then the
+ *    maximum year it can represent is 2038 (see [1] for more details). Trying
+ *    to use a higher date like 2041 in the 32 bit "ts" variable below will
+ *    typically result in "ts" being a negative number (corresponding roughly
+ *    to a year ~ 1905). If NPY_TIME_T is 64 bit, then there is no such
+ *    problem in practice.
+ * 2) If the "ts" argument to localtime() is negative, it represents
+ *    years < 1970 both for 32 and 64 bits (for 32 bits the earliest year it can
+ *    represent is 1901, while 64 bits can represent much earlier years).
+ * 3) On Linux, localtime() works for negative "ts". On Windows and in Wine,
+ *    localtime() as well as the localtime_s() and _localtime64_s() functions
+ *    will fail for any negative "ts" and return a nonzero exit number
+ *    (localtime_s, _localtime64_s) or NULL (localtime). This behavior is the
+ *    same for both 32 and 64 bits.
+ *
+ * From this it follows that get_localtime() is only guaranteed to work
+ * correctly on all platforms for years between 1970 and 2038 for 32bit
+ * NPY_TIME_T and years higher than 1970 for 64bit NPY_TIME_T. For
+ * multiplatform code, get_localtime() should never be used outside of this
+ * range.
+ *
+ * [1] https://en.wikipedia.org/wiki/Year_2038_problem
+ */
+static int
+get_localtime(NPY_TIME_T *ts, struct tm *tms)
+{
+    char *func_name = "<unknown>";
+#if defined(_WIN32)
+ #if defined(_MSC_VER) && (_MSC_VER >= 1400)
+    if (localtime_s(tms, ts) != 0) {
+        func_name = "localtime_s";
+        goto fail;
+    }
+ #elif defined(NPY_MINGW_USE_CUSTOM_MSVCR)
+    if (_localtime64_s(tms, ts) != 0) {
+        func_name = "_localtime64_s";
+        goto fail;
+    }
+ #else
+    struct tm *tms_tmp;
+    tms_tmp = localtime(ts);
+    if (tms_tmp == NULL) {
+        func_name = "localtime";
+        goto fail;
+    }
+    memcpy(tms, tms_tmp, sizeof(struct tm));
+ #endif
+#else
+    if (localtime_r(ts, tms) == NULL) {
+        func_name = "localtime_r";
+        goto fail;
+    }
+#endif
+
+    return 0;
+
+fail:
+    PyErr_Format(PyExc_OSError, "Failed to use '%s' to convert "
+                                "to a local time", func_name);
+    return -1;
+}
 
 /*
  * Parses (almost) standard ISO 8601 date strings. The differences are: