On Sat, Oct 22, 2022, 8:05 PM Robert Elz <k...@munnari.oz.au> wrote: > Date: Sat, 22 Oct 2022 13:42:54 -0400 > From: Jan Schaumann <jscha...@netmeister.org> > Message-ID: <y1qrnixdev1bn...@netmeister.org> > > | A full set of examples strikes me as too much here > > A full set would be yes, but I think we could handle 3. > They don't need to be C code examples, just something > like > if tm_year==2022 tm_mon==10 tm_mday==19 > tm_hour==23 tm_min==58 tm_sec==17 and tm_dst==-1 > > and tm_min was incremented as tm_min+=180, and then > mktime() called upon the result, the struct tm would > now have tm_min==1 tm_hour==24 and tm_mday==20, with > tm_isdst 0 or 1 depending upon the local time zone. > The other fields shown would not be altered in this > example, the fields of struct tm not show here would > (tm_wday, ...) would be filled in with appropriate values. >
That sounds like a good idea... [Using tm_min rather than tm_sec to avoid needing to include > caveats about possible leap seconds, which, at least currently, > could never happen in November, but all of that is too much > to bother with.] > On the other hand, adding a caveat that leap seconds don't exist in a POSIX time_t and that's necessarily reflected in the normalization wouldn't be bad. It's a quite common misconception that somehow they do because they exist in UTC... while you can encode any valid UTC time, they are always normalized away. The other examples could be even shorter, no need to repeat > the final sentence about the other field changes or otherwise. > > | Perhaps: > | > | This normalization is done in order from tm_sec up to > | tm_year, > > No, that is what you cannot say, because it is wrong. > > We do not always start from tm_sec, and tm_mon is *always* > normalised (with its possible flow on to tm_year) before > tm_mday - nothing else makes sense. tm_year isn't > "normalized" at all, though it might be adjusted. > > But all of this is what we already agreed is too much > to explain. And no matter how simple it makes things, > the man pages cannot (deliberately) lie. > Agreed. These nuances are important. | possibly leading to cascading values. That > | is, a tm_sec value of e.g., 185 with a tm_min value of > | 58 could lead to an increment of tm_min by three, and > | thus further incrementing tm_hour by one, and so on. > > This is more explaining how it works, which if we do at all, > we need to do correctly. That's where a few examples can > be better, they allow the reader to deduce what probably > happens, the weird one is there to show that the results > will not always be what is expected at first glance, but > that they always are correct. > > | As with most things relating to > | time, dates, and calendars, the full details of these > | side effects are often non‐obvious, and it may be best > | to avoid such scenarios. > > And that part is just useless, unless you mean that non-normalised > values should never be used, perhaps just in some fields (and it > isn't that anyway, a big enough increment of tm_sec is the same > as an increment of tm_mday or tm_mon) in which case we should just > say that. If not that, then hinting that it is sometimes odd, > and those cases, which ones we refuse to tell you, should be > avoided is a complete waste of time. Which scenarios should be > avoided? The answer really is none of them, the answer is > always correct, it just might not be what the user expected. > All good points. Warner > kre > >
