Commit 5f3f3884 authored by Paul Eggert's avatar Paul Eggert

Improve time function doc

* doc/misc/emacs-mime.texi (time-date): Don’t give
parse-iso8601-time-string in the example, as the function is
not autoloaded.
* lisp/gnus/nndiary.el (nndiary-compute-reminders):
No need to call encode-time or use floating point here.
parent f01597a4
......@@ -1559,7 +1559,7 @@ or more arguments. The first six arguments @var{second},
specify most of the components of a decoded time. If there are more
than six arguments the @emph{last} argument is used as @var{zone} and
any other extra arguments are ignored, so that @code{(apply
#\\='encode-time (decode-time ...))} works; otherwise @var{zone} defaults
#'encode-time (decode-time ...))} works; otherwise @var{zone} defaults
to the current time zone rule (@pxref{Time Zone Rules}). The decoded
time's @var{dst} component is treated as if it was @minus{}1, and
@var{form} takes its default value.
......@@ -1581,7 +1581,7 @@ You can perform simple date arithmetic by using out-of-range values for
for example, day 0 means the day preceding the given month.
The operating system puts limits on the range of possible time values;
if you try to encode a time that is out of range, an error results.
if the limits are exceeded while encoding the time, an error results.
For instance, years before 1970 do not work on some systems;
on others, years as early as 1901 do work.
@end defun
......
......@@ -1541,10 +1541,6 @@ Here's a bunch of time/date/second/day examples:
1000000)
@result{} (905595714000000 . 1000000)
(encode-time (parse-iso8601-time-string "1998-09-12T12:21:54+0200")
1000000)
@result{} (905595714000000 . 1000000)
(float-time '(905595714000000 . 1000000))
@result{} 905595714.0
......@@ -1627,7 +1623,7 @@ These are the functions available:
Take a date and return a time.
@item float-time
Take a time and return seconds. (This is a built-in function.)
Take a time and return seconds.
@item encode-time
Take seconds (and other ways to represent time, notably decoded time
......
......@@ -138,7 +138,7 @@ well as variants like \"2008W32\" (week number) and
date)))
(defun iso8601-parse-date (string)
"Parse STRING (which should be on ISO 8601 format) and return a time value."
"Parse STRING (in ISO 8601 format) and return a decoded time value."
(cond
;; Just a year: [-+]YYYY.
((iso8601--match iso8601--year-match string)
......
......@@ -374,8 +374,8 @@ January 1st being 1."
(defun decoded-time-add (time delta)
"Add DELTA to TIME, both of which are `decoded-time' structures.
TIME should represent a time, while DELTA should only have
non-nil integers for the values that should be altered.
TIME should represent a time, while DELTA should have non-nil
entries only for the values that should be altered.
For instance, if you want to \"add two months\" to TIME, then
leave all other fields but the month field in DELTA nil, and make
......
......@@ -1278,27 +1278,27 @@ all. This may very well take some time.")
(cond ((eq (cdr reminder) 'minute)
(time-subtract
(apply #'encode-time 0 (nthcdr 1 date-elts))
(encode-time (* (car reminder) 60.0))))
(* (car reminder) 60)))
((eq (cdr reminder) 'hour)
(time-subtract
(apply #'encode-time 0 0 (nthcdr 2 date-elts))
(encode-time (* (car reminder) 3600.0))))
(* (car reminder) 3600)))
((eq (cdr reminder) 'day)
(time-subtract
(apply #'encode-time 0 0 0 (nthcdr 3 date-elts))
(encode-time (* (car reminder) 86400.0))))
(* (car reminder) 86400)))
((eq (cdr reminder) 'week)
(time-subtract
(apply #'encode-time 0 0 0 monday (nthcdr 4 date-elts))
(encode-time (* (car reminder) 604800.0))))
(* (car reminder) 604800)))
((eq (cdr reminder) 'month)
(time-subtract
(apply #'encode-time 0 0 0 1 (nthcdr 4 date-elts))
(encode-time (* (car reminder) 18748800.0))))
(* (car reminder) 18748800)))
((eq (cdr reminder) 'year)
(time-subtract
(apply #'encode-time 0 0 0 1 1 (nthcdr 5 date-elts))
(encode-time (* (car reminder) 400861056.0)))))
(* (car reminder) 400861056))))
res))
(sort res 'time-less-p)))
......
......@@ -636,6 +636,7 @@ disallows them."
(error "Invalid or unsupported time: %s" date-time-string))
;; Return a value in a format similar to that returned by decode-time, and
;; suitable for (apply #'encode-time ...).
;; FIXME: Nobody uses this idiosyncratic value. Perhaps stop returning it?
(list second minute hour day month year second-fraction datatype
(if has-time-zone
(* (rng-xsd-time-to-seconds
......
......@@ -412,9 +412,12 @@ The input I may be a character, or a single-letter string."
r))
(defun org-id-time-to-b36 (&optional time)
"Encode TIME as a 10-digit string.
"Encode TIME as a 12-digit string.
This string holds the time to micro-second accuracy, and can be decoded
using `org-id-decode'."
;; FIXME: If TIME represents N seconds after the epoch, then
;; this encoding assumes 0 <= N < 110075314176 = (* (expt 36 4) 65536),
;; i.e., that TIME is from 1970-01-01 00:00:00 to 5458-02-23 20:09:36 UTC.
(setq time (encode-time time 'list))
(concat (org-id-int-to-b36 (nth 0 time) 4)
(org-id-int-to-b36 (nth 1 time) 4)
......@@ -423,7 +426,7 @@ using `org-id-decode'."
(defun org-id-decode (id)
"Split ID into the prefix and the time value that was used to create it.
The return value is (prefix . time) where PREFIX is nil or a string,
and time is the usual three-integer representation of time."
and TIME is a Lisp time value (HI LO USEC)."
(let (prefix time parts)
(setq parts (org-split-string id ":"))
(if (= 2 (length parts))
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment