#51030 [Opn->Csd]: DateInterval::format() does not handle "carry-over points"

ID: 51030 Updated by: kalle@php.net Reported By: m dot kurzyna at crystalpoint dot pl -Status: Open +Status: Closed Bug Type: Documentation problem Operating System: Linux PHP Version: Irrelevant -Assigned To: +Assigned To: kalle New Comment: This bug has been fixed in the documentation's XML sources. Since the online and downloadable versions of the documentation need some time to get updated, we would like to ask you to be a bit patient. Thank you for the report, and for helping us make our documentation better. Previous Comments: ------------------------------------------------------------------------ [2010-02-17 04:59:49] svn@php.net Automatic comment from SVN on behalf of kalle Revision: http://svn.php.net/viewvc/?view=revision&revision=295194 Log: Fixed bug #51030 (DateInterval::format() does not handle "carry-over points") - Patch based on patch by <m dot kurzyna at crystalpoint dot pl> ------------------------------------------------------------------------ [2010-02-13 13:12:30] m dot kurzyna at crystalpoint dot pl Given that patches speak more then words, for format: http://svn.php.net/viewvc/phpdoc/en/trunk/reference/datetime/dateinterval/format.xml?view=log --- format.xml?revision=293203 2010-02-13 13:59:58.925136599 +0100 +++ modified.xml 2010-02-13 14:08:12.238423558 +0100 @@ -162,6 +162,33 @@ </screen> </example> </para> + <para> +<![CDATA[ +The DateInterval::format() function doesn't recalculate carry over points in +time nor in date segments. This is expected behaviour because you can't +overflow "32 days". It could be anything from 1 month, 4 days to 1 month, 1 +day. +]]> + <example> + <title><classname>DateInterval</classname> example</title> + <programlisting role="php"> +<![CDATA[ +<?php + +$interval = new DateInterval('P32D'); +echo $interval->format('%d days'); + +?> +]]> + </programlisting> + &example.outputs; + <screen role="php"> +<![CDATA[ +32 days +]]> + </screen> + </example> + </para> </refsect1> </refentry> And for the add function (sub() should be same i suppose): http://svn.php.net/viewvc/phpdoc/en/trunk/reference/datetime/datetime/add.xml?view=log --- add.xml?revision=289096 2010-02-13 14:09:57.735365489 +0100 +++ modified2.xml 2010-02-13 14:10:49.675492799 +0100 @@ -49,7 +49,7 @@ <refsect1 role="returnvalues"> &reftitle.returnvalues; <para> - Returns the modified DateTime. + Returns the modified self object (DateTime). </para> </refsect1> TIA ------------------------------------------------------------------------ [2010-02-13 12:54:04] m dot kurzyna at crystalpoint dot pl Aye. And i admit i haven't thought of that - feel free to mark me bogus ;-) Leap years also come to mind now; as i was fixed on the time issue which i have run into i haven't considered dates at all. I'd still vote on documentation clarification there though; and maybe giving your explanation as well. As a side note - i was experimenting with date manipulation (in order to check whether combination of DateTime::add()/diff() would yield what i need) and have run into another (sort of) ambiguity: $today = new DateTime(); $tomorrow = $today ->add(new DateInterval('P1D'); $today is $tomorrow (as in same object). I didn't expect that only by examining documentation. I'd change: Return Values Returns the modified DateTime. to: Return Values Returns the modified self object (DateTime). I love the ability to do chain calls and actually like this feature - it's just i haven't expected it from core. No real statistics behind it but i have a feeling that most PHP functions don't return self references. Take SimpleXMLElement::addChild() for example as it's a similar case. It returns added child not "self" containing the added child. No matter - just wondering off there. Point is: please be so kind and consider documentation enhancements (although i admit it's not a very critical case and based mostly on my assumptions on how things will work). ------------------------------------------------------------------------ [2010-02-12 20:39:36] derick@php.net THis is (code wise) on purpose, because you can't really overflow "32 days" for example (it could be 1month, 4 days to 1 month, 1 days f.e.) ------------------------------------------------------------------------ [2010-02-12 20:02:07] m dot kurzyna at crystalpoint dot pl Description: ------------ DateInterval::format() does not handle "carry over points" thus having 25 hours or 70 minutes is a valid output. Format description suggests that output would be recalculated (but specifying min,middle,max sample outputs). Submitted as documentation problem but IMHO the implementation could be changed (at least be optional whether to recalculate carry overs or not). Reproduce code: --------------- <?php $dti = new \DateInterval('PT70M'); echo $dti->format('%H:%I:%S'); ?> Expected result: ---------------- 01:10:00 Actual result: -------------- 00:70:00 ------------------------------------------------------------------------ -- Edit this bug report at http://bugs.php.net/?id=51030&edit=1