Fix actively-misleading comments about the contents of struct pg_tm.

tglsfdc · tglsfdc · commit 89dba59590fd · 2021-09-06T11:43:44.000-04:00
pgtime.h documented the PG interpretation of tm_mon right alongside the POSIX interpretation of tm_year, with no hint that neither comment was correct throughout our code. Perhaps someday we ought to switch to using two separate struct definitions to provide a clearer indication of which semantics are in use where. But I fear the tedium-versus-safety-gain tradeoff would not be very good. Discussion: https://postgr.es/m/CAJ7c6TOMG8zSNEZtCn5SPe+cCk3Lfxb71ZaQwT2F4T7PJ_t=KA@mail.gmail.com
diff --git a/src/include/pgtime.h b/src/include/pgtime.h
@@ -22,14 +22,21 @@
 
 typedef int64 pg_time_t;
 
+/*
+ * CAUTION: the IANA timezone library (src/timezone/) follows the POSIX
+ * convention that tm_mon counts from 0 and tm_year is relative to 1900.
+ * However, Postgres' datetime functions generally treat tm_mon as counting
+ * from 1 and tm_year as relative to 1 BC.  Be sure to make the appropriate
+ * adjustments when moving from one code domain to the other.
+ */
 struct pg_tm
 {
 	int			tm_sec;
 	int			tm_min;
 	int			tm_hour;
 	int			tm_mday;
-	int			tm_mon;			/* origin 1, not 0! */
-	int			tm_year;		/* relative to 1900 */
+	int			tm_mon;			/* see above */
+	int			tm_year;		/* see above */
 	int			tm_wday;
 	int			tm_yday;
 	int			tm_isdst;
