GNU bug report logs - #71573
[PATCH] seconds-to-string-approximate

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 71573 in the body.
You can then email your comments to 71573 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: JD Smith <jdtsmith <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Cc: Adam Porter <adam <at> alphapapa.net>, jonas <at> bernoul.li
Subject: [PATCH] seconds-to-string-approximate
Date: Sat, 15 Jun 2024 13:24:00 -0400

[Message part 1 (text/plain, inline)]

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.

[seconds-to-string-approximate.patch (application/octet-stream, attachment)]

Message #8 received at 71573 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: JD Smith <jdtsmith <at> gmail.com>
Cc: 71573 <at> debbugs.gnu.org, adam <at> alphapapa.net, jonas <at> bernoul.li
Subject: Re: bug#71573: [PATCH] seconds-to-string-approximate
Date: Sat, 15 Jun 2024 20:36:01 +0300

merge 71573 71572
thanks

> Cc: Adam Porter <adam <at> alphapapa.net>, jonas <at> bernoul.li
> From: JD Smith <jdtsmith <at> 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.

Message #13 received at 71573 <at> debbugs.gnu.org (full text, mbox):

From: Adam Porter <adam <at> alphapapa.net>
To: 71573 <at> debbugs.gnu.org
Subject: Related functions from ts.el
Date: Mon, 17 Jun 2024 01:20:04 -0500

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

Message #16 received at 71573 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefankangas <at> gmail.com>
To: Adam Porter <adam <at> alphapapa.net>, 71573 <at> debbugs.gnu.org
Subject: Re: bug#71573: Related functions from ts.el
Date: Sat, 22 Jun 2024 03:55:41 -0700

Adam Porter <adam <at> 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'?

Message #19 received at 71573 <at> debbugs.gnu.org (full text, mbox):

From: Adam Porter <adam <at> alphapapa.net>
To: Stefan Kangas <stefankangas <at> gmail.com>, 71573 <at> debbugs.gnu.org
Subject: Re: bug#71573: Related functions from ts.el
Date: Sat, 22 Jun 2024 16:54:42 -0500

On 6/22/24 05:55, Stefan Kangas wrote:
> Adam Porter <adam <at> 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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.