bug#71573: [PATCH] seconds-to-string-approximate

bug#71573: [PATCH] seconds-to-string-approximate

[JD Smith]

[-- Attachment #1: Type: text/plain, Size: 827 bytes --]

A very useful and widely used time operation is to approximate a given delay or age (in seconds) using a human-readable unit — think "2 hours", "5 days",  "3 weeks", or "7 months".  We have `seconds-to-string', but it provides more precision than is often required, skips some meaningful "human readable" duration units like weeks and months, and uses abbreviated units exclusively.  

For those familiar with magit, the `magit--age' function has provided this capability for quite some time (e.g. for short commit age), and other packages have adapted it.  It would be useful to have a version in core.

This patch provides a `seconds-to-string-approximate' function based loosely on `magit--age' and `seconds-to-string'.  It allows using abbreviated or full units, and can optionally round to the nearest half-unit.


[-- Attachment #2: seconds-to-string-approximate.patch --]
[-- Type: application/octet-stream, Size: 2089 bytes --]

diff --git a/lisp/calendar/time-date.el b/lisp/calendar/time-date.el
index eca80f1e8b6..079001bafe2 100644
--- a/lisp/calendar/time-date.el
+++ b/lisp/calendar/time-date.el
@@ -420,6 +420,37 @@ seconds-to-string
                          (<= (car here) delay)))
              (concat (format "%.2f" (/ delay (car (cddr here)))) (cadr here))))))
 
+(defvar seconds-to-string-approximate
+  `(("Y" "year"   "years"   ,(round (* 60 60 24 365.2425)))
+    ("M" "month"  "months"  ,(round (* 60 60 24 30.436875)))
+    ("w" "week"   "weeks"   ,(* 60 60 24 7))
+    ("d" "day"    "days"    ,(* 60 60 24))
+    ("h" "hour"   "hours"   ,(* 60 60))
+    ("m" "minute" "minutes" 60)
+    ("s" "second" "seconds" 1))
+  "Formatting used by the function `seconds-to-string-approximate'.")
+;;;###autoload
+(defun seconds-to-string-approximate (delay &optional abbreviate half)
+  "Convert the time interval DELAY in seconds to a string approximation.
+Abbreviate the units if ABBREVIATE is non-nil.  If HALF is non-nil,
+round to the nearest half-unit, otherwise round to the nearest unit."
+  (cond ((> 0 delay)
+         (concat "-" (seconds-to-string-approximate (- delay) abbreviate half)))
+        ((= (round delay (if half 0.5 1.)) 0)
+         (format "0%s" (if abbreviate "s" " seconds")))
+        (t (let ((stsa seconds-to-string-approximate) here cnt)
+             (while (and (setq here (pop stsa)) stsa
+                         (< (/ delay (nth 3 here)) 1)))
+             (setq cnt (round (/ (float delay) (nth 3 here)) (if half 0.5 1.)))
+             (concat
+              (let ((c (if half (/ cnt 2) cnt)))
+                (if (> c 0) (number-to-string c) ""))
+              (if (and half (= (mod cnt 2) 1)) "½" "")
+              (if abbreviate "" " ")
+              (cond (abbreviate (car here))
+                    ((<= cnt (if half 2 1)) (nth 1 here))
+                    (t (nth 2 here))))))))
+
 (defun date-days-in-month (year month)
   "The number of days in MONTH in YEAR."
   (unless (and (numberp month) (<= 1 month 12))

bug#71573: [PATCH] seconds-to-string-approximate

[Eli Zaretskii]

merge 71573 71572
thanks

> Cc: Adam Porter <adam@alphapapa.net>, jonas@bernoul.li
> From: JD Smith <jdtsmith@gmail.com>
> Date: Sat, 15 Jun 2024 13:24:00 -0400
> A very useful and widely used time operation is to approximate a given delay or age (in seconds) using a human-readable unit — think "2 hours", "5 days",  "3 weeks", or "7 months".  We have `seconds-to-string', but it provides more precision than is often required, skips some meaningful "human readable" duration units like weeks and months, and uses abbreviated units exclusively.  
> 
> For those familiar with magit, the `magit--age' function has provided this capability for quite some time (e.g. for short commit age), and other packages have adapted it.  It would be useful to have a version in core.
> 
> This patch provides a `seconds-to-string-approximate' function based loosely on `magit--age' and `seconds-to-string'.  It allows using abbreviated or full units, and can optionally round to the nearest half-unit.

This is a duplicate of bug#71572, merging.

bug#71573: Related functions from ts.el

[Adam Porter]

Hi all,

FWIW, my ts.el timestamp library has the related functions
`ts-human-duration' and `ts-human-format-duration'.  See 
<https://github.com/alphapapa/ts.el/blob/552936017cfdec89f7fc20c254ae6b37c3f22c5b/ts.el#L440-L491> 
and code below.

They work a bit differently, but I've found them very useful in my other
Elisp projects, and my profiling has shown that they perform very well 
relative to, e.g. the existing `format-seconds' function in terms of 
runtime and GC (see benchmarks in source comments).

If any of the code in ts.el would be helpful, I'd be glad to contribute
it to Emacs (some discussion about upstreaming parts of ts.el has also 
been going on in other, Org-related contexts).

--Adam

Elisp follows:

(defun ts-human-duration (seconds)
   "Return plist describing duration SECONDS.
List includes years, days, hours, minutes, and seconds.  This is
a simple calculation that does not account for leap years, leap
seconds, etc."
   ;; TODO: Add weeks.
   (cl-macrolet ((dividef (place divisor)
                          ;; Divide PLACE by DIVISOR, set PLACE to the 
remainder, and return the quotient.
                          `(prog1 (/ ,place ,divisor)
                             (setf ,place (% ,place ,divisor)))))
     (let* ((seconds (floor seconds))
            (years (dividef seconds 31536000))
            (days (dividef seconds 86400))
            (hours (dividef seconds 3600))
            (minutes (dividef seconds 60)))
       (list :years years :days days :hours hours :minutes minutes 
:seconds seconds))))

