DateUtils

About

DateUtils is a utility class provided by Apache Commons Lang to simplify working with java.util.Date. It provides null-safe, immutable, and convenient methods for:

• Date comparison

• Date truncation and rounding

• Adding or subtracting time units

• Setting specific fields of a date

• Calculating ranges (start of day/week/month)

• Iterating over date ranges

Characteristics

• Works primarily with java.util.Date (not java.time.*)

• All methods are static

• Provides safe and readable alternatives to manual Calendar manipulations

• Often used in legacy systems still relying on Date instead of LocalDate or ZonedDateTime

Maven Dependency & Import

<dependency>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-lang3</artifactId>
    <version>3.12.0</version> <!-- or latest -->
</dependency>

import org.apache.commons.lang3.time.DateUtils;

Common Methods

1. Date Comparison

Method	Description
isSameDay(Date d1, Date d2)	Checks if both dates fall on the same day
isSameInstant(Date d1, Date d2)	Checks if both dates represent the same instant
isSameLocalTime(Date d1, Date d2)	Checks if both dates have the same local time
truncatedEquals(Date d1, Date d2, int field)	Checks equality after truncating to a field

Example:

Date today = new Date();
Date another = DateUtils.addHours(today, 2);
boolean sameDay = DateUtils.isSameDay(today, another); // true

2. Truncation and Rounding

Method	Description
truncate(Date date, int field)	Resets lower fields to zero (e.g., time part)
round(Date date, int field)	Rounds up/down to the nearest field boundary
ceiling(Date date, int field)	Rounds up to the next unit

Example:

Date truncated = DateUtils.truncate(new Date(), Calendar.DAY_OF_MONTH);
// Returns date at 00:00:00 of the same day

3. Adding or Subtracting

Method	Description
addDays(date, int days)	Adds or subtracts days
addHours(date, int hours)	Adds or subtracts hours
addMinutes(date, int minutes)	Adds or subtracts minutes
addMonths(date, int months)	Adds or subtracts months
addWeeks(date, int weeks)	Adds or subtracts weeks
addYears(date, int years)	Adds or subtracts years

Example:

Date future = DateUtils.addDays(new Date(), 7); // 7 days later
Date past = DateUtils.addMonths(new Date(), -1); // 1 month ago

4. Setting Fields

Method	Description
setYears(date, int year)	Sets the year field
setHours(date, int hour)	Sets the hour field
setMinutes(date, int minutes)	Sets the minutes field

Example:

Date updated = DateUtils.setHours(new Date(), 15); // sets to 3 PM

5. Date Range Utilities

Method	Description
iterator(Date start, Date end, int rangeStyle)	Iterates over date ranges (e.g., by day/week)

Example:

Iterator<?> days = DateUtils.iterator(new Date(), DateUtils.RANGE_WEEK_CENTER);
while (days.hasNext()) {
    System.out.println(days.next());
}

Why Use DateUtils Instead of Raw Java?

Task	Without DateUtils	With DateUtils
Compare two dates (same day)	Complex Calendar logic	DateUtils.isSameDay(d1, d2)
Truncate to midnight	Manual time setting to zero	DateUtils.truncate(date, Calendar.DATE)
Add 1 week	Calendar.add(...)	DateUtils.addWeeks(date, 1)
Iterate through days	Manual loops and increment	DateUtils.iterator(...)