Re: CVS commit: src/lib/libc/time

[Robert Elz <kre%munnari.OZ.AU@localhost>]

    Date:        Sat, 22 Oct 2022 13:42:54 -0400
    From:        Jan Schaumann <jschauma%netmeister.org@localhost>
    Message-ID:  <Y1QrnixDev1BN99Y%netmeister.org@localhost>

  | 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.

[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.]

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.

  | 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.

kre