Next: qp, Previous: rfc2047, Up: Basic Functions [Contents][Index]

### 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)

    (float-time '(13818 19266))
    ⇒ 905595714.0

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

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

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

    (time-since '(13818 19266))
    ⇒ (6797 9607 984839 247000)

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

    (time-subtract '(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")))
    ⇒ 4314.095589286675

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 0 0)`.

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.

`float-time`

  Take a time and return seconds. (This is a built-in function.)

`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. (This is a built-in function.)

`time-since`

  Take a time and return a time saying how long it was since that time.

`time-subtract`

  Take two times and subtract the second from the first. I.e., return the time between the two times. (This is a built-in function.)

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

Next: qp, Previous: rfc2047, Up: Basic Functions [Contents][Index]