;; See also the built-in function `format-seconds', which I seem to have
;; overlooked before writing this.  However, a quick benchmark, run
;; 100,000 times, shows that, when controllable formatting is not needed,
;; `ts-human-format-duration' is much faster and generates less garbage:

;; | Form                     | x faster than next | Total runtime | # 
of GCs | Total GC runtime |
;; 
|--------------------------+--------------------+---------------+----------+------------------|
;; | ts-human-format-duration | 5.82               |      0.832945 | 
    3 |         0.574929 |
;; | format-seconds           | slowest            |      4.848253 | 
   17 |         3.288799 |

(cl-defun ts-human-format-duration (seconds &optional abbreviate)
   "Return human-formatted string describing duration SECONDS.
If SECONDS is less than 1, returns \"0 seconds\".  If ABBREVIATE
is non-nil, return a shorter version, without spaces.  This is a
simple calculation that does not account for leap years, leap
seconds, etc."
   ;; FIXME: Doesn't work with negative values, even though 
`ts-human-duration' does.
   (if (< seconds 1)
       (if abbreviate "0s" "0 seconds")
     (cl-macrolet ((format> (place)
                            ;; When PLACE is greater than 0, return 
formatted string using its symbol name.
                            `(when (> ,place 0)
                               (format "%d%s%s" ,place
                                       (if abbreviate "" " ")
                                       (if abbreviate
                                           ,(substring (symbol-name 
place) 0 1)
                                         ,(symbol-name place)))))
                   (join-places (&rest places)
                                ;; Return string joining the names and 
values of PLACES.
                                `(->> (list ,@(cl-loop for place in places
                                                       collect `(format> 
,place)))
                                      -non-nil
                                      (s-join (if abbreviate "" ", ")))))
       (-let* (((&plist :years :days :hours :minutes :seconds) 
(ts-human-duration seconds)))
         (join-places years days hours minutes seconds)))))

bug#71572: [PATCH] seconds-to-string-approximate

[Eli Zaretskii]

> Cc: Adam Porter <adam@alphapapa.net>, jonas@bernoul.li
> From: JD Smith <jdtsmith@gmail.com>
> Date: Sat, 15 Jun 2024 13:24:00 -0400
> 
> A very useful and widely used time operation is to approximate a given delay or age (in seconds) using a human-readable unit — think "2 hours", "5 days",  "3 weeks", or "7 months".  We have `seconds-to-string', but it provides more precision than is often required, skips some meaningful "human readable" duration units like weeks and months, and uses abbreviated units exclusively.  
> 
> For those familiar with magit, the `magit--age' function has provided this capability for quite some time (e.g. for short commit age), and other packages have adapted it.  It would be useful to have a version in core.
> 
> This patch provides a `seconds-to-string-approximate' function based loosely on `magit--age' and `seconds-to-string'.  It allows using abbreviated or full units, and can optionally round to the nearest half-unit.

