Date: Sun, 23 Oct 2022 13:53:01 -0400 From: Jan Schaumann <jscha...@netmeister.org> Message-ID: <Y1V/fYAEKv9d9i/g...@netmeister.org>
| Hmm, maybe something like this? I think there is still too much there, you don't have to explain everything (or almost anything), but it is in the right direction I think. | For example, consider a struct tm initialized with a | tm_year = 122, tm_mon = 11, tm_mday = 30, tm_hour = | 22, tm_min = 57, and a tm_sec = 0, using UTC, | representing 2022â12â31T22:57:00Z. That last bit (the ISO format spec of the time) isn't really needed, but doesn't hurt either - but I would avoid an example that touches anywhere near midnight Dec 31, UTC, (which this one does later, if not here) as that's exactly where leap seconds start to appear, and (as illustrated in the side-discussion in this thread) that's where things get messy. Best to just avoid that (Avoid June 30 for the same reason.) | Incrementing | tm_min by 13 and calling mktime() would yield a time_t | with value 1672528200, That's irrelevant, the time_t returned isn't what's really interesting here, and its binary value is way too much (useless) information, it is the modification made to the tm that matters. It is already clear enough in the doc (I think) that the result from mktime() is the time_t for the normalised tm. | representing 2022â12â31T23:10:00Z, this, or just give the adjusted tm_min and tm_hour values, there's no need for both, and | as the tm_min = 70 was | normalized to an increment of tm_hour by one and | tm_min = 10. no need for the explanation of how it was done. | This normalizing can lead to cascading changes: Again | using a struct tm initialized as in the above example | but with a tm_hour = 23, the same change would yield a | time_t with value 1672531800, representing | 2023â01â01T00:10:00Z That's the adjustment we want to avoid, as it gets right into what happens if we're observing leap seconds, and one was to happen in that period. There's no need to show the year being incremented, showing the month going up would be enough, readers ought to be able to deduce that if the month changes from Dec to Jan then the year would be incremented by one. | the normalization of tm_min incremented tm_hour, This explanation is not needed, but if it were, that would be correct, but | which lead to a normalization of tm_mday, which in | turn caused tm_mon to be normalized, but not those. Those fields (in this example) were already within the appropriate range, they don't need to be normalised, they're simply adjusted, or as in this (or tm_hour above): | which in turn lead to the increment of tm_year. | In addition, That's perhaps poor wording here, "addition" followed immediately by "negative", it could be "Also" which avoids this, but this lead in clause is not really needed at all, just begin like: | negative values may also be normalized, | such that e.g., a tm_hour of â1 means 1 hour before | midnight, tm_mday of 0 means the day preceding the | current month, and tm_mon of â2 means 2 months before | January of tm_year. Again, too much there, we don't need examples of everything. I still feel though that an example with more than one adjustment to a tm returned by localtime (though how it was originally created is irrelevant) and which would affect Feb 29 were it a leap year, would be worth giving (in both the leap year and non leap year cases) so we get Feb 29 in one case and Mar 1 in the other, from an adjustment that affects months (and days, either directly, or as a flow on from hours, mins, or secs) - like going back a month from Mar 28, then forward to the next day, and sometimes still being in Mar. | The fact that mktime(2) returns a time_t makes the | phrasing even more awkward, Yes, as above. | and I suppose we could | leave out the actual value and say "would yield a | time_t representing..."? No, nothing about the result returned at all, this should all just be about what normalising the tm causes to happen. Those values are not just internal, the tm passed (via ref) is modified if needed before mktime returns. kre