Next: qp, Previous: rfc2047, Up: Basic Functions

### 4.5 time-date

While not really a part of the MIME library, it is convenient to document this library here. It deals with parsing `Date` headers and manipulating time. (Not by using tesseracts, though, I'm sorry to say.)

These functions convert between five formats: A date string, an Emacs time structure, a decoded time list, a second number, and a day number.

Here's a bunch of time/date/second/day examples:

         (parse-time-string "Sat Sep 12 12:21:54 1998 +0200")
         ⇒ (54 21 12 12 9 1998 6 nil 7200)

         (date-to-time "Sat Sep 12 12:21:54 1998 +0200")
         ⇒ (13818 19266)

         (time-to-seconds '(13818 19266))
         ⇒ 905595714.0

         (seconds-to-time 905595714.0)
         ⇒ (13818 19266 0)

         (time-to-days '(13818 19266))
         ⇒ 729644

         (days-to-time 729644)
         ⇒ (961933 65536)

         (time-since '(13818 19266))
         ⇒ (0 430)

         (time-less-p '(13818 19266) '(13818 19145))
         ⇒ nil

         (subtract-time '(13818 19266) '(13818 19145))
         ⇒ (0 121)

         (days-between "Sat Sep 12 12:21:54 1998 +0200"
                       "Sat Sep 07 12:21:54 1998 +0200")
         ⇒ 5

         (date-leap-year-p 2000)
         ⇒ t

         (time-to-day-in-year '(13818 19266))
         ⇒ 255

         (time-to-number-of-days
          (time-since
           (date-to-time "Mon, 01 Jan 2001 02:22:26 GMT")))
         ⇒ 4.146122685185185

And finally, we have `safe-date-to-time`, which does the same as `date-to-time`, but returns a zero time if the date is syntactically malformed.

The five data representations used are the following:

date
  An RFC822 (or similar) date string. For instance: `"Sat Sep 12 12:21:54 1998 +0200"`.
time
  An internal Emacs time. For instance: `(13818 26466)`.
seconds
  A floating point representation of the internal Emacs time. For instance: `905595714.0`.
days
  An integer number representing the number of days since 00000101. For instance: `729644`.
decoded time
  A list of decoded time. For instance: `(54 21 12 12 9 1998 6 t 7200)`.

All the examples above represent the same moment.

These are the functions available:

`date-to-time`
  Take a date and return a time.
`time-to-seconds`
  Take a time and return seconds. Note that Emacs has a built-in function, `float-time`, that does this.
`seconds-to-time`
  Take seconds and return a time.
`time-to-days`
  Take a time and return days.
`days-to-time`
  Take days and return a time.
`date-to-day`
  Take a date and return days.
`time-to-number-of-days`
  Take a time and return the number of days that represents.
`safe-date-to-time`
  Take a date and return a time. If the date is not syntactically valid, return a “zero” time.
`time-less-p`
  Take two times and say whether the first time is less (i. e., earlier) than the second time.
`time-since`
  Take a time and return a time saying how long it was since that time.
`subtract-time`
  Take two times and subtract the second from the first. I. e., return the time between the two times.
`days-between`
  Take two days and return the number of days between those two days.
`date-leap-year-p`
  Take a year number and say whether it's a leap year.
`time-to-day-in-year`
  Take a time and return the day number within the year that the time is in.