1 ;;; time-date.el --- date and time handling functions
2 ;; Copyright (C) 1998, 1999, 2000, 2004, 2005 Free Software Foundation, Inc.
4 ;; Author: Lars Magne Ingebrigtsen <larsi@gnus.org>
5 ;; Masanobu Umeda <umerin@mse.kyutech.ac.jp>
6 ;; Keywords: mail news util
8 ;; This file is part of GNU Emacs.
10 ;; GNU Emacs is free software; you can redistribute it and/or modify
11 ;; it under the terms of the GNU General Public License as published by
12 ;; the Free Software Foundation; either version 2, or (at your option)
15 ;; GNU Emacs is distributed in the hope that it will be useful,
16 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
17 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 ;; GNU General Public License for more details.
20 ;; You should have received a copy of the GNU General Public License
21 ;; along with GNU Emacs; see the file COPYING. If not, write to the
22 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
23 ;; Boston, MA 02111-1307, USA.
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
42 (defmacro with-decoded-time-value (varlist &rest body)
43 "Decode a time value and bind it according to VARLIST, then eval BODY.
45 The value of the last form in BODY is returned.
47 Each element of the list VARLIST is a list of the form
48 \(HIGH-SYMBOL LOW-SYMBOL MICRO-SYMBOL [TYPE-SYMBOL] TIME-VALUE).
49 The time value TIME-VALUE is decoded and the result it bound to
50 the symbols HIGH-SYMBOL, LOW-SYMBOL and MICRO-SYMBOL.
52 The optional TYPE-SYMBOL is bound to the type of the time value.
53 Type 0 is the cons cell (HIGH . LOW), type 1 is the list (HIGH
54 LOW), and type 3 is the list (HIGH LOW MICRO)."
56 (debug ((&rest (symbolp symbolp symbolp &or [symbolp form] form))
59 (let* ((elt (pop varlist))
63 (type (unless (eq (length elt) 1)
65 (time-value (car elt))
66 (gensym (make-symbol "time")))
67 `(let* ,(append `((,gensym ,time-value)
73 (setq ,low (pop ,gensym))
75 ,(append `(setq ,micro (car ,gensym))
76 (when type `(,type 2)))
77 ,(append `(setq ,micro 0)
78 (when type `(,type 1)))))
79 ,(append `(setq ,low ,gensym ,micro 0)
80 (when type `(,type 0))))
81 (with-decoded-time-value ,varlist ,@body)))
84 (defun encode-time-value (high low micro type)
85 "Encode HIGH, LOW, and MICRO into a time value of type TYPE.
86 Type 0 is the cons cell (HIGH . LOW), type 1 is the list (HIGH LOW),
87 and type 3 is the list (HIGH LOW MICRO)."
89 ((eq type 0) (cons high low))
90 ((eq type 1) (list high low))
91 ((eq type 2) (list high low micro))))
93 (autoload 'timezone-make-date-arpa-standard "timezone")
96 (defun date-to-time (date)
97 "Parse a string that represents a date-time and return a time value."
101 ;; `parse-time-string' isn't sufficiently general or
102 ;; robust. It fails to grok some of the formats that
103 ;; timezone does (e.g. dodgy post-2000 stuff from some
104 ;; Elms) and either fails or returns bogus values. Lars
105 ;; reverted this change, but that loses non-trivially
106 ;; often for me. -- fx
107 (timezone-make-date-arpa-standard date)))
108 (error (error "Invalid date: %s" date))))
111 (defun time-to-seconds (time)
112 "Convert time value TIME to a floating point number.
113 You can use `float-time' instead."
114 (with-decoded-time-value ((high low micro time))
115 (+ (* 1.0 high #x10000)
117 (/ micro 1000000.0))))
120 (defun seconds-to-time (seconds)
121 "Convert SECONDS (a floating point number) to a time value."
122 (list (floor seconds #x10000)
123 (floor (mod seconds #x10000))
124 (floor (* (- seconds (ffloor seconds)) 1000000))))
127 (defun time-less-p (t1 t2)
128 "Say whether time value T1 is less than time value T2."
129 (with-decoded-time-value ((high1 low1 micro1 t1)
130 (high2 low2 micro2 t2))
135 (< micro1 micro2)))))))
138 (defun days-to-time (days)
139 "Convert DAYS into a time value."
140 (let* ((seconds (* 1.0 days 60 60 24))
141 (high (condition-case nil (floor (/ seconds #x10000))
142 (range-error most-positive-fixnum))))
143 (list high (condition-case nil (floor (- seconds (* 1.0 high #x10000)))
144 (range-error #xffff)))))
147 (defun time-since (time)
148 "Return the time elapsed since TIME.
149 TIME should be either a time value or a date-time string."
151 ;; Convert date strings to internal time.
152 (setq time (date-to-time time)))
153 (time-subtract (current-time) time))
156 (defalias 'subtract-time 'time-subtract)
159 (defun time-subtract (t1 t2)
160 "Subtract two time values.
161 Return the difference in the format of a time value."
162 (with-decoded-time-value ((high low micro type t1)
163 (high2 low2 micro2 type2 t2))
164 (setq high (- high high2)
166 micro (- micro micro2)
167 type (max type type2))
170 micro (+ micro 1000000)))
173 low (+ low #x10000)))
174 (encode-time-value high low micro type)))
177 (defun time-add (t1 t2)
178 "Add two time values. One should represent a time difference."
179 (with-decoded-time-value ((high low micro type t1)
180 (high2 low2 micro2 type2 t2))
181 (setq high (+ high high2)
183 micro (+ micro micro2)
184 type (max type type2))
185 (when (>= micro 1000000)
187 micro (- micro 1000000)))
188 (when (>= low #x10000)
190 low (- low #x10000)))
191 (encode-time-value high low micro type)))
194 (defun date-to-day (date)
195 "Return the number of days between year 1 and DATE.
196 DATE should be a date-time string."
197 (time-to-days (date-to-time date)))
200 (defun days-between (date1 date2)
201 "Return the number of days between DATE1 and DATE2.
202 DATE1 and DATE2 should be date-time strings."
203 (- (date-to-day date1) (date-to-day date2)))
206 (defun date-leap-year-p (year)
207 "Return t if YEAR is a leap year."
208 (or (and (zerop (% year 4))
209 (not (zerop (% year 100))))
210 (zerop (% year 400))))
213 (defun time-to-day-in-year (time)
214 "Return the day number within the year corresponding to TIME."
215 (let* ((tim (decode-time time))
219 (day-of-year (+ day (* 31 (1- month)))))
221 (setq day-of-year (- day-of-year (/ (+ 23 (* 4 month)) 10)))
222 (when (date-leap-year-p year)
223 (setq day-of-year (1+ day-of-year))))
227 (defun time-to-days (time)
228 "The number of days between the Gregorian date 0001-12-31bce and TIME.
229 TIME should be a time value.
230 The Gregorian date Sunday, December 31, 1bce is imaginary."
231 (let* ((tim (decode-time time))
235 (+ (time-to-day-in-year time) ; Days this year
236 (* 365 (1- year)) ; + Days in prior years
237 (/ (1- year) 4) ; + Julian leap years
238 (- (/ (1- year) 100)) ; - century years
239 (/ (1- year) 400)))) ; + Gregorian leap years
241 (defun time-to-number-of-days (time)
242 "Return the number of days represented by TIME.
243 The number of days will be returned as a floating point number."
244 (/ (time-to-seconds time) (* 60 60 24)))
247 (defun safe-date-to-time (date)
248 "Parse a string that represents a date-time and return a time value.
249 If DATE is malformed, return a time value of zeros."
256 ;;; arch-tag: addcf07b-b20a-465b-af72-550b8ac5190f
257 ;;; time-date.el ends here