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 d97a916de [LANG-441] DateUtils Javadoc does not fully define round()
behavior
d97a916de is described below
commit d97a916dedd5063b1320b34201ba41adb7281572
Author: Gary Gregory <[email protected]>
AuthorDate: Fri Oct 16 15:38:11 2026 -0400
[LANG-441] DateUtils Javadoc does not fully define round() behavior
Document minute, hour, month, year, and SEMI_MONTH thresholds, and link
the other overloads to the shared explanation. Document the exception
for unsupported fields.
---
src/changes/changes.xml | 1 +
.../java/org/apache/commons/lang3/time/DateUtils.java | 17 +++++++++++++++++
2 files changed, 18 insertions(+)
diff --git a/src/changes/changes.xml b/src/changes/changes.xml
index 6bcb7e3b2..606cdaf36 100644
--- a/src/changes/changes.xml
+++ b/src/changes/changes.xml
@@ -63,6 +63,7 @@ The <action> type attribute can be add,update,fix,remove.
<action issue="LANG-796" type="fix" dev="ggregory" due-to="gaurav kumar
pandey, Gary Gregory">Clarify DateUtils calendar arithmetic and daylight saving
time behavior.</action>
<action type="fix" dev="ggregory" due-to="alhuda, Gary
Gregory">Treat an unmatched quote as closed in ExtendedMessageFormat
(#1819).</action>
<action issue="LANG-796" type="fix" dev="ggregory" due-to="gaurav kumar
pandey, Gary Gregory">Prevent StringUtils padding from splitting surrogate
pairs (#1813).</action>
+ <action issue="LANG-441" type="fix" dev="ggregory" due-to="Sebb, Valentin
Rocher, Adarsh Kumar Omrey, Gary Gregory">DateUtils Javadoc does not fully
define round() behavior.</action>
<!-- ADD -->
<!-- UPDATE -->
</release>
diff --git a/src/main/java/org/apache/commons/lang3/time/DateUtils.java
b/src/main/java/org/apache/commons/lang3/time/DateUtils.java
index 226aaffc8..2f354037e 100644
--- a/src/main/java/org/apache/commons/lang3/time/DateUtils.java
+++ b/src/main/java/org/apache/commons/lang3/time/DateUtils.java
@@ -1503,6 +1503,12 @@ private static Date parseDateWithLeniency(final String
dateStr, final Locale loc
* </p>
*
* <p>
+ * Rounding ignores fields below the immediately smaller field: minutes
round up at 30 seconds, hours at 30 minutes,
+ * months at day 16 (day 15 in a 28-day month), and years at July. For
{@code SEMI_MONTH}, days 1–8 round to the 1st,
+ * days 9–23 to the 16th, and days 24 onward to the 1st of the next month.
+ * </p>
+ *
+ * <p>
* For a date in a time zone that handles the change to daylight
* saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows.
* Suppose daylight saving time begins at 02:00 on March 30. Rounding a
@@ -1520,6 +1526,7 @@ private static Date parseDateWithLeniency(final String
dateStr, final Locale loc
* @return The different rounded date, not null.
* @throws NullPointerException Thrown if the date is {@code null}.
* @throws ArithmeticException Thrown if the year is over 280 million.
+ * @throws IllegalArgumentException Thrown if the field is not supported.
*/
public static Calendar round(final Calendar calendar, final int field) {
Objects.requireNonNull(calendar, "calendar");
@@ -1538,6 +1545,10 @@ public static Calendar round(final Calendar calendar,
final int field) {
* </p>
*
* <p>
+ * See {@link #round(Calendar, int)} for rounding thresholds.
+ * </p>
+ *
+ * <p>
* For a date in a time zone that handles the change to daylight
* saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows.
* Suppose daylight saving time begins at 02:00 on March 30. Rounding a
@@ -1555,6 +1566,7 @@ public static Calendar round(final Calendar calendar,
final int field) {
* @return The different rounded date, not null.
* @throws NullPointerException Thrown if the date is null.
* @throws ArithmeticException Thrown if the year is over 280 million.
+ * @throws IllegalArgumentException Thrown if the field is not supported.
*/
public static Date round(final Date date, final int field) {
return modify(toCalendar(date), field, ModifyType.ROUND).getTime();
@@ -1572,6 +1584,10 @@ public static Date round(final Date date, final int
field) {
* </p>
*
* <p>
+ * See {@link #round(Calendar, int)} for rounding thresholds.
+ * </p>
+ *
+ * <p>
* For a date in a time zone that handles the change to daylight
* saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows.
* Suppose daylight saving time begins at 02:00 on March 30. Rounding a
@@ -1590,6 +1606,7 @@ public static Date round(final Date date, final int
field) {
* @throws NullPointerException Thrown if the date is {@code null}.
* @throws ClassCastException Thrown if the object type is not a {@link
Date} or {@link Calendar}.
* @throws ArithmeticException Thrown if the year is over 280 million.
+ * @throws IllegalArgumentException Thrown if the field is not supported.
*/
public static Date round(final Object date, final int field) {
Objects.requireNonNull(date, "date");
