encode-time vs decode-time

[Stefan Monnier]

> I think the pair makes sense on the same level as
> {decode,encode}-coding-string does.  That is, encoded time is what Emacs
> uses internally for most things, and decoded time is pretty close to
> what you er find in nature.

I think the problem is one of presentation and vocabulary, indeed.

I think we should clarify:

- "time string", as returned by format-time-string and accepted
  by parse-time-string.

- "decoded time", i.e. a list of the form (SECOND MINUTE HOUR DAY MONTH YEAR 
IGNORED DST ZONE)
  I just pushed a patch which defines the `decoded-time` *type*, so we can
  refer to that precise name in docstrings.

- "time counted in seconds" for which we support several representations:
  a plain number, a list of integers (HIGH LOW USEC PSEC), a pair of
  integers (NUMERATOR . DENOMINATOR).

And part of the confusion for me is that `encode-time` not only encodes
time, but can also be used to convert between different representations
of "time counted in seconds" (in which case it's not the inverse of
decode-time).


        Stefan