This is an automated email from the ASF dual-hosted git repository.
garydgregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-lang.git
The following commit(s) were added to refs/heads/master by this push:
new 17df41b44 Fix the month/day example in
DurationFormatUtils.formatPeriod Javadoc (#1772)
17df41b44 is described below
commit 17df41b44c2991d3d4a0fd3075a45735da513373
Author: anchor <[email protected]>
AuthorDate: Fri Aug 14 23:13:44 2026 +0800
Fix the month/day example in DurationFormatUtils.formatPeriod Javadoc
(#1772)
The Javadoc for formatPeriod(long, long, String, boolean, TimeZone) states
that January 15th to March 10th gives "1 month and 23 days" and explicitly
not "1 month and 26 days". The method returns the latter: the negative-days
loop borrows start.getActualMaximum(Calendar.DAY_OF_MONTH), the length of
the month the period starts in, which is the backwards calculation the
Javadoc disclaims. DurationFormatUtilsTest.testEdgeDurations asserts
"01 26" for this date pair, so the behavior is intentional.
Describe the implemented rule, correct the example, fix "it choose", and
reference java.time.Period#between for the forward calculation. Javadoc
only, no behavior change.
Assisted-by: Cursor (Claude Opus 5)
Co-authored-by: codeAnqiang-ma
<[email protected]>
---
.../java/org/apache/commons/lang3/time/DurationFormatUtils.java | 7 ++++---
1 file changed, 4 insertions(+), 3 deletions(-)
diff --git
a/src/main/java/org/apache/commons/lang3/time/DurationFormatUtils.java
b/src/main/java/org/apache/commons/lang3/time/DurationFormatUtils.java
index 23799d633..66d963ce9 100644
--- a/src/main/java/org/apache/commons/lang3/time/DurationFormatUtils.java
+++ b/src/main/java/org/apache/commons/lang3/time/DurationFormatUtils.java
@@ -505,9 +505,10 @@ public static String formatPeriod(final long startMillis,
final long endMillis,
* Formats the time gap as a string, using the specified format. Padding
the left-hand side side of numbers with zeroes is optional and the time zone
may be
* specified.
* <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.
+ * When calculating the difference between months/days, it chooses to
calculate months first, borrowing the length of the month in which the period
starts
+ * when the number of days would otherwise be negative. So when working
out the number of months and days between January 15th and March 10th, it
chooses
+ * 1 month and 26 days gained by choosing March -> February = 1 month
and then calculating days backwards, and not the 1 month and 23 days gained by
+ * choosing January->February = 1 month and then calculating days
forwards, as computed by {@link java.time.Period#between}.
* </p>
* <p>
* For more control, the <a
href="https://www.joda.org/joda-time/";>Joda-Time</a> library is recommended.
