[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
master 6db5c7f8c4: Improve time parsing documentation
From: |
Lars Ingebrigtsen |
Subject: |
master 6db5c7f8c4: Improve time parsing documentation |
Date: |
Fri, 17 Jun 2022 10:05:44 -0400 (EDT) |
branch: master
commit 6db5c7f8c47590269d196a329eab727228b9be19
Author: Lars Ingebrigtsen <larsi@gnus.org>
Commit: Lars Ingebrigtsen <larsi@gnus.org>
Improve time parsing documentation
* doc/lispref/os.texi (Time Parsing): Clarify which functions
take/return timestamps and which ones take decoded time structures.
* src/timefns.c (Fdecode_time): Clarify TIME argument (bug#46505).
---
doc/lispref/os.texi | 38 ++++++++++++++------------------------
src/timefns.c | 2 +-
2 files changed, 15 insertions(+), 25 deletions(-)
diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index 11a0d02338..bc5374f10f 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -1754,9 +1754,10 @@ at the 15th of the month when adding months.
Alternatively, you can use the
@cindex time formatting
@cindex formatting time values
- These functions convert time values to text in a string, and vice versa.
-Time values include @code{nil}, finite numbers, and Lisp timestamps
-(@pxref{Time of Day}).
+ These functions convert time values to text in a string, and vice
+versa. Time values are either represented as a Lisp timestamp
+(@pxref{Time of Day}) or a decoded time structure (@pxref{Time
+Conversion}).
@defun date-to-time string
This function parses the time-string @var{string} and returns the
@@ -1769,22 +1770,11 @@ The operating system limits the range of time and zone
values.
@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
-@code{dst} element that cannot be determined from the input is set to
-@minus{}1, and any other unknown element is set to
-@code{nil}. 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.
+This function parses the time-string @var{string} into a decoded time
+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.
@end defun
@vindex ISO 8601 date/time strings
@@ -1801,11 +1791,11 @@ time structures, except the final one, which returns
three of them
@end defun
@defun format-time-string format-string &optional time zone
-
-This function converts @var{time} (or the current time, if
-@var{time} is omitted or @code{nil}) to a string according to
-@var{format-string}. The conversion uses the time zone rule @var{zone}, which
-defaults to the current time zone rule. @xref{Time Zone Rules}. The argument
+This function converts @var{time} (which should be a Lisp timestamp,
+and defaults to the current time if @var{time} is omitted or
+@code{nil}) to a string according to @var{format-string}. The
+conversion uses the time zone rule @var{zone}, which defaults to the
+current time zone rule. @xref{Time Zone Rules}. The argument
@var{format-string} may contain @samp{%}-sequences which say to
substitute parts of the time. Here is a table of what the
@samp{%}-sequences mean:
diff --git a/src/timefns.c b/src/timefns.c
index 13a84f6b3c..9df50eaecc 100644
--- a/src/timefns.c
+++ b/src/timefns.c
@@ -1463,7 +1463,7 @@ usage: (format-time-string FORMAT-STRING &optional TIME
ZONE) */)
}
DEFUN ("decode-time", Fdecode_time, Sdecode_time, 0, 3, 0,
- doc: /* Decode a time value as (SEC MINUTE HOUR DAY MONTH YEAR DOW DST
UTCOFF).
+ doc: /* Decode a timestamp into (SEC MINUTE HOUR DAY MONTH YEAR DOW DST
UTCOFF).
The optional TIME is the time value to convert. See
`format-time-string' for the various forms of a time value.
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- master 6db5c7f8c4: Improve time parsing documentation,
Lars Ingebrigtsen <=