From: Max Nikulin <manikulin@gmail.com>
To: Paul Eggert <eggert@cs.ucla.edu>, 54764@debbugs.gnu.org
Cc: emacs-orgmode@gnu.org
Subject: Re: bug#54764: encode-time: make DST and TIMEZONE fields of the list argument optional ones
Date: Sat, 16 Apr 2022 23:26:24 +0700 [thread overview]
Message-ID: <2d57e59b-f971-483b-ad65-e0c5ff7883e8@gmail.com> (raw)
In-Reply-To: <149de00f-115b-5367-414f-c7700ef8966b@cs.ucla.edu>
[-- Attachment #1: Type: text/plain, Size: 501 bytes --]
On 09/04/2022 14:52, Paul Eggert wrote:
> On 4/7/22 05:37, Max Nikulin wrote:
>
>> Daylight saving time field matters only as a list component and
>> ignored as a separate argument (by the way, it should be stressed in
>> the docstring).
>
> Do you have a wording suggestion? (The doc string already covers the
> topic concisely; however, conciseness is not always a virtue. :-)
Feel free to shorten the added fragment, to change the wording, or to
use your variant instead. See the attachment.
[-- Attachment #2: 0001-Stress-difference-of-new-and-old-ways-to-call-encode.patch --]
[-- Type: text/x-patch, Size: 3304 bytes --]
From 42a20494e9f1461f7166c922452028548796bd16 Mon Sep 17 00:00:00 2001
From: Max Nikulin <manikulin@gmail.com>
Date: Sat, 16 Apr 2022 23:19:10 +0700
Subject: [PATCH] Stress difference of new and old ways to call `encode-time'
* doc/lispref/os.texi (Time Conversion): Add a warning that blind
changing of code calling `encode-time' to use single list instead of
multiple values may cause deferred bugs since it is common to use nil
for ignored arguments such as DST in the old calling convention.
* src/timefns.c (encode-time): Mention the warning added to the elisp
reference in the docstring.
Refactoring related to `encode-time' caused (bug#54731), so it is better
to make apparent the difference between the recommended and the
obsolescent ways to call the function. More details concerning the
purpose and limitations of the DST field are added after discussion with
Paul Eggert in (bug#54764).
---
doc/lispref/os.texi | 19 +++++++++++++++++++
src/timefns.c | 4 ++++
2 files changed, 23 insertions(+)
diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index 4ee893f860..b7b41f97ab 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -1707,6 +1707,25 @@ the latter to the former as follows:
You can perform simple date arithmetic by using out-of-range values for
@var{seconds}, @var{minutes}, @var{hour}, @var{day}, and @var{month};
for example, day 0 means the day preceding the given month.
+
+The old and the new styles to call @code{encode-time} with the same
+values of time fields may give different results. While modernizing
+code that uses obsolescent calling convention, ensure that the list
+argument contains 9 elements. Pay special attention that the @code{dst}
+field does not use @code{nil} expecting that actual value will be
+guessed, pass @samp{-1} instead. During normalizing of values to
+correct state of daylight saving time users may get time shift and even
+wrong date. It may take months to discover such problem. When
+called with multiple arguments, the function ignores equivalent of the
+@code{dst} value and @samp{-1} is effectively used. The new way to call
+@code{encode-time} has an advantage that it is possible to resolve
+ambiguity around backward time shift by passing @code{nil} or @code{t}.
+Unfortunately there are enough cases across the world when a particular
+area is moved to another time zone with no change of daylight saving
+time state. @code{encode-time} may signal an error in response to
+@code{t} passed as @code{dst}. You have to pass @code{zone} explicitly
+as time offset in such case if default ambiguity resolution is not
+acceptable.
@end defun
@node Time Parsing
diff --git a/src/timefns.c b/src/timefns.c
index b061be0a78..9af89a512d 100644
--- a/src/timefns.c
+++ b/src/timefns.c
@@ -1631,6 +1631,10 @@ convention, DST and ZONE default to -1 and nil respectively.
Years before 1970 are not guaranteed to work. On some systems,
year values as low as 1901 do work.
+See Info node `(elisp)Time Conversion' for description of a pitfall
+that can be faced during migration from the obsolescent to the new
+calling convention due to unconscious usage of nil for the DST argument.
+
usage: (encode-time TIME &rest OBSOLESCENT-ARGUMENTS) */)
(ptrdiff_t nargs, Lisp_Object *args)
{
--
2.25.1
next prev parent reply other threads:[~2022-04-16 16:27 UTC|newest]
Thread overview: 39+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-04-07 12:37 Max Nikulin
2022-04-09 7:52 ` Paul Eggert
2022-04-10 3:57 ` Max Nikulin
2022-04-13 14:40 ` Max Nikulin
2022-04-13 18:35 ` Paul Eggert
2022-04-14 13:19 ` Max Nikulin
2022-04-14 22:46 ` Paul Eggert
2022-04-15 2:14 ` Tim Cross
2022-04-15 17:23 ` Max Nikulin
2022-04-16 19:23 ` Paul Eggert
2022-04-21 16:59 ` Max Nikulin
2022-04-19 2:02 ` Paul Eggert
2022-04-19 5:50 ` Eli Zaretskii
2022-04-19 22:22 ` Paul Eggert
2022-04-20 7:23 ` Eli Zaretskii
2022-04-20 18:19 ` Paul Eggert
2022-04-20 18:41 ` Eli Zaretskii
2022-04-20 19:01 ` Paul Eggert
2022-04-20 19:14 ` Eli Zaretskii
2022-04-20 19:23 ` Paul Eggert
2022-04-20 19:30 ` Eli Zaretskii
2022-04-21 0:11 ` Paul Eggert
2022-04-21 6:44 ` Eli Zaretskii
2022-04-21 23:56 ` Paul Eggert
2022-04-22 5:01 ` Eli Zaretskii
2022-04-23 14:35 ` Bernhard Voelker
2022-04-20 15:07 ` Max Nikulin
2022-04-20 18:29 ` Paul Eggert
2022-04-25 15:30 ` Max Nikulin
2022-04-25 15:37 ` Paul Eggert
2022-04-25 19:49 ` Paul Eggert
2022-04-30 11:22 ` Max Nikulin
2022-05-01 2:32 ` Paul Eggert
2022-05-01 17:15 ` Max Nikulin
2022-04-13 15:12 ` Max Nikulin
2022-04-16 16:26 ` Max Nikulin [this message]
2022-04-17 1:58 ` Paul Eggert
2022-04-20 16:56 ` Max Nikulin
2022-04-20 19:17 ` Paul Eggert
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=2d57e59b-f971-483b-ad65-e0c5ff7883e8@gmail.com \
--to=manikulin@gmail.com \
--cc=54764@debbugs.gnu.org \
--cc=eggert@cs.ucla.edu \
--cc=emacs-orgmode@gnu.org \
--subject='Re: bug#54764: encode-time: make DST and TIMEZONE fields of the list argument optional ones' \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Code repositories for project(s) associated with this inbox:
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).