Paul, any comments to the patch?

bug#71573: Related functions from ts.el

[Stefan Kangas]

Adam Porter <adam@alphapapa.net> writes:

> ;; See also the built-in function `format-seconds', which I seem to have
> ;; overlooked before writing this.  However, a quick benchmark, run
> ;; 100,000 times, shows that, when controllable formatting is not needed,
> ;; `ts-human-format-duration' is much faster and generates less garbage:
>
> ;; | Form                     | x faster than next | Total runtime | #
> of GCs | Total GC runtime |
> ;;
> |--------------------------+--------------------+---------------+----------+------------------|
> ;; | ts-human-format-duration | 5.82               |      0.832945 |
>     3 |         0.574929 |
> ;; | format-seconds           | slowest            |      4.848253 |
>    17 |         3.288799 |

Is this used a lot in hot loops?  IOW, is it worth optimizing?

If yes, how about adding something like what you have as an optimization
to `format-seconds` for when the format is very simple?  Would that
remove the need for `ts-human-format-duration'?

bug#71573: Related functions from ts.el

[Adam Porter]

On 6/22/24 05:55, Stefan Kangas wrote:
> Adam Porter <adam@alphapapa.net> writes:
> 
>> ;; See also the built-in function `format-seconds', which I seem to have
>> ;; overlooked before writing this.  However, a quick benchmark, run
>> ;; 100,000 times, shows that, when controllable formatting is not needed,
>> ;; `ts-human-format-duration' is much faster and generates less garbage:
>>
>> ;; | Form                     | x faster than next | Total runtime | #
>> of GCs | Total GC runtime |
>> ;;
>> |--------------------------+--------------------+---------------+----------+------------------|
>> ;; | ts-human-format-duration | 5.82               |      0.832945 |
>>      3 |         0.574929 |
>> ;; | format-seconds           | slowest            |      4.848253 |
>>     17 |         3.288799 |
> 
> Is this used a lot in hot loops?  IOW, is it worth optimizing?

It can be.  Imagine formatting timestamps for thousands of items in a 
vtable.  And imagine that happening frequently, e.g. if the vtable is 
redrawn automatically to account for data having arrived over the network.

> If yes, how about adding something like what you have as an optimization
> to `format-seconds` for when the format is very simple?  Would that
> remove the need for `ts-human-format-duration'?

I don't know what form such an optimization would take.  Perhaps someone 
could profile it and optimize some hot spots in it, but I'll have to 
decline that to-do for now, as my list is much too long already.  :)

BTW, please note that I don't claim that ts-human-format-duration is 
superior to format-seconds, because the latter is different and has some 
additional features.  Rather, ts-human-format-duration is an alternative 
that can sometimes be worth using instead.  I present it as food for 
thought when considering to implement related functionality.

bug#71572: [PATCH] seconds-to-string-approximate

[Adam Porter]

May I also recommend that the function be benchmarked, and potentially 
that it be profiled and optimized if needed?  A function like this may 
be used on hundreds or even thousands of items in a single operation 
(e.g. formatting a long list of items into a vtable), so it's important 
that it not be too slow.  I don't think I've seen mention of performance 
yet (forgive me if I missed it).

bug#71572: [PATCH] seconds-to-string-approximate

[Paul Eggert]

On 6/22/24 04:45, Eli Zaretskii wrote:
>> Cc: Adam Porter <adam@alphapapa.net>, jonas@bernoul.li
>> From: JD Smith <jdtsmith@gmail.com>
>> Date: Sat, 15 Jun 2024 13:24:00 -0400
>>
>> A very useful and widely used time operation is to approximate a given delay or age (in seconds) using a human-readable unit — think "2 hours", "5 days",  "3 weeks", or "7 months".  We have `seconds-to-string', but it provides more precision than is often required, skips some meaningful "human readable" duration units like weeks and months, and uses abbreviated units exclusively.
>>
>> For those familiar with magit, the `magit--age' function has provided this capability for quite some time (e.g. for short commit age), and other packages have adapted it.  It would be useful to have a version in core.
>>
>> This patch provides a `seconds-to-string-approximate' function based loosely on `magit--age' and `seconds-to-string'.  It allows using abbreviated or full units, and can optionally round to the nearest half-unit.
> 
> Paul, any comments to the patch?

For starters:

Why define a new function, instead of adding optional arguments to the 
existing one?

Why not look at what mastodon.el does, as the comment in 
seconds-to-string suggests? For example, mastodon-tl--human-duration 
lets you specify whatever resolution you want, instead of limiting you 
to either 0.5 or 1  as in the proposed patch.

Isn't the master branch was in an long-term sort-of-frozen state, until 
a branch is created for Emacs 30? If so I imagine changes in this area 
should wait.

bug#71572: [PATCH] seconds-to-string-approximate

[JD Smith]

[-- Attachment #1: Type: text/plain, Size: 5234 bytes --]



> On Jun 22, 2024, at 7:42 PM, Paul Eggert <eggert@cs.ucla.edu> wrote:
> 
> On 6/22/24 04:45, Eli Zaretskii wrote:
>>> 
>> Paul, any comments to the patch?
> 
> For starters:

Thanks for the comment.

> Why define a new function, instead of adding optional arguments to the existing one?

No real reason; new patch doing so attached.

> Why not look at what mastodon.el does, as the comment in seconds-to-string suggests? For example, mastodon-tl--human-duration lets you specify whatever resolution you want, instead of limiting you to either 0.5 or 1  as in the proposed patch.

I see that mastodon is a package in ELPA, so doesn't satisfy the need in core.  I took a look at this function.  The RESOLUTION mentioned is not equivalent to the HALF argument, it is the minimum resolution in seconds.  So setting it to e.g. 3600 results in truncating to the hour, but changes nothing below the hour.  Setting it to the number of seconds in a year gives something quite similar to magit--age (though I notice the mastodon function truncates, instead of rounds; see, e.g., 2.98y in the table below).

Here's a comparison among:

- the current seconds-to-string
- mastodon-tl--human-duration
- mastodon with a 3600s resolution
- mastodon with 1yr "resolution"
- the new seconds-to-string with option READABLE=t
- new seconds-to-string with abbreviated units and half unit resolution

  Delay (s)      s-to-s            mastodon    mastodon (3600s)    mast (1yr)  s-to-s (rdb)  s-to-s (rdb=abbrev, half)
        0.5    450.00ms               0 sec               0 sec         0 sec     0 seconds  ½s
        1.0       1.03s               1 sec               1 sec         1 sec      1 second  1s
        2.4       2.38s              2 secs              2 secs        2 secs     2 seconds  2½s
        5.5       5.48s              5 secs              5 secs        5 secs     5 seconds  5½s
       12.6      12.59s             12 secs             12 secs       12 secs    13 seconds  12½s
       29.0      28.96s             28 secs             28 secs       28 secs    29 seconds  29s
       66.6      66.62s               1 min               1 min         1 min      1 minute  1m
      153.2       2.55m              2 mins              2 mins        2 mins     3 minutes  2½m
      352.4       5.87m              5 mins              5 mins        5 mins     6 minutes  6m
      810.5      13.51m             13 mins             13 mins       13 mins    14 minutes  13½m
     1864.2      31.07m             31 mins             31 mins       31 mins    31 minutes  31m
     4287.6      71.46m     1 hour, 11 mins              1 hour        1 hour        1 hour  1h
     9861.6       2.74h    2 hours, 44 mins             2 hours       2 hours       3 hours  2½h
    22681.6       6.30h    6 hours, 18 mins             6 hours       6 hours       6 hours  6½h
    52167.8      14.49h   14 hours, 29 mins            14 hours      14 hours      14 hours  14½h
   119985.9       1.39d      1 day, 9 hours      1 day, 9 hours         1 day         1 day  1½d
   275967.5       3.19d     3 days, 4 hours     3 days, 4 hours        3 days        3 days  3d
   634725.2       7.35d              1 week              1 week        1 week        1 week  1w
  1459867.9      16.90d     2 weeks, 2 days     2 weeks, 2 days       2 weeks       2 weeks  2½w
  3357696.2      38.86d     1 month, 1 week     1 month, 1 week       1 month       1 month  1½M
  7722701.2      89.38d   2 months, 4 weeks   2 months, 4 weeks      2 months      3 months  3M
 17762212.9     205.58d   6 months, 3 weeks   6 months, 3 weeks      6 months      7 months  7M
 40853089.6       1.29y    1 year, 3 months    1 year, 3 months        1 year        1 year  1½Y
 93962106.0       2.98y  2 years, 11 months  2 years, 11 months       2 years       3 years  3Y
216112843.8       6.85y  6 years, 10 months  6 years, 10 months       6 years       7 years  7Y
497059540.7      15.75y  15 years, 9 months  15 years, 9 months      15 years      16 years  16Y

The last column is obviously the most compact while still conveying a good amount of information, but the 1yr mastodon and normal READABLE s-to-s are also quite good (effectively equivalent to magit--age) for a quick glance and maintaining ~constant widths.  I do find it awkward to set the RESOLUTION argument to >30 million seconds to achieve this.  It took me a bit to understand what this argument does. 

Code use to produce:

(concat
 (format "%11s  %10s  %18s  %18s  %12s  %12s  %s\n" "Delay (s)" "s-to-s"
         "mastodon" "mastodon (3600s)" "mast (1yr)" "s-to-s (rdb)" "s-to-s (rdb=abbrev, half)")
 (cl-loop for s = 0.45 then (* s 2.3) while (< s (* 365.25 24 3600 22))
          concat (format "%11.1f  %10s  %18s  %18s  %12s  %12s  %s\n" s
                         (seconds-to-string s)
                         (car (mastodon-tl--human-duration s))
                         (car (mastodon-tl--human-duration s 3600))
                         (car (mastodon-tl--human-duration s (* 365.25 24 3600)))
                         (seconds-to-string s t)
                         (seconds-to-string s 'abbrev 'half))))



[-- Attachment #2.1: Type: text/html, Size: 11225 bytes --]

[-- Attachment #2.2: time-data-readable-seconds.patch --]
[-- Type: application/octet-stream, Size: 2217 bytes --]

--- time-date.el	2024-06-22 21:51:21
+++ time-date_new.el	2024-06-22 21:53:13
@@ -406,10 +406,41 @@
         (list (* 3600 24 400) "d" (* 3600.0 24.0))
         (list nil "y" (* 365.25 24 3600)))
   "Formatting used by the function `seconds-to-string'.")
+
+(defvar seconds-to-string-readable
+  `(("Y" "year"   "years"   ,(round (* 60 60 24 365.2425)))
+    ("M" "month"  "months"  ,(round (* 60 60 24 30.436875)))
+    ("w" "week"   "weeks"   ,(* 60 60 24 7))
+    ("d" "day"    "days"    ,(* 60 60 24))
+    ("h" "hour"   "hours"   ,(* 60 60))
+    ("m" "minute" "minutes" 60)
+    ("s" "second" "seconds" 1))
+  "Formatting used by the function `seconds-to-string' with READABLE set.")
+
 ;;;###autoload
-(defun seconds-to-string (delay)
-  "Convert the time interval in seconds to a short string."
-  (cond ((> 0 delay) (concat "-" (seconds-to-string (- delay))))
+(defun seconds-to-string (delay &optional readable half)
+  "Convert the time interval in seconds to a short string.
+If READABLE is non-nil, convert DELAY into a readable string.  If it is
+the value `abbrev', abbreviate the units.  If HALF is set, round to the
+nearest half unit."
+  (cond ((> 0 delay) (concat "-" (seconds-to-string (- delay) readable half)))
+        (readable
+         (let ((abbrev (eq readable 'abbrev))
+               (stsa seconds-to-string-readable)
+               here cnt)
+           (if (= (round delay (if half 0.5 1.)) 0)
+               (format "0%s" (if abbrev "s" " seconds"))
+             (while (and (setq here (pop stsa)) stsa
+                         (< (/ delay (nth 3 here)) 1)))
+             (setq cnt (round (/ (float delay) (nth 3 here)) (if half 0.5 1.)))
+             (concat
+              (let ((c (if half (/ cnt 2) cnt)))
+                (if (> c 0) (number-to-string c) ""))
+              (if (and half (= (mod cnt 2) 1)) "½" "")
+              (if abbrev "" " ")
+              (cond (abbrev (car here))
+                    ((<= cnt (if half 2 1)) (nth 1 here))
+                    (t (nth 2 here)))))))
         ((= 0 delay) "0s")
         (t (let ((sts seconds-to-string) here)
              (while (and (car (setq here (pop sts)))

[-- Attachment #2.3: Type: text/html, Size: 212 bytes --]

bug#71572: [PATCH] seconds-to-string-approximate

[Eli Zaretskii]

> Date: Sat, 22 Jun 2024 19:42:25 -0400
> Cc: 71572@debbugs.gnu.org, adam@alphapapa.net, jonas@bernoul.li
> From: Paul Eggert <eggert@cs.ucla.edu>
> 
> Isn't the master branch was in an long-term sort-of-frozen state, until 
> a branch is created for Emacs 30? If so I imagine changes in this area 
> should wait.

Yes, this is for Emacs 31.