From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#32902: Add support for (TIMESTAMP . RESOLUTION) Lisp timestamps Date: Tue, 02 Oct 2018 06:04:07 +0300 Message-ID: <83y3bh2gns.fsf@gnu.org> References: NNTP-Posting-Host: blaine.gmane.org X-Trace: blaine.gmane.org 1538449389 16957 195.159.176.226 (2 Oct 2018 03:03:09 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Tue, 2 Oct 2018 03:03:09 +0000 (UTC) Cc: 32902@debbugs.gnu.org To: Paul Eggert Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Tue Oct 02 05:03:04 2018 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1g7Axk-0004Hk-FV for geb-bug-gnu-emacs@m.gmane.org; Tue, 02 Oct 2018 05:03:04 +0200 Original-Received: from localhost ([::1]:41536 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1g7Azr-0004mX-15 for geb-bug-gnu-emacs@m.gmane.org; Mon, 01 Oct 2018 23:05:15 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:47339) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1g7Azl-0004k2-0V for bug-gnu-emacs@gnu.org; Mon, 01 Oct 2018 23:05:09 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1g7Azf-00017w-4N for bug-gnu-emacs@gnu.org; Mon, 01 Oct 2018 23:05:08 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:57622) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1g7Aze-00017d-8Z for bug-gnu-emacs@gnu.org; Mon, 01 Oct 2018 23:05:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1g7Azd-0001N8-V2 for bug-gnu-emacs@gnu.org; Mon, 01 Oct 2018 23:05:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 02 Oct 2018 03:05:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 32902 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 32902-submit@debbugs.gnu.org id=B32902.15384494745229 (code B ref 32902); Tue, 02 Oct 2018 03:05:01 +0000 Original-Received: (at 32902) by debbugs.gnu.org; 2 Oct 2018 03:04:34 +0000 Original-Received: from localhost ([127.0.0.1]:33647 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1g7AzB-0001MG-Pv for submit@debbugs.gnu.org; Mon, 01 Oct 2018 23:04:34 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:37544) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1g7Az9-0001M0-E1 for 32902@debbugs.gnu.org; Mon, 01 Oct 2018 23:04:31 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1g7Ayx-0000ok-06 for 32902@debbugs.gnu.org; Mon, 01 Oct 2018 23:04:24 -0400 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:41550) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1g7Ayw-0000oX-EL; Mon, 01 Oct 2018 23:04:18 -0400 Original-Received: from [176.228.60.248] (port=3218 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1g7Ayr-0007Ba-HP; Mon, 01 Oct 2018 23:04:15 -0400 In-reply-to: (message from Paul Eggert on Mon, 1 Oct 2018 18:00:26 -0700) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 208.118.235.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:150896 Archived-At: > From: Paul Eggert > Date: Mon, 1 Oct 2018 18:00:26 -0700 > > The attached patches follow up on a suggestion by Stefan a few weeks > ago, by adding support for a new Lisp timestamp format (TIMESTAMP . > FREQUENCY), where TIMESTAMP is an integer that counts clock ticks and > FREQUENCY is a positive integer that counts ticks per second. For > brevity the documentation says (TICKS . HZ) instead of (TIMESTAMP . > FREQUENCY). Thanks for working on this. I'd prefer not to move stuff from editfns.c to a new file, as that makes forensics significantly harder. Is it feasible to leave the time-related code in editfns.c? > DEFUN ("current-time", Fcurrent_time, Scurrent_time, 0, 0, 0, > - doc: /* Return the current time, as the number of seconds since 1970-01-01 00:00:00. > -The time is returned as a list of integers (HIGH LOW USEC PSEC). > -HIGH has the most significant bits of the seconds, while LOW has the > -least significant 16 bits. USEC and PSEC are the microsecond and > -picosecond counts. */) > + doc: /* Return the current time, counting the number of seconds since the epoch. > + > +See Info node `(elisp)Time of Day' for the format of the returned > +timestamp. Although this is currently list format, it may change in > +future versions of Emacs. Use `encode-time' if you need a particular > +form; for example, (encode-time nil \\='list) returns the current time > +in list form. */) I think this obfuscation of the time values in doc strings (here and elsewhere in the patch) is not a good idea, and asking users to read the manual just to understand what kind of data they will get or need to pass to a function, is a step backwards. Doc strings only send to the manuals for additional details and explanations, not for the basic facts such as these. The manual and NEWS can (and probably should) explain that this stuff is in transition, but we shouldn't describe return values as opaque objects because of that. IMO, this is not the Emacsy way of dealing with complex data structures. I also don't like saying in a doc string that something might change in a future version: that's stuff for the manual. Doc strings should describe the current state of affairs. > +If TIME is a list (SECOND MINUTE HOUR DAY MONTH YEAR IGNORED DST ZONE) > +it a decoded time in the style of `decode-time', so that (encode-time ^^ A typo: should be "it is" or "it's". > +If FORM is a positive integer, the time is returned as a pair of > +integers (TICKS . FORM), where TICKS is the number of clock ticks and FORM > +is the clock frequency in ticks per second. (Currently the positive > +integer should be at least 65536 if the returned value is expected to > +be given to standard functions expecting Lisp timestamps.) If FORM is > +t, the time is returned as (TICKS . PHZ), where PHZ is a > +platform-dependent clock frequency. This doesn't tell in what units the clock frequency is returned. > -usage: (encode-time SECOND MINUTE HOUR DAY MONTH YEAR &optional ZONE) */) > +usage: (encode-time TIME &optional FORM) */) This makes an impression the function doesn't support more than 2 arguments, which is incorrect. Can we provide a more accurate 'usage' form? I think it would be good to add tests for the functions being modified, otherwise we might be breaking something without paying attention.