[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)