Format durations in seconds as human-friendly strings

format-seconds

#+TITLE: format-seconds
#+SUBTITLE: Format integer seconds as human-readable duration strings
#+DESCRIPTION: User Manual
#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="style.css" />

#+BEGIN_EXPORT html
<a href="https://liberapay.com/contrapunctus/donate">
  <img alt="Donate using Liberapay" src="https://img.shields.io/liberapay/receives/contrapunctus.svg?logo=liberapay">
</a>
#+END_EXPORT

* Explanation
:PROPERTIES:
:CUSTOM_ID: explanation
:END:
=format-seconds= is a Common Lisp system to format seconds as an integer into human-readable duration strings, based on a control string similar to =format=. It tries to provide the equivalent of =format-seconds= from Emacs Lisp, but adopts Common Lisp conventions wherever possible.

#+BEGIN_SRC lisp
 * (format-seconds nil
                "I've been waiting ~Y, ~W, ~D, and oh...~M to fix what he did to me."
                33869640)
 "I've been waiting 1 year, 3 weeks, 6 days, and oh...14 minutes to fix what he did to me."
#+END_SRC

To see more of what it can do, have a [[#tutorial][look at the tutorial]].

** Comparison with prior art
:PROPERTIES:
:CUSTOM_ID: differences-from-emacs-lisp
:END:
This library has the following differences compared to Elisp's =format-seconds= -
1. As with Common Lisp's =format=, there is an additional =destination= parameter, and control string directives begin with =~= rather than =%=,
2. Durations may be formatted as months (30 days) and weeks (7 days). The Elisp version supports years and days, and nothing in between.
3. Directives can contain any prefix parameters acceptable to =format='s =~D= directive.
4. The =%z= directive is planned, but not yet implemented.

Differences from [[https://github.com/enaeher/local-time-duration][=local-time-duration:human-readable-duration=]] -
1. Durations may be formatted as years (365 days) or months (30 days). The largest unit supported by =local-time-duration:human-readable-duration= is weeks.
2. The user controls the output string and the units used, and whether or not unit names are emitted.
3. Consumes integer seconds rather than =local-time-duration:duration= instances.

Differences from [[https://github.com/40ants/humanize-duration][humanize-duration]] -
1. Durations may be formatted as years (365 days) or months (30 days). The largest unit supported by =humanize-duration= is weeks.
2. Control over output string is provided by a =format=-like control string, rather than a list.
3. Consumes integer seconds rather than =local-time-duration:duration= instances.

** The month unit
:PROPERTIES:
:CUSTOM_ID: month-unit
:END:
The month unit is rife with issues. It all depends on how you define it.

*** A month is 30 days
:PROPERTIES:
:CUSTOM_ID: month-is-30-days
:END:
You could define a month as 30 days, which is the default. That works well for most situations.
#+BEGIN_SRC lisp
(let* ((minute 60)
       (hour   (* 60 minute))
       (day    (* 24 hour))
       (week   (* 7 day))
       (year   (* 365 day)))
  (list
   (format-seconds nil "~O, ~W, ~D" (+ year
                                       (* 3 week)
                                       (* 4 day)
                                       (* 23 hour)
                                       (* 59 minute)
                                       59))
   (format-seconds nil "~O, ~W, ~D" (+ year (* 3 week)))))
;; =>
("13 months, 0 weeks, 0 days"
 "12 months, 3 weeks, 5 days")
#+END_SRC
Why is that 13 months, seeing as we supplied 12? Where do those mysterious 5 days come from?

The problem is that if a month is defined as 30 days and a year as 365 days, a year has 12 months and /5 days/. 5 days + 3 weeks (21 days) + 4 days = 30 days, resulting in an extra month. The same 5 days manifest in the second example.

*** A month is 1/12th of a year
:PROPERTIES:
:CUSTOM_ID: month-is-1-12th-of-year
:END:
Alternatively, you could define a month as 1/12th of a year -
#+BEGIN_SRC lisp
(setq *units*
      (let* ((second (make-unit "second" "s" 1))
             (minute (make-unit "minute" "m" 60))
             (hour   (make-unit "hour" "h" (* 60 60)))
             (day    (make-unit "day"  "d" (* 24 60 60)))
             (week   (make-unit "week" "w" (* 7 24 60 60)))
             (year   (make-unit "year" "y" (* 365 24 60 60)))
             (month  (make-unit "month" "o" (/ (seconds year) 12))))
        (list year month week day hour minute second)))
#+END_SRC

The earlier examples now return -
#+BEGIN_SRC lisp
("12 months, 3 weeks, 4 days"
 "12 months, 3 weeks, 0 days")
#+END_SRC

Any test code using this definition of months must define months in input durations as =(/ year 12)=, or you'll get unexpected results.
#+BEGIN_SRC lisp
(let ((day (* 24 60 60)))
  (format-seconds nil "~Y, ~O" (+ (* 2 365 day)
                                  (* 2 30 day))))
"2 years, 1 month" ;; ouch

(let* ((day   (* 24 60 60))
       (year  (* 365 day))
       (month (/ year 12)))
  (format-seconds nil "~Y, ~O" (+ (* 2 year) (* 2 month))))
"2 years, 2 months" ;; whew
#+END_SRC

*** Remove months entirely
:PROPERTIES:
:CUSTOM_ID: remove-months-entirely
:END:
A third option could be to remove support for months entirely.
#+BEGIN_SRC lisp
(setq *units*
      (loop for (name directive seconds) in
            `(("year" "y"   ,(* 365 24 60 60))
              ("week" "w"   ,(* 7 24 60 60))
              ("day" "d"    ,(* 24 60 60))
              ("hour" "h"   ,(* 60 60))
              ("minute" "m" 60)
              ("second" "s" 1))
            collect (make-unit name directive seconds)))
#+END_SRC

** Possible future improvements
:PROPERTIES:
:CUSTOM_ID: possible-future-improvements
:END:
1. Support for microseconds
2. Support for using =format='s =~R= directive instead of =~D=.
3. Support for multiple languages.
4. Optimization

** Contributions and contact
:PROPERTIES:
:CUSTOM_ID: contributions-contact
:END:
Feedback and MRs are very welcome. ὤ2

Get in touch with the author and other Lisp users the Lisp Jabber/XMPP channel - [[https://conversations.im/j/lisp@conference.a3.pm][xmpp:lisp@conference.a3.pm?join]] ([[https://inverse.chat/#converse/room?jid=lisp@conference.a3.pm][web chat]])

(For help in getting started with Jabber, [[https://xmpp.org/getting-started/][click here]])

** License
:PROPERTIES:
:CUSTOM_ID: license
:END:
I'd /like/ for all software to be liberated - transparent, trustable, and accessible for anyone to use, study, or improve.

I'd /like/ anyone using my software to credit me for the work.

I'd /like/ to receive financial support for my efforts, so I can spend all my time doing what I find meaningful.

But I don't want to make demands or threats (e.g. via legal conditions) to accomplish all that, nor restrict my services to only those who can pay.

Thus, =format-seconds= is released under your choice of [[https://unlicense.org/][Unlicense]] or the [[http://www.wtfpl.net/][WTFPL]].

(See files [[file:UNLICENSE][UNLICENSE]] and [[file:WTFPL][WTFPL]]).

** Thanks
:PROPERTIES:
:CUSTOM_ID: thanks
:END:
acdw, hdasch, Zash, gilberth, and moonchild, for discussing the behavior of the library.

* Tutorial
:PROPERTIES:
:CUSTOM_ID: tutorial
:END:

Let's set up our session. Enter the following forms into your REPL. (The =*= represents the REPL prompt and is not meant to be entered.)
#+BEGIN_SRC lisp
 * (ql:quickload :format-seconds)
 * (use-package :format-seconds)
 * (defvar *year* (* 365 24 60 60))
 * (defvar *day* (* 24 60 60))
#+END_SRC

The =destination= parameter works like it does in =format=. For instance, pass =T= as destination to print to =*standard-output*= -
#+BEGIN_SRC lisp
 * (format-seconds t "~Y" *year*)
 1 year
 NIL
#+END_SRC

Or pass =NIL= as destination to return a string. Note the pluralization based on the provided duration.
#+BEGIN_SRC lisp
 * (format-seconds nil "~Y" 0)
 "0 years"
 * (format-seconds nil "~Y" *year*)
 "1 year"
 * (format-seconds nil "~Y" (* 2 *year*))
 "2 years"
#+END_SRC

To omit unit strings, you can use lower-case directives -
#+BEGIN_SRC lisp
 * (format-seconds nil "~yy ~om" (* 60 24 60 60))
 "0y 2m"
#+END_SRC

Any prefix parameters acceptable to =format='s ~D directive can be used. Let's left-pad the durations with zeroes -
#+BEGIN_SRC lisp
 * (format-seconds nil "~2,'0h:~2,'0m:~2,'0s" (* 2 *day*))
 "48:00:00"
#+END_SRC


format-seconds

Upstream URL

Author

License

format-seconds-tests

Version:

License:

Authors:

Defsystem Dependencies:

Dependencies:

Dependencies (2)

Dependents (0)