svn commit: r483891 - /jakarta/commons/proper/lang/trunk/src/java/org/apache/commons/lang/time/DurationFormatUtils.java

[ba...@apache.org]

Author: bayard
Date: Fri Dec  8 01:05:52 2006
New Revision: 483891

URL: http://svn.apache.org/viewvc?view=rev&rev=483891
Log:
Added javadoc to explain the quandry in how to count month/day differences

Modified:
    jakarta/commons/proper/lang/trunk/src/java/org/apache/commons/lang/time/DurationFormatUtils.java

Modified: jakarta/commons/proper/lang/trunk/src/java/org/apache/commons/lang/time/DurationFormatUtils.java
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/lang/trunk/src/java/org/apache/commons/lang/time/DurationFormatUtils.java?view=diff&rev=483891&r1=483890&r2=483891
==============================================================================
--- jakarta/commons/proper/lang/trunk/src/java/org/apache/commons/lang/time/DurationFormatUtils.java (original)
+++ jakarta/commons/proper/lang/trunk/src/java/org/apache/commons/lang/time/DurationFormatUtils.java Fri Dec  8 01:05:52 2006
@@ -249,7 +249,18 @@
     /**
      * <p>Formats the time gap as a string, using the specified format.
      * Padding the left hand side of numbers with zeroes is optional and 
-     * the timezone may be specified. 
+     * the timezone may be specified. </p>
+     *
+     * <p>When calculating the difference between months/days, it chooses to 
+     * calculate months first. So when working out the number of months and 
+     * days between January 15th and March 10th, it choose 1 month and 
+     * 23 days gained by choosing January->February = 1 month and then 
+     * calculating days forwards, and not the 1 month and 26 days gained by 
+     * choosing March -> February = 1 month and then calculating days 
+     * backwards. </p>
+     *
+     * <p>For more control, the Joda Time library is recommended
+     * (<a href="http://joda-time.sf.net/"). </p>
      * 
      * @param startMillis  the start of the duration
      * @param endMillis  the end of the duration
@@ -304,11 +315,10 @@
         while (days < 0) {
             end.add(Calendar.MONTH, -1);
             days += end.getActualMaximum(Calendar.DAY_OF_MONTH);
-//days += 31; // TODO: Need tests to show this is bad and the new code is good.
-// HEN: It's a tricky subject. Jan 15th to March 10th. If I count days-first it is 
-// 1 month and 26 days, but if I count month-first then it is 1 month and 23 days.
-// Also it's contextual - if asked for no M in the format then I should probably 
-// be doing no calculating here.
+            // HEN: It's a tricky subject. Jan 15th to March 10th. If I count days-first it is 
+            // 1 month and 26 days, but if I count month-first then it is 1 month and 23 days.
+            // Also it's contextual - if asked for no M in the format then I should probably 
+            // be doing no calculating here.
             months -= 1;
             end.add(Calendar.MONTH, 1);
         }



---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org