Commit | Line | Data |
---|---|---|
707f2b38 | 1 | ;;; time-date.el --- Date and time handling functions |
dbfca9c4 | 2 | |
6afa3d67 | 3 | ;; Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, |
5df4f04c | 4 | ;; 2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc. |
c113de23 GM |
5 | |
6 | ;; Author: Lars Magne Ingebrigtsen <larsi@gnus.org> | |
7 | ;; Masanobu Umeda <umerin@mse.kyutech.ac.jp> | |
8 | ;; Keywords: mail news util | |
9 | ||
10 | ;; This file is part of GNU Emacs. | |
11 | ||
2ed66575 | 12 | ;; GNU Emacs is free software: you can redistribute it and/or modify |
c113de23 | 13 | ;; it under the terms of the GNU General Public License as published by |
2ed66575 GM |
14 | ;; the Free Software Foundation, either version 3 of the License, or |
15 | ;; (at your option) any later version. | |
c113de23 GM |
16 | |
17 | ;; GNU Emacs is distributed in the hope that it will be useful, | |
18 | ;; but WITHOUT ANY WARRANTY; without even the implied warranty of | |
2ed66575 | 19 | ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
c113de23 GM |
20 | ;; GNU General Public License for more details. |
21 | ||
22 | ;; You should have received a copy of the GNU General Public License | |
2ed66575 | 23 | ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>. |
c113de23 GM |
24 | |
25 | ;;; Commentary: | |
26 | ||
ca2d9ad8 LK |
27 | ;; Time values come in three formats. The oldest format is a cons |
28 | ;; cell of the form (HIGH . LOW). This format is obsolete, but still | |
29 | ;; supported. The two other formats are the lists (HIGH LOW) and | |
30 | ;; (HIGH LOW MICRO). The first two formats specify HIGH * 2^16 + LOW | |
31 | ;; seconds; the third format specifies HIGH * 2^16 + LOW + MICRO / | |
32 | ;; 1000000 seconds. We should have 0 <= MICRO < 1000000 and 0 <= LOW | |
33 | ;; < 2^16. If the time value represents a point in time, then HIGH is | |
34 | ;; nonnegative. If the time value is a time difference, then HIGH can | |
35 | ;; be negative as well. The macro `with-decoded-time-value' and the | |
36 | ;; function `encode-time-value' make it easier to deal with these | |
37 | ;; three formats. See `time-subtract' for an example of how to use | |
38 | ;; them. | |
39 | ||
c113de23 GM |
40 | ;;; Code: |
41 | ||
e3e955fe MB |
42 | ;; Only necessary for `declare' when compiling Gnus with Emacs 21. |
43 | (eval-when-compile (require 'cl)) | |
44 | ||
ca2d9ad8 LK |
45 | (defmacro with-decoded-time-value (varlist &rest body) |
46 | "Decode a time value and bind it according to VARLIST, then eval BODY. | |
47 | ||
48 | The value of the last form in BODY is returned. | |
49 | ||
50 | Each element of the list VARLIST is a list of the form | |
51 | \(HIGH-SYMBOL LOW-SYMBOL MICRO-SYMBOL [TYPE-SYMBOL] TIME-VALUE). | |
52 | The time value TIME-VALUE is decoded and the result it bound to | |
53 | the symbols HIGH-SYMBOL, LOW-SYMBOL and MICRO-SYMBOL. | |
54 | ||
55 | The optional TYPE-SYMBOL is bound to the type of the time value. | |
56 | Type 0 is the cons cell (HIGH . LOW), type 1 is the list (HIGH | |
e07ea833 | 57 | LOW), and type 2 is the list (HIGH LOW MICRO)." |
ca2d9ad8 LK |
58 | (declare (indent 1) |
59 | (debug ((&rest (symbolp symbolp symbolp &or [symbolp form] form)) | |
60 | body))) | |
61 | (if varlist | |
62 | (let* ((elt (pop varlist)) | |
63 | (high (pop elt)) | |
64 | (low (pop elt)) | |
65 | (micro (pop elt)) | |
66 | (type (unless (eq (length elt) 1) | |
67 | (pop elt))) | |
68 | (time-value (car elt)) | |
69 | (gensym (make-symbol "time"))) | |
70 | `(let* ,(append `((,gensym ,time-value) | |
71 | (,high (pop ,gensym)) | |
72 | ,low ,micro) | |
73 | (when type `(,type))) | |
74 | (if (consp ,gensym) | |
75 | (progn | |
76 | (setq ,low (pop ,gensym)) | |
77 | (if ,gensym | |
78 | ,(append `(setq ,micro (car ,gensym)) | |
79 | (when type `(,type 2))) | |
80 | ,(append `(setq ,micro 0) | |
81 | (when type `(,type 1))))) | |
82 | ,(append `(setq ,low ,gensym ,micro 0) | |
83 | (when type `(,type 0)))) | |
84 | (with-decoded-time-value ,varlist ,@body))) | |
85 | `(progn ,@body))) | |
86 | ||
87 | (defun encode-time-value (high low micro type) | |
88 | "Encode HIGH, LOW, and MICRO into a time value of type TYPE. | |
89 | Type 0 is the cons cell (HIGH . LOW), type 1 is the list (HIGH LOW), | |
e4b07c8b | 90 | and type 2 is the list (HIGH LOW MICRO)." |
ca2d9ad8 LK |
91 | (cond |
92 | ((eq type 0) (cons high low)) | |
93 | ((eq type 1) (list high low)) | |
94 | ((eq type 2) (list high low micro)))) | |
c113de23 | 95 | |
bbcb5072 | 96 | (autoload 'parse-time-string "parse-time") |
ce2a8a6a DL |
97 | (autoload 'timezone-make-date-arpa-standard "timezone") |
98 | ||
c113de23 GM |
99 | ;;;###autoload |
100 | (defun date-to-time (date) | |
244b023e CY |
101 | "Parse a string DATE that represents a date-time and return a time value. |
102 | If DATE lacks timezone information, GMT is assumed." | |
c113de23 | 103 | (condition-case () |
ce2a8a6a DL |
104 | (apply 'encode-time |
105 | (parse-time-string | |
106 | ;; `parse-time-string' isn't sufficiently general or | |
107 | ;; robust. It fails to grok some of the formats that | |
23f87bed | 108 | ;; timezone does (e.g. dodgy post-2000 stuff from some |
ce2a8a6a DL |
109 | ;; Elms) and either fails or returns bogus values. Lars |
110 | ;; reverted this change, but that loses non-trivially | |
111 | ;; often for me. -- fx | |
112 | (timezone-make-date-arpa-standard date))) | |
c113de23 GM |
113 | (error (error "Invalid date: %s" date)))) |
114 | ||
697c7714 GM |
115 | ;; Bit of a mess. Emacs has float-time since at least 21.1. |
116 | ;; This file is synced to Gnus, and XEmacs packages may have been written | |
117 | ;; using time-to-seconds from the Gnus library. | |
cdce0b33 KY |
118 | ;;;###autoload(if (and (fboundp 'float-time) |
119 | ;;;###autoload (subrp (symbol-function 'float-time))) | |
120 | ;;;###autoload (progn | |
121 | ;;;###autoload (defalias 'time-to-seconds 'float-time) | |
122 | ;;;###autoload (make-obsolete 'time-to-seconds 'float-time "21.1")) | |
123 | ;;;###autoload (autoload 'time-to-seconds "time-date")) | |
124 | ||
125 | (eval-and-compile | |
126 | (unless (and (fboundp 'float-time) | |
127 | (subrp (symbol-function 'float-time))) | |
697c7714 GM |
128 | (defun time-to-seconds (time) |
129 | "Convert time value TIME to a floating point number." | |
130 | (with-decoded-time-value ((high low micro time)) | |
cdce0b33 KY |
131 | (+ (* 1.0 high 65536) |
132 | low | |
133 | (/ micro 1000000.0)))))) | |
134 | ||
135 | (eval-when-compile | |
136 | (unless (fboundp 'with-no-warnings) | |
137 | (defmacro with-no-warnings (&rest body) | |
138 | `(progn ,@body)))) | |
c113de23 | 139 | |
74fcda73 | 140 | ;;;###autoload |
c113de23 | 141 | (defun seconds-to-time (seconds) |
74fcda73 | 142 | "Convert SECONDS (a floating point number) to a time value." |
91472578 MB |
143 | (list (floor seconds 65536) |
144 | (floor (mod seconds 65536)) | |
c113de23 GM |
145 | (floor (* (- seconds (ffloor seconds)) 1000000)))) |
146 | ||
74fcda73 | 147 | ;;;###autoload |
c113de23 | 148 | (defun time-less-p (t1 t2) |
74fcda73 | 149 | "Say whether time value T1 is less than time value T2." |
ca2d9ad8 LK |
150 | (with-decoded-time-value ((high1 low1 micro1 t1) |
151 | (high2 low2 micro2 t2)) | |
152 | (or (< high1 high2) | |
153 | (and (= high1 high2) | |
154 | (or (< low1 low2) | |
155 | (and (= low1 low2) | |
156 | (< micro1 micro2))))))) | |
c113de23 | 157 | |
74fcda73 | 158 | ;;;###autoload |
c113de23 | 159 | (defun days-to-time (days) |
74fcda73 | 160 | "Convert DAYS into a time value." |
c113de23 | 161 | (let* ((seconds (* 1.0 days 60 60 24)) |
91472578 | 162 | (high (condition-case nil (floor (/ seconds 65536)) |
ca2d9ad8 | 163 | (range-error most-positive-fixnum)))) |
91472578 MB |
164 | (list high (condition-case nil (floor (- seconds (* 1.0 high 65536))) |
165 | (range-error 65535))))) | |
c113de23 | 166 | |
74fcda73 | 167 | ;;;###autoload |
c113de23 | 168 | (defun time-since (time) |
74fcda73 RS |
169 | "Return the time elapsed since TIME. |
170 | TIME should be either a time value or a date-time string." | |
c113de23 GM |
171 | (when (stringp time) |
172 | ;; Convert date strings to internal time. | |
173 | (setq time (date-to-time time))) | |
ca2d9ad8 | 174 | (time-subtract (current-time) time)) |
c113de23 | 175 | |
74fcda73 RS |
176 | ;;;###autoload |
177 | (defalias 'subtract-time 'time-subtract) | |
178 | ||
179 | ;;;###autoload | |
180 | (defun time-subtract (t1 t2) | |
7d4005cc | 181 | "Subtract two time values, T1 minus T2. |
74fcda73 | 182 | Return the difference in the format of a time value." |
ca2d9ad8 LK |
183 | (with-decoded-time-value ((high low micro type t1) |
184 | (high2 low2 micro2 type2 t2)) | |
185 | (setq high (- high high2) | |
186 | low (- low low2) | |
187 | micro (- micro micro2) | |
188 | type (max type type2)) | |
189 | (when (< micro 0) | |
190 | (setq low (1- low) | |
191 | micro (+ micro 1000000))) | |
192 | (when (< low 0) | |
193 | (setq high (1- high) | |
91472578 | 194 | low (+ low 65536))) |
ca2d9ad8 | 195 | (encode-time-value high low micro type))) |
c113de23 | 196 | |
74fcda73 RS |
197 | ;;;###autoload |
198 | (defun time-add (t1 t2) | |
7d4005cc | 199 | "Add two time values T1 and T2. One should represent a time difference." |
ca2d9ad8 LK |
200 | (with-decoded-time-value ((high low micro type t1) |
201 | (high2 low2 micro2 type2 t2)) | |
202 | (setq high (+ high high2) | |
203 | low (+ low low2) | |
204 | micro (+ micro micro2) | |
205 | type (max type type2)) | |
206 | (when (>= micro 1000000) | |
207 | (setq low (1+ low) | |
208 | micro (- micro 1000000))) | |
91472578 | 209 | (when (>= low 65536) |
ca2d9ad8 | 210 | (setq high (1+ high) |
91472578 | 211 | low (- low 65536))) |
ca2d9ad8 | 212 | (encode-time-value high low micro type))) |
74fcda73 RS |
213 | |
214 | ;;;###autoload | |
c113de23 | 215 | (defun date-to-day (date) |
74fcda73 RS |
216 | "Return the number of days between year 1 and DATE. |
217 | DATE should be a date-time string." | |
c113de23 GM |
218 | (time-to-days (date-to-time date))) |
219 | ||
74fcda73 | 220 | ;;;###autoload |
c113de23 | 221 | (defun days-between (date1 date2) |
74fcda73 RS |
222 | "Return the number of days between DATE1 and DATE2. |
223 | DATE1 and DATE2 should be date-time strings." | |
c113de23 GM |
224 | (- (date-to-day date1) (date-to-day date2))) |
225 | ||
74fcda73 | 226 | ;;;###autoload |
c113de23 GM |
227 | (defun date-leap-year-p (year) |
228 | "Return t if YEAR is a leap year." | |
229 | (or (and (zerop (% year 4)) | |
230 | (not (zerop (% year 100)))) | |
231 | (zerop (% year 400)))) | |
232 | ||
74fcda73 | 233 | ;;;###autoload |
c113de23 | 234 | (defun time-to-day-in-year (time) |
1525ea1e | 235 | "Return the day number within the year corresponding to TIME." |
c113de23 GM |
236 | (let* ((tim (decode-time time)) |
237 | (month (nth 4 tim)) | |
238 | (day (nth 3 tim)) | |
239 | (year (nth 5 tim)) | |
240 | (day-of-year (+ day (* 31 (1- month))))) | |
241 | (when (> month 2) | |
242 | (setq day-of-year (- day-of-year (/ (+ 23 (* 4 month)) 10))) | |
243 | (when (date-leap-year-p year) | |
244 | (setq day-of-year (1+ day-of-year)))) | |
245 | day-of-year)) | |
246 | ||
74fcda73 | 247 | ;;;###autoload |
c113de23 GM |
248 | (defun time-to-days (time) |
249 | "The number of days between the Gregorian date 0001-12-31bce and TIME. | |
74fcda73 | 250 | TIME should be a time value. |
c113de23 GM |
251 | The Gregorian date Sunday, December 31, 1bce is imaginary." |
252 | (let* ((tim (decode-time time)) | |
253 | (month (nth 4 tim)) | |
254 | (day (nth 3 tim)) | |
255 | (year (nth 5 tim))) | |
256 | (+ (time-to-day-in-year time) ; Days this year | |
257 | (* 365 (1- year)) ; + Days in prior years | |
258 | (/ (1- year) 4) ; + Julian leap years | |
259 | (- (/ (1- year) 100)) ; - century years | |
260 | (/ (1- year) 400)))) ; + Gregorian leap years | |
261 | ||
cdce0b33 KY |
262 | (eval-and-compile |
263 | (if (and (fboundp 'float-time) | |
264 | (subrp (symbol-function 'float-time))) | |
265 | (defun time-to-number-of-days (time) | |
266 | "Return the number of days represented by TIME. | |
267 | The number of days will be returned as a floating point number." | |
268 | (/ (float-time time) (* 60 60 24))) | |
269 | (defun time-to-number-of-days (time) | |
270 | "Return the number of days represented by TIME. | |
23f87bed | 271 | The number of days will be returned as a floating point number." |
cdce0b33 | 272 | (/ (with-no-warnings (time-to-seconds time)) (* 60 60 24))))) |
23f87bed | 273 | |
c113de23 GM |
274 | ;;;###autoload |
275 | (defun safe-date-to-time (date) | |
7d4005cc | 276 | "Parse a string DATE that represents a date-time and return a time value. |
74fcda73 | 277 | If DATE is malformed, return a time value of zeros." |
c113de23 GM |
278 | (condition-case () |
279 | (date-to-time date) | |
280 | (error '(0 0)))) | |
281 | ||
9ce1b62f | 282 | \f |
6afa3d67 | 283 | ;;;###autoload |
99d8d540 | 284 | (defun format-seconds (string seconds) |
6afa3d67 GM |
285 | "Use format control STRING to format the number SECONDS. |
286 | The valid format specifiers are: | |
287 | %y is the number of (365-day) years. | |
288 | %d is the number of days. | |
289 | %h is the number of hours. | |
290 | %m is the number of minutes. | |
291 | %s is the number of seconds. | |
99d8d540 | 292 | %z is a non-printing control flag (see below). |
6afa3d67 GM |
293 | %% is a literal \"%\". |
294 | ||
295 | Upper-case specifiers are followed by the unit-name (e.g. \"years\"). | |
296 | Lower-case specifiers return only the unit. | |
297 | ||
298 | \"%\" may be followed by a number specifying a width, with an | |
299 | optional leading \".\" for zero-padding. For example, \"%.3Y\" will | |
300 | return something of the form \"001 year\". | |
301 | ||
99d8d540 GM |
302 | The \"%z\" specifier does not print anything. When it is used, specifiers |
303 | must be given in order of decreasing size. To the left of \"%z\", nothing | |
304 | is output until the first non-zero unit is encountered. | |
6afa3d67 | 305 | |
99d8d540 | 306 | This function does not work for SECONDS greater than `most-positive-fixnum'." |
6afa3d67 GM |
307 | (let ((start 0) |
308 | (units '(("y" "year" 31536000) | |
309 | ("d" "day" 86400) | |
310 | ("h" "hour" 3600) | |
311 | ("m" "minute" 60) | |
99d8d540 GM |
312 | ("s" "second" 1) |
313 | ("z"))) | |
6afa3d67 | 314 | (case-fold-search t) |
99d8d540 | 315 | spec match usedunits zeroflag larger prev name unit num zeropos) |
6afa3d67 GM |
316 | (while (string-match "%\\.?[0-9]*\\(.\\)" string start) |
317 | (setq start (match-end 0) | |
318 | spec (match-string 1 string)) | |
319 | (unless (string-equal spec "%") | |
e3e955fe MB |
320 | ;; `assoc-string' is not available in Emacs 21. So when compiling |
321 | ;; Gnus (`time-date.el' is part of Gnus) with Emacs 21, we get a | |
322 | ;; warning here. But `format-seconds' is not used anywhere in Gnus so | |
323 | ;; it's not a real problem. --rsteib | |
6afa3d67 GM |
324 | (or (setq match (assoc-string spec units t)) |
325 | (error "Bad format specifier: `%s'" spec)) | |
99d8d540 | 326 | (if (assoc-string spec usedunits t) |
6afa3d67 | 327 | (error "Multiple instances of specifier: `%s'" spec)) |
99d8d540 GM |
328 | (if (string-equal (car match) "z") |
329 | (setq zeroflag t) | |
330 | (unless larger | |
331 | (setq unit (nth 2 match) | |
332 | larger (and prev (> unit prev)) | |
333 | prev unit))) | |
334 | (push match usedunits))) | |
335 | (and zeroflag larger | |
336 | (error "Units are not in decreasing order of size")) | |
337 | (dolist (u units) | |
338 | (setq spec (car u) | |
339 | name (cadr u) | |
340 | unit (nth 2 u)) | |
6afa3d67 | 341 | (when (string-match (format "%%\\(\\.?[0-9]+\\)?\\(%s\\)" spec) string) |
99d8d540 GM |
342 | (if (string-equal spec "z") ; must be last in units |
343 | (setq string | |
344 | (replace-regexp-in-string | |
345 | "%z" "" | |
346 | (substring string (min (or zeropos (match-end 0)) | |
347 | (match-beginning 0))))) | |
348 | ;; Cf article-make-date-line in gnus-art. | |
349 | (setq num (floor seconds unit) | |
350 | seconds (- seconds (* num unit))) | |
351 | ;; Start position of the first non-zero unit. | |
352 | (or zeropos | |
353 | (setq zeropos (unless (zerop num) (match-beginning 0)))) | |
354 | (setq string | |
355 | (replace-match | |
356 | (format (concat "%" (match-string 1 string) "d%s") num | |
357 | (if (string-equal (match-string 2 string) spec) | |
358 | "" ; lower-case, no unit-name | |
359 | (format " %s%s" name | |
360 | (if (= num 1) "" "s")))) | |
361 | t t string)))))) | |
6afa3d67 GM |
362 | (replace-regexp-in-string "%%" "%" string)) |
363 | ||
9ce1b62f | 364 | |
c113de23 GM |
365 | (provide 'time-date) |
366 | ||
cbee283d | 367 | ;; arch-tag: addcf07b-b20a-465b-af72-550b8ac5190f |
c113de23 | 368 | ;;; time-date.el ends here |