1 ;;; time-date.el --- Date and time handling functions
3 ;; Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006,
4 ;; 2007, 2008 Free Software Foundation, Inc.
6 ;; Author: Lars Magne Ingebrigtsen <larsi@gnus.org>
7 ;; Masanobu Umeda <umerin@mse.kyutech.ac.jp>
8 ;; Keywords: mail news util
10 ;; This file is part of GNU Emacs.
12 ;; GNU Emacs is free software; you can redistribute it and/or modify
13 ;; it under the terms of the GNU General Public License as published by
14 ;; the Free Software Foundation; either version 3, or (at your option)
17 ;; GNU Emacs is distributed in the hope that it will be useful,
18 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
19 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 ;; GNU General Public License for more details.
22 ;; You should have received a copy of the GNU General Public License
23 ;; along with GNU Emacs; see the file COPYING. If not, write to the
24 ;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
25 ;; Boston, MA 02110-1301, USA.
29 ;; Time values come in three formats. The oldest format is a cons
30 ;; cell of the form (HIGH . LOW). This format is obsolete, but still
31 ;; supported. The two other formats are the lists (HIGH LOW) and
32 ;; (HIGH LOW MICRO). The first two formats specify HIGH * 2^16 + LOW
33 ;; seconds; the third format specifies HIGH * 2^16 + LOW + MICRO /
34 ;; 1000000 seconds. We should have 0 <= MICRO < 1000000 and 0 <= LOW
35 ;; < 2^16. If the time value represents a point in time, then HIGH is
36 ;; nonnegative. If the time value is a time difference, then HIGH can
37 ;; be negative as well. The macro `with-decoded-time-value' and the
38 ;; function `encode-time-value' make it easier to deal with these
39 ;; three formats. See `time-subtract' for an example of how to use
44 (defmacro with-decoded-time-value (varlist &rest body)
45 "Decode a time value and bind it according to VARLIST, then eval BODY.
47 The value of the last form in BODY is returned.
49 Each element of the list VARLIST is a list of the form
50 \(HIGH-SYMBOL LOW-SYMBOL MICRO-SYMBOL [TYPE-SYMBOL] TIME-VALUE).
51 The time value TIME-VALUE is decoded and the result it bound to
52 the symbols HIGH-SYMBOL, LOW-SYMBOL and MICRO-SYMBOL.
54 The optional TYPE-SYMBOL is bound to the type of the time value.
55 Type 0 is the cons cell (HIGH . LOW), type 1 is the list (HIGH
56 LOW), and type 2 is the list (HIGH LOW MICRO)."
58 (debug ((&rest (symbolp symbolp symbolp &or [symbolp form] form))
61 (let* ((elt (pop varlist))
65 (type (unless (eq (length elt) 1)
67 (time-value (car elt))
68 (gensym (make-symbol "time")))
69 `(let* ,(append `((,gensym ,time-value)
75 (setq ,low (pop ,gensym))
77 ,(append `(setq ,micro (car ,gensym))
78 (when type `(,type 2)))
79 ,(append `(setq ,micro 0)
80 (when type `(,type 1)))))
81 ,(append `(setq ,low ,gensym ,micro 0)
82 (when type `(,type 0))))
83 (with-decoded-time-value ,varlist ,@body)))
86 (defun encode-time-value (high low micro type)
87 "Encode HIGH, LOW, and MICRO into a time value of type TYPE.
88 Type 0 is the cons cell (HIGH . LOW), type 1 is the list (HIGH LOW),
89 and type 2 is the list (HIGH LOW MICRO)."
91 ((eq type 0) (cons high low))
92 ((eq type 1) (list high low))
93 ((eq type 2) (list high low micro))))
95 (autoload 'parse-time-string "parse-time")
96 (autoload 'timezone-make-date-arpa-standard "timezone")
99 (defun date-to-time (date)
100 "Parse a string that represents a date-time and return a time value."
104 ;; `parse-time-string' isn't sufficiently general or
105 ;; robust. It fails to grok some of the formats that
106 ;; timezone does (e.g. dodgy post-2000 stuff from some
107 ;; Elms) and either fails or returns bogus values. Lars
108 ;; reverted this change, but that loses non-trivially
109 ;; often for me. -- fx
110 (timezone-make-date-arpa-standard date)))
111 (error (error "Invalid date: %s" date))))
113 (defun time-to-seconds (time)
114 "Convert time value TIME to a floating point number.
115 You can use `float-time' instead."
116 (with-decoded-time-value ((high low micro time))
117 (+ (* 1.0 high 65536)
119 (/ micro 1000000.0))))
122 (defun seconds-to-time (seconds)
123 "Convert SECONDS (a floating point number) to a time value."
124 (list (floor seconds 65536)
125 (floor (mod seconds 65536))
126 (floor (* (- seconds (ffloor seconds)) 1000000))))
129 (defun time-less-p (t1 t2)
130 "Say whether time value T1 is less than time value T2."
131 (with-decoded-time-value ((high1 low1 micro1 t1)
132 (high2 low2 micro2 t2))
137 (< micro1 micro2)))))))
140 (defun days-to-time (days)
141 "Convert DAYS into a time value."
142 (let* ((seconds (* 1.0 days 60 60 24))
143 (high (condition-case nil (floor (/ seconds 65536))
144 (range-error most-positive-fixnum))))
145 (list high (condition-case nil (floor (- seconds (* 1.0 high 65536)))
146 (range-error 65535)))))
149 (defun time-since (time)
150 "Return the time elapsed since TIME.
151 TIME should be either a time value or a date-time string."
153 ;; Convert date strings to internal time.
154 (setq time (date-to-time time)))
155 (time-subtract (current-time) time))
158 (defalias 'subtract-time 'time-subtract)
161 (defun time-subtract (t1 t2)
162 "Subtract two time values.
163 Return the difference in the format of a time value."
164 (with-decoded-time-value ((high low micro type t1)
165 (high2 low2 micro2 type2 t2))
166 (setq high (- high high2)
168 micro (- micro micro2)
169 type (max type type2))
172 micro (+ micro 1000000)))
176 (encode-time-value high low micro type)))
179 (defun time-add (t1 t2)
180 "Add two time values. One should represent a time difference."
181 (with-decoded-time-value ((high low micro type t1)
182 (high2 low2 micro2 type2 t2))
183 (setq high (+ high high2)
185 micro (+ micro micro2)
186 type (max type type2))
187 (when (>= micro 1000000)
189 micro (- micro 1000000)))
193 (encode-time-value high low micro type)))
196 (defun date-to-day (date)
197 "Return the number of days between year 1 and DATE.
198 DATE should be a date-time string."
199 (time-to-days (date-to-time date)))
202 (defun days-between (date1 date2)
203 "Return the number of days between DATE1 and DATE2.
204 DATE1 and DATE2 should be date-time strings."
205 (- (date-to-day date1) (date-to-day date2)))
208 (defun date-leap-year-p (year)
209 "Return t if YEAR is a leap year."
210 (or (and (zerop (% year 4))
211 (not (zerop (% year 100))))
212 (zerop (% year 400))))
215 (defun time-to-day-in-year (time)
216 "Return the day number within the year of the date month/day/year."
217 (let* ((tim (decode-time time))
221 (day-of-year (+ day (* 31 (1- month)))))
223 (setq day-of-year (- day-of-year (/ (+ 23 (* 4 month)) 10)))
224 (when (date-leap-year-p year)
225 (setq day-of-year (1+ day-of-year))))
229 (defun time-to-days (time)
230 "The number of days between the Gregorian date 0001-12-31bce and TIME.
231 TIME should be a time value.
232 The Gregorian date Sunday, December 31, 1bce is imaginary."
233 (let* ((tim (decode-time time))
237 (+ (time-to-day-in-year time) ; Days this year
238 (* 365 (1- year)) ; + Days in prior years
239 (/ (1- year) 4) ; + Julian leap years
240 (- (/ (1- year) 100)) ; - century years
241 (/ (1- year) 400)))) ; + Gregorian leap years
243 (defun time-to-number-of-days (time)
244 "Return the number of days represented by TIME.
245 The number of days will be returned as a floating point number."
246 (/ (time-to-seconds time) (* 60 60 24)))
249 (defun safe-date-to-time (date)
250 "Parse a string that represents a date-time and return a time value.
251 If DATE is malformed, return a time value of zeros."
258 (defun format-seconds (string seconds)
259 "Use format control STRING to format the number SECONDS.
260 The valid format specifiers are:
261 %y is the number of (365-day) years.
262 %d is the number of days.
263 %h is the number of hours.
264 %m is the number of minutes.
265 %s is the number of seconds.
266 %z is a non-printing control flag (see below).
267 %% is a literal \"%\".
269 Upper-case specifiers are followed by the unit-name (e.g. \"years\").
270 Lower-case specifiers return only the unit.
272 \"%\" may be followed by a number specifying a width, with an
273 optional leading \".\" for zero-padding. For example, \"%.3Y\" will
274 return something of the form \"001 year\".
276 The \"%z\" specifier does not print anything. When it is used, specifiers
277 must be given in order of decreasing size. To the left of \"%z\", nothing
278 is output until the first non-zero unit is encountered.
280 This function does not work for SECONDS greater than `most-positive-fixnum'."
282 (units '(("y" "year" 31536000)
289 spec match usedunits zeroflag larger prev name unit num zeropos)
290 (while (string-match "%\\.?[0-9]*\\(.\\)" string start)
291 (setq start (match-end 0)
292 spec (match-string 1 string))
293 (unless (string-equal spec "%")
294 (or (setq match (assoc-string spec units t))
295 (error "Bad format specifier: `%s'" spec))
296 (if (assoc-string spec usedunits t)
297 (error "Multiple instances of specifier: `%s'" spec))
298 (if (string-equal (car match) "z")
301 (setq unit (nth 2 match)
302 larger (and prev (> unit prev))
304 (push match usedunits)))
306 (error "Units are not in decreasing order of size"))
311 (when (string-match (format "%%\\(\\.?[0-9]+\\)?\\(%s\\)" spec) string)
312 (if (string-equal spec "z") ; must be last in units
314 (replace-regexp-in-string
316 (substring string (min (or zeropos (match-end 0))
317 (match-beginning 0)))))
318 ;; Cf article-make-date-line in gnus-art.
319 (setq num (floor seconds unit)
320 seconds (- seconds (* num unit)))
321 ;; Start position of the first non-zero unit.
323 (setq zeropos (unless (zerop num) (match-beginning 0))))
326 (format (concat "%" (match-string 1 string) "d%s") num
327 (if (string-equal (match-string 2 string) spec)
328 "" ; lower-case, no unit-name
330 (if (= num 1) "" "s"))))
332 (replace-regexp-in-string "%%" "%" string))
337 ;;; arch-tag: addcf07b-b20a-465b-af72-550b8ac5190f
338 ;;; time-date.el ends here