From mboxrd@z Thu Jan 1 00:00:00 1970 From: Nicolas Goaziou Subject: [ANN] New Org duration library Date: Mon, 13 Feb 2017 15:10:38 +0100 Message-ID: <87bmu6p4f5.fsf@nicolasgoaziou.fr> Mime-Version: 1.0 Content-Type: text/plain Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:53863) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cdHL1-00015i-5a for emacs-orgmode@gnu.org; Mon, 13 Feb 2017 09:10:44 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1cdHKz-0008OH-S9 for emacs-orgmode@gnu.org; Mon, 13 Feb 2017 09:10:43 -0500 Received: from relay4-d.mail.gandi.net ([2001:4b98:c:538::196]:45010) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1cdHKz-0008O7-Dn for emacs-orgmode@gnu.org; Mon, 13 Feb 2017 09:10:41 -0500 Received: from saiph.selenimh (00004301000000000000074b.ipv6.commingeshautdebit.fr [IPv6:2a03:a0a0:0:4301::74b]) (Authenticated sender: mail@nicolasgoaziou.fr) by relay4-d.mail.gandi.net (Postfix) with ESMTPSA id 00EEC1720CF for ; Mon, 13 Feb 2017 15:10:38 +0100 (CET) Received: from ngz by saiph.selenimh with local (Exim 4.88) (envelope-from ) id 1cdHKw-0005y3-Hp for emacs-orgmode@gnu.org; Mon, 13 Feb 2017 15:10:38 +0100 List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: "Emacs-orgmode" To: Org Mode List Hello, * TL;DR; `org-time-clocksum-format', `org-time-clocksum-use-fractional' and `org-time-clocksum-fractional-format' are obsolete. If you changed them, consider modifying ~org-duration-format~ instead. Variable `org-time-clocksum-use-effort-durations' is also obsolete. Consider setting `org-duration-units' instead. * Rationale In current stable version, time duration handling is unsatisfactory: - There are overlapping and confusing functions: `org-minutes-to-clocksum-string', `org-hh:mm-string-to-minutes' and `org-duration-string-to-minutes'. - Duration format is powerful but complex to handle since there are four variables involved: `org-time-clocksum-format', `org-time-clocksum-use-fractional', `org-time-clocksum-fractional-format' and `org-time-clocksum-use-effort-durations'. - More importantly, if you set that format to something fancy, it is not possible anymore to read the produced string back. Therefore, I implemented and merged a simple "duration" library that takes care of reading and producing such durations. Quoting the file's commentary: This library provides tools to manipulate durations. A duration can have multiple formats: - 3:12 - 1:23:45 - 1y 3d 3h 4min - 3d 13:35 - 2.35h More accurately, it consists of numbers and units, as defined in variable `org-duration-units', separated with white spaces, and a "H:MM" or "H:MM:SS" part. White spaces are tolerated between the number and its relative unit. Variable `org-duration-format' controls durations default representation. The library provides functions allowing to convert a duration to, and from, a number of minutes: `org-duration-to-minutes' and `org-duration-from-minutes'. It also provides two lesser tools: `org-duration-p', and `org-duration-h:mm-only-p'. Users can set the number of minutes per unit, or define new units, in `org-duration-units'. The library also supports canonical duration, i.e., a duration that doesn't depend on user's settings, through optional arguments. At the cost of some incompatibilities if you introduced some fancy duration format, and a slightly more limited choice of representation, we get a more consistent and sturdy interface. * About base unit design choice The base unit for a duration is the minute. I hesitated with the more natural second but - Org time precision is the minute, - `org-duration-to-minutes' and `org-duration-from-minutes' can be drop-in replacements for the functions quoted above, - We would need to handle floats anyway as we don't require custom units to be multiple of the base unit. Feedback welcome. Regards, -- Nicolas Goaziou 0x80A93738