[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
master 7a828c938ca: Document time-parsing functions a bit better
From: |
Paul Eggert |
Subject: |
master 7a828c938ca: Document time-parsing functions a bit better |
Date: |
Mon, 12 Aug 2024 17:52:42 -0400 (EDT) |
branch: master
commit 7a828c938ca9daf37baa02a50bb6463e2b7c0b85
Author: Paul Eggert <eggert@cs.ucla.edu>
Commit: Paul Eggert <eggert@cs.ucla.edu>
Document time-parsing functions a bit better
See <https://bugs.gnu.org/72570#14>
---
doc/lispref/os.texi | 26 +++++++++++++++++++-------
lisp/calendar/iso8601.el | 10 +++++-----
lisp/calendar/parse-time.el | 5 ++---
3 files changed, 26 insertions(+), 15 deletions(-)
diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index 3ba3da459bf..5839de4a650 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -1800,19 +1800,31 @@ structure (@pxref{Time Conversion}). The argument
@var{string} should
resemble an RFC 822 (or later) 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.
+It parses an incomplete string like ``2024-08-13'' to an incomplete
+structure like @samp{(nil nil nil 13 8 2024 nil -1 nil)}, in which
+an unknown DST value is @minus{}1 and other unknown values are @code{nil}.
@end defun
@vindex ISO 8601 date/time strings
@defun iso8601-parse string
-For a more strict function (that will error out upon invalid input),
-this function can be used instead. It can parse all variants of
+This function acts like @code{parse-time-string} except it is stricter
+and errors out upon invalid input. It can parse all variants of
the ISO 8601 standard, so in addition to the formats mentioned above,
it also parses things like ``1998W45-3'' (week number) and
-``1998-245'' (ordinal day number). To parse durations, there's
-@code{iso8601-parse-duration}, and to parse intervals, there's
-@code{iso8601-parse-interval}. All these functions return decoded
-time structures, except the final one, which returns three of them
-(the start, the end, and the duration).
+``1998-245'' (ordinal day number).
+@end defun
+
+@defun iso8601-parse-duration string
+This function parses an ISO 8601 time duration @var{string}
+and returns a decoded time structure.
+@c FIXME: example? behavior on incomplete input?
+@end defun
+
+@defun iso8601-parse-interval string
+This function parses an ISO 8601 time interval @var{string}
+and returns three decoded time structures
+representing the start, the end, and the duration.
+@c FIXME: example? behavior on incomplete input?
@end defun
@defun format-time-string format-string &optional time zone
diff --git a/lisp/calendar/iso8601.el b/lisp/calendar/iso8601.el
index a32b52564c9..a31b60eaec2 100644
--- a/lisp/calendar/iso8601.el
+++ b/lisp/calendar/iso8601.el
@@ -121,11 +121,11 @@
(defun iso8601-parse (string &optional form)
"Parse an ISO 8601 date/time string and return a `decode-time' structure.
-
-The ISO 8601 date/time strings look like \"2008-03-02T13:47:30\",
-but shorter, incomplete strings like \"2008-03-02\" are valid, as
-well as variants like \"2008W32\" (week number) and
-\"2008-234\" (ordinal day number).
+ISO 8601 date/time strings look like \"2008-03-02T13:47:30+05:30\",
+or like shorter, incomplete strings like date \"2008-03-02\",
+week number \"2008W32\", and ordinal day number \"2008-234\".
+Values returned are identical to those of `decode-time', except
+that an unknown DST value is -1 and other unknown values are nil.
See `decode-time' for the meaning of FORM."
(if (not (iso8601-valid-p string))
diff --git a/lisp/calendar/parse-time.el b/lisp/calendar/parse-time.el
index c34329a4002..9538ea92ee5 100644
--- a/lisp/calendar/parse-time.el
+++ b/lisp/calendar/parse-time.el
@@ -154,9 +154,8 @@ or something resembling an RFC 822 (or later) date-time,
e.g.,
\"Wed, 15 Jan 2020 16:12:21 -0800\". This function is
somewhat liberal in what format it accepts, and will attempt to
return a \"likely\" value even for somewhat malformed strings.
-The values returned are identical to those of `decode-time', but
-any unknown values other than DST are returned as nil, and an
-unknown DST value is returned as -1.
+Values returned are identical to those of `decode-time', except
+that an unknown DST value is -1 and other unknown values are nil.
See `decode-time' for the meaning of FORM."
(condition-case ()
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- master 7a828c938ca: Document time-parsing functions a bit better,
Paul Eggert <=