master 4a1f69ebca 2/2: Use (TICKS . HZ) for current-time etc.

[Paul Eggert]

branch: master
commit 4a1f69ebca9bbf5797b8898f8250f6580753d829
Author: Paul Eggert <eggert@cs.ucla.edu>
Commit: Paul Eggert <eggert@cs.ucla.edu>

    Use (TICKS . HZ) for current-time etc.
    
    * src/timefns.c (CURRENT_TIME_LIST): Change default to false.
    All documentation changed.
---
 doc/lispintro/emacs-lisp-intro.texi |  6 +++---
 doc/lispref/files.texi              | 14 +++++++-------
 doc/lispref/intro.texi              |  2 +-
 doc/lispref/os.texi                 | 15 +++++++--------
 etc/NEWS                            |  8 ++++++++
 src/timefns.c                       | 26 ++++++++++++--------------
 6 files changed, 38 insertions(+), 33 deletions(-)

diff --git a/doc/lispintro/emacs-lisp-intro.texi 
b/doc/lispintro/emacs-lisp-intro.texi
index 466d7f0e60..afaed10cdf 100644
--- a/doc/lispintro/emacs-lisp-intro.texi
+++ b/doc/lispintro/emacs-lisp-intro.texi
@@ -15343,9 +15343,9 @@ nil
 100
 @end group
 @group
-(20615 27034 579989 697000)
-(17905 55681 0 0)
-(20615 26327 734791 805000)
+(1351051674579989697 . 1000000000)
+(1173477761000000000 . 1000000000)
+(1351050967734791805 . 1000000000)
 13188
 "-rw-r--r--"
 @end group
diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index d8b55b114a..4394f64a32 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -1423,9 +1423,9 @@ For example, here are the file attributes for 
@file{files.texi}:
 @group
 (file-attributes "files.texi" 'string)
      @result{}  (nil 1 "lh" "users"
-          (20614 64019 50040 152000)
-          (20000 23 0 0)
-          (20614 64555 902289 872000)
+          (1351023123050040152 . 1000000000)
+          (1310720023000000000 . 1000000000)
+          (1351023659902289872 . 1000000000)
           122295 "-rw-rw-rw-"
           t 6473924464520138
           1014478468)
@@ -1449,13 +1449,13 @@ is owned by the user with name @samp{lh}.
 @item "users"
 is in the group with name @samp{users}.
 
-@item (20614 64019 50040 152000)
+@item (1351023123050040152 . 1000000000)
 was last accessed on October 23, 2012, at 20:12:03.050040152 UTC.
 
-@item (20000 23 0 0)
-was last modified on July 15, 2001, at 08:53:43 UTC.
+@item (1310720023000000000 . 1000000000)
+was last modified on July 15, 2001, at 08:53:43.000000000 UTC.
 
-@item (20614 64555 902289 872000)
+@item (1351023659902289872 . 1000000000)
 last had its status changed on October 23, 2012, at 20:20:59.902289872 UTC.
 
 @item 122295
diff --git a/doc/lispref/intro.texi b/doc/lispref/intro.texi
index 5afd2f4ecf..d1a3fef7a4 100644
--- a/doc/lispref/intro.texi
+++ b/doc/lispref/intro.texi
@@ -503,7 +503,7 @@ if the information is not available.
 @example
 @group
 emacs-build-time
-     @result{} (20614 63694 515336 438000)
+     @result{} (1650228902637038831 . 1000000000)
 @end group
 @end example
 @end defvar
diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index af9ad0a533..9e87b3840e 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -1359,9 +1359,6 @@ This represents the number of seconds using the formula:
 @tex
 $high \times 2^{16} + low + micro \times 10^{-6} + pico \times 10^{-12}$.
 @end tex
-In some cases, functions may default to returning two- or
-three-element lists, with omitted @var{micro} and @var{pico}
-components defaulting to zero.
 On all current machines @var{pico} is a multiple of 1000, but this
 may change as higher-resolution clocks become available.
 @end itemize
@@ -1415,11 +1412,13 @@ The operating system limits the range of time and zone 
values.
 
 @defun current-time
 This function returns the current time as a Lisp timestamp.
-Although the timestamp takes the form @code{(@var{high} @var{low}
-@var{micro} @var{pico})} in the current Emacs release, this is
-planned to change in a future Emacs version.  You can use the
-@code{time-convert} function to convert a timestamp to some other
-form.  @xref{Time Conversion}.
+The timestamp has the form @code{(@var{ticks} . @var{hz})} where
+@var{ticks} counts clock ticks and @var{hz} is the clock ticks per second.
+
+In Emacs 28 and earlier, the returned timestamp had the list form
+@code{(@var{high} @var{low} @var{usec} @var{psec})}.  You can use
+@code{(time-convert nil 'list)} to return the current time in this
+older form.  @xref{Time Conversion}.
 @end defun
 
 @defun float-time &optional time
diff --git a/etc/NEWS b/etc/NEWS
index 05c636102d..40e914cd32 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -202,6 +202,14 @@ speakers of the Tamil language.  To get back the previous 
behavior,
 use the new 'tamil-itrans-digits' and 'tamil-inscript-digits' input
 methods instead.
 
++++
+** current-time and related functions now yield (TICKS . HZ) timestamps.
+Previously they yielded timestamps of the forms (HI LO US PS), (HI LO
+US) or (HI LO), which were less regular and less efficient and which
+lacked information about clock resolution.  This long-planned change
+was documented in Emacs 27.  To convert a timestamp X to the old
+4-element list form, you can use (time-convert X 'list).
+
 
 * Changes in Emacs 29.1
 
diff --git a/src/timefns.c b/src/timefns.c
index b0b84a438c..e7a2cd368e 100644
--- a/src/timefns.c
+++ b/src/timefns.c
@@ -69,12 +69,11 @@ enum { TM_YEAR_BASE = 1900 };
 # define FASTER_TIMEFNS 1
 #endif
 
-/* Although current-time etc. generate list-format timestamps
-   (HI LO US PS), the plan is to change these functions to generate
-   frequency-based timestamps (TICKS . HZ) in a future release.
-   To try this now, compile with -DCURRENT_TIME_LIST=0.  */
+/* current-time etc. generate (TICKS . HZ) timestamps.
+   To change that to the old 4-element list format (HI LO US PS),
+   compile with -DCURRENT_TIME_LIST=1.  */
 #ifndef CURRENT_TIME_LIST
-enum { CURRENT_TIME_LIST = true };
+enum { CURRENT_TIME_LIST = false };
 #endif
 
 #if FIXNUM_OVERFLOW_P (1000000000)
@@ -1763,15 +1762,14 @@ bits, and USEC and PSEC are the microsecond and 
picosecond counts.  */)
 
 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.
-
-In a future Emacs version, the format of the returned timestamp is
-planned to change.  Use `time-convert' if you need a particular
-timestamp form; for example, (time-convert nil \\='integer) returns
-the current time in seconds.  */)
+The time is returned as a pair of integers (TICKS . HZ), where TICKS
+counts clock ticks and HZ is the clock ticks per second.
+
+In Emacs 28 and earlier, the returned timestamp had the form (HIGH LOW
+USEC PSEC), where HIGH is the most significant bits of the seconds,
+LOW the least significant 16 bits, and USEC and PSEC are the
+microsecond and picosecond counts.  Use \(time-convert nil \\='list)
+if you need this older timestamp form.  */)
   (void)
 {
   return make_lisp_time (current_timespec ());