[PATCH] Add a new function to convert a time value to the canonical format.

[PATCH] Add a new function to convert a time value to the canonical format.

[Philipp Stephani]

Such a function is useful for users that want to do their own time
calculations and conversions.

* src/timefns.c (Ftime_canonicalize): New defun.

* test/src/timefns-tests.el (time-canonicalize): New unit test.
---
 src/timefns.c             | 12 ++++++++++++
 test/src/timefns-tests.el | 10 ++++++++++
 2 files changed, 22 insertions(+)

diff --git a/src/timefns.c b/src/timefns.c
index cb953d1b4c..632d6c6d64 100644
--- a/src/timefns.c
+++ b/src/timefns.c
@@ -958,6 +958,17 @@ lisp_seconds_argument (Lisp_Object specified_time)
   return t.tv_sec;
 }
 
+DEFUN ("time-canonicalize", Ftime_canonicalize, Stime_canonicalize, 1, 1, NULL,
+       doc: /* Return canonical form of TIME as pair (TICKS . HZ).
+TIME can be any time value.  See Info node `(elisp)Time of Day'.  The
+return value is a pair (TICKS . HZ).  TICKS / HZ is the time value in
+seconds.  */)
+  (Lisp_Object time)
+{
+  struct lisp_time lt = lisp_time_struct (time, NULL);
+  return Fcons (lt.ticks, lt.hz);
+}
+
 /* Given Lisp operands A and B, add their values, and return the
    result as a Lisp timestamp that is in (TICKS . HZ) form if either A
    or B are in that form, (HI LO US PS) form otherwise.  Subtract
@@ -1764,6 +1775,7 @@ syms_of_timefns (void)
   DEFSYM (Qencode_time, "encode-time");
 
   defsubr (&Scurrent_time);
+  defsubr (&Stime_canonicalize);
   defsubr (&Stime_add);
   defsubr (&Stime_subtract);
   defsubr (&Stime_less_p);
diff --git a/test/src/timefns-tests.el b/test/src/timefns-tests.el
index 5c858ef3bd..e681b17a3c 100644
--- a/test/src/timefns-tests.el
+++ b/test/src/timefns-tests.el
@@ -17,6 +17,7 @@
 ;; You should have received a copy of the GNU General Public License
 ;; along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
+(require 'cl-lib)
 (require 'ert)
 
 ;;; Check format-time-string and decode-time with various TZ settings.
@@ -142,3 +143,12 @@ timefns-tests--have-leap-seconds
 		      (< 0.99 (/ x y) 1.01)
 		      (< 0.99 (/ (- (float-time a)) (float-time b))
 			 1.01))))))))
+
+(ert-deftest time-canonicalize ()
+  (dolist (time '(123.45 (123 . 1000000) (1 2) (1 2 3) (1 2 3 4)))
+    (ert-info ((prin1-to-string `(time-canonicalize ,time)))
+      (let ((result (time-canonicalize time)))
+        (should (consp result))
+        (should (integerp (car result)))
+        (should (integerp (cdr result)))
+        (should (cl-plusp (cdr result)))))))
-- 
2.20.1 (Apple Git-117)

Re: [PATCH] Add a new function to convert a time value to the canonical format.

[Eli Zaretskii]

> From: Philipp Stephani <p.stephani2@gmail.com>
> Date: Tue, 23 Apr 2019 14:46:13 +0200
> Cc: Philipp Stephani <phst@google.com>
> 
> Such a function is useful for users that want to do their own time
> calculations and conversions.
> 
> * src/timefns.c (Ftime_canonicalize): New defun.
> 
> * test/src/timefns-tests.el (time-canonicalize): New unit test.

Please include documentation of this.

Thanks.

Re: [PATCH] Add a new function to convert a time value to the canonical format.

[Philipp Stephani]

Am Di., 23. Apr. 2019 um 15:11 Uhr schrieb Eli Zaretskii <eliz@gnu.org>:
>
> > From: Philipp Stephani <p.stephani2@gmail.com>
> > Date: Tue, 23 Apr 2019 14:46:13 +0200
> > Cc: Philipp Stephani <phst@google.com>
> >
> > Such a function is useful for users that want to do their own time
> > calculations and conversions.
> >
> > * src/timefns.c (Ftime_canonicalize): New defun.
> >
> > * test/src/timefns-tests.el (time-canonicalize): New unit test.
>
> Please include documentation of this.

Actually it seems superfluous because (encode-time timeval t) does the
same. I guess we don't need this any more. Sorry for the noise.

Re: [PATCH] Add a new function to convert a time value to the canonical format.

[Eli Zaretskii]

> From: Philipp Stephani <p.stephani2@gmail.com>
> Date: Tue, 23 Apr 2019 15:13:17 +0200
> Cc: Philipp Stephani <phst@google.com>, Emacs developers <emacs-devel@gnu.org>
> 
> Actually it seems superfluous because (encode-time timeval t) does the
> same. I guess we don't need this any more. Sorry for the noise.

No need to apologize.

How about a patch for the ELisp manual to mention this use case?
Would that be useful?

Re: [PATCH] Add a new function to convert a time value to the canonical format.

[Paul Eggert]

On 4/23/19 6:21 AM, Eli Zaretskii wrote:
> No need to apologize.
>
> How about a patch for the ELisp manual to mention this use case?

The manual already says this:

You can convert a time value into
a human-readable string using @code{format-time-string}, into a Lisp
timestamp using @code{encode-time}, and into other forms using
@code{decode-time} and @code{float-time}.

Re: [PATCH] Add a new function to convert a time value to the canonical format.

[Eli Zaretskii]

> From: Paul Eggert <eggert@cs.ucla.edu>
> Date: Tue, 23 Apr 2019 09:20:34 -0700
> Cc: phst@google.com, emacs-devel@gnu.org
> 
> On 4/23/19 6:21 AM, Eli Zaretskii wrote:
> > No need to apologize.
> >
> > How about a patch for the ELisp manual to mention this use case?
> 
> The manual already says this:
> 
> You can convert a time value into
> a human-readable string using @code{format-time-string}, into a Lisp
> timestamp using @code{encode-time}, and into other forms using
> @code{decode-time} and @code{float-time}.

I guess I misunderstood what TIMEVAL stood for in (encode-time timeval t).