From b8c70172f354ad57bb6c547d59f585d751f632ed Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Fri, 8 Feb 2019 10:33:13 +0200 Subject: [PATCH] Improve documentation of 'date-to-time' and 'parse-time-string' * doc/lispref/os.texi (Time Parsing): Document 'parse-time-string', and refer to it for the description of the argument of 'date-to-time'. * lisp/calendar/time-date.el (date-to-time): Refer in the doc string to 'parse-time-string' for more information about the format of the DATE argument. (Bug#34303) --- doc/lispref/os.texi | 23 ++++++++++++++++++++++- lisp/calendar/time-date.el | 1 + 2 files changed, 23 insertions(+), 1 deletion(-) diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi index 65c57064a3d..2f3e91ce68c 100644 --- a/doc/lispref/os.texi +++ b/doc/lispref/os.texi @@ -1467,7 +1467,28 @@ integers (@pxref{Time of Day}). @defun date-to-time string This function parses the time-string @var{string} and returns the -corresponding time value. +corresponding time value. The argument @var{string} should represent +a date-time, and should be in one of the forms recognized by +@code{parse-time-string} (see below). This function assumes the GMT +timezone if @var{string} lacks an explicit timezone information. +@end defun + +@defun parse-time-string string +This function parses the time-string @var{string} into a list of the +following form: + +@example +(@var{sec} @var{min} @var{hour} @var{day} @var{mon} @var{year} @var{dow} @var{dst} @var{tz}) +@end example + +@noindent +The format of this list is the same as what @code{decode-time} accepts +(@pxref{Time Conversion}), and is described in more detail there. Any +element that cannot be determined from the input will be set to +@code{nil}. The argument @var{string} should resemble an RFC 2822 or +ISO 8601 string, like ``Fri, 25 Mar 2016 16:24:56 +0100'' or +``1998-09-12T12:21:54-0200'', but this function will attempt to parse +less well-formed time strings as well. @end defun @defun format-time-string format-string &optional time zone diff --git a/lisp/calendar/time-date.el b/lisp/calendar/time-date.el index 6988e65dddc..afd5c091b40 100644 --- a/lisp/calendar/time-date.el +++ b/lisp/calendar/time-date.el @@ -148,6 +148,7 @@ it is assumed that PICO was omitted and should be treated as zero." ;; values. timezone-make-date-arpa-standard should help. (defun date-to-time (date) "Parse a string DATE that represents a date-time and return a time value. +DATE should be in one of the forms recognized by `parse-time-string'. If DATE lacks timezone information, GMT is assumed." (condition-case err (apply 'encode-time (parse-time-string date)) -- 2.39.5