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

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

    Date:        Sun, 23 Oct 2022 13:53:01 -0400
    From:        Jan Schaumann <jschauma%netmeister.org@localhost>
    Message-ID:  <Y1V/fYAEKv9d9i/g%netmeister.org@localhost>

  | 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