Difference Between Two Dates in Java

1. Overview

In this quick tutorial, we’ll explore multiple ways to calculate the difference between two dates in Java.

2. Core Java

2.1. Using java.util.Date to Find the Difference in Days

Let’s start by using the core Java APIs to do the calculation and determine the number of days between the two dates:

@Test
public void givenTwoDatesBeforeJava8_whenDifferentiating_thenWeGetSix()
  throws ParseException {
 
    SimpleDateFormat sdf = new SimpleDateFormat("MM/dd/yyyy", Locale.ENGLISH);
    Date firstDate = sdf.parse("06/24/2017");
    Date secondDate = sdf.parse("06/30/2017");

    long diffInMillies = Math.abs(secondDate.getTime() - firstDate.getTime());
    long diff = TimeUnit.DAYS.convert(diffInMillies, TimeUnit.MILLISECONDS);

    assertEquals(6, diff);
}

2.2. Using java.time.temporal.ChronoUnit to Find the Difference

The Time API in Java 8 represents a unit of date-time, e.g. seconds or days, using TemporalUnit interface.

Each unit provides an implementation for a method named between() to calculate the amount of time between two temporal objects in terms of that specific unit.

For example, to calculate the seconds between two LocalDateTime instances:

@Test
public void givenTwoDateTimesInJava8_whenDifferentiatingInSeconds_thenWeGetTen() {
    LocalDateTime now = LocalDateTime.now();
    LocalDateTime tenSecondsLater = now.plusSeconds(10);

    long diff = ChronoUnit.SECONDS.between(now, tenSecondsLater);

    assertEquals(10, diff);
}

ChronoUnit provides a set of concrete time units by implementing the TemporalUnit interface. It’s highly recommended to static import the ChronoUnit enum values to achieve better readability:

import static java.time.temporal.ChronoUnit.SECONDS;

// omitted
long diff = SECONDS.between(now, tenSecondsLater);

Also, we can pass any two compatible temporal objects to the between method, even the ZonedDateTime.

What’s great about ZonedDateTime is that the calculation will work even if they are set to different time zones:

@Test
public void givenTwoZonedDateTimesInJava8_whenDifferentiating_thenWeGetSix() {
    LocalDateTime ldt = LocalDateTime.now();
    ZonedDateTime now = ldt.atZone(ZoneId.of("America/Montreal"));
    ZonedDateTime sixMinutesBehind = now
      .withZoneSameInstant(ZoneId.of("Asia/Singapore"))
      .minusMinutes(6);
    
    long diff = ChronoUnit.MINUTES.between(sixMinutesBehind, now);
    
    assertEquals(6, diff);
}

2.3. Using Temporal#until()

Any Temporal object, such as LocalDate or ZonedDateTime,provides an until method to calculate the amount of time until another Temporal in terms of the specified unit:

@Test
public void givenTwoDateTimesInJava8_whenDifferentiatingInSecondsUsingUntil_thenWeGetTen() {
    LocalDateTime now = LocalDateTime.now();
    LocalDateTime tenSecondsLater = now.plusSeconds(10);

    long diff = now.until(tenSecondsLater, ChronoUnit.SECONDS);

    assertEquals(10, diff);
}

The Temporal#until and TemporalUnit#between are two different APIs for the same functionality.

2.4. Using java.time.Duration and java.time.Period

In Java 8, the Time API introduced two new classes: Duration and Period.

If we want to calculate the difference between two date-times in a time-based (hour, minutes, or seconds) amount of time, we can use the Duration class:

@Test
public void givenTwoDateTimesInJava8_whenDifferentiating_thenWeGetSix() {
    LocalDateTime now = LocalDateTime.now();
    LocalDateTime sixMinutesBehind = now.minusMinutes(6);

    Duration duration = Duration.between(now, sixMinutesBehind);
    long diff = Math.abs(duration.toMinutes());

    assertEquals(6, diff);
}

However, we should be wary of a pitfall if we try using the Period class to represent the difference between two dates.

An example will explain this pitfall quickly.

Let’s calculate how many days between two dates using the Period class:

@Test
public void givenTwoDatesInJava8_whenUsingPeriodGetDays_thenWorks() {
    LocalDate aDate = LocalDate.of(2020, 9, 11);
    LocalDate sixDaysBehind = aDate.minusDays(6);

    Period period = Period.between(aDate, sixDaysBehind);
    int diff = Math.abs(period.getDays());

    assertEquals(6, diff);
}

If we run the test above, it’ll pass. We may think the Period class is convenient for solving our problem. So far, so good.

If this way works with a difference of six days, we don’t doubt that it’ll work for 60 days as well.

So let’s change the 6 in the test above to 60 and see what happens:

@Test
public void givenTwoDatesInJava8_whenUsingPeriodGetDays_thenDoesNotWork() {
    LocalDate aDate = LocalDate.of(2020, 9, 11);
    LocalDate sixtyDaysBehind = aDate.minusDays(60);

    Period period = Period.between(aDate, sixtyDaysBehind);
    int diff = Math.abs(period.getDays());

    assertEquals(60, diff);
}

Now if we run the test again, we’ll see:

java.lang.AssertionError:
Expected :60
Actual   :29

Oops! Why did the Period class report the difference as 29 days?

This is because the Period class represents a date-based amount of time in the format of “x years, y months and z days”. When we call its getDays() method, it returns only the “z days” part.

Therefore, the period object in the test above holds the value “0 years, 1 month and 29 days”:

@Test
public void givenTwoDatesInJava8_whenUsingPeriod_thenWeGet0Year1Month29Days() {
    LocalDate aDate = LocalDate.of(2020, 9, 11);
    LocalDate sixtyDaysBehind = aDate.minusDays(60);
    Period period = Period.between(aDate, sixtyDaysBehind);
    int years = Math.abs(period.getYears());
    int months = Math.abs(period.getMonths());
    int days = Math.abs(period.getDays());
    assertArrayEquals(new int[] { 0, 1, 29 }, new int[] { years, months, days });
}

If we want to calculate the difference in days using Java 8’s Time API, the ChronoUnit.DAYS.between() method is the most straightforward way.

3. External Libraries

3.1. JodaTime

We can also do a relatively straightforward implementation with JodaTime:

<dependency>
    <groupId>joda-time</groupId>
    <artifactId>joda-time</artifactId>
    <version>2.13.1</version>
</dependency>

The latest version of Joda-time is available from Maven Central.

Let’s look at the LocalDate case:

@Test
public void givenTwoDatesInJodaTime_whenDifferentiating_thenWeGetSix() {
    org.joda.time.LocalDate now = org.joda.time.LocalDate.now();
    org.joda.time.LocalDate sixDaysBehind = now.minusDays(6);

    long diff = Math.abs(Days.daysBetween(now, sixDaysBehind).getDays());
    assertEquals(6, diff);
}

Similarly, we can use LocalDateTime:

@Test
public void givenTwoDateTimesInJodaTime_whenDifferentiating_thenWeGetSix() {
    org.joda.time.LocalDateTime now = org.joda.time.LocalDateTime.now();
    org.joda.time.LocalDateTime sixMinutesBehind = now.minusMinutes(6);

    long diff = Math.abs(Minutes.minutesBetween(now, sixMinutesBehind).getMinutes());
    assertEquals(6, diff);
}

3.2. Date4J

Date4j also provides a straightforward implementation — noting that, in this case, we need to explicitly provide a TimeZone.

Let’s start with the Maven dependency:

<dependency>
    <groupId>com.darwinsys</groupId>
    <artifactId>hirondelle-date4j</artifactId>
    <version>1.5.1</version>
</dependency>

Here’s a quick test working with the standard DateTime:

@Test
public void givenTwoDatesInDate4j_whenDifferentiating_thenWeGetSix() {
    DateTime now = DateTime.now(TimeZone.getDefault());
    DateTime sixDaysBehind = now.minusDays(6);
 
    long diff = Math.abs(now.numDaysFrom(sixDaysBehind));

    assertEquals(6, diff);
}

4. Getting the Number of Weeks Between Two Dates

We can also get the number of weeks between two dates using one of the date-time APIs.

4.1. Using DateTime from Joda-Time

The org.joda.time.Weeks class in Joda-Time stores an immutable period representing a specific number of weeks. We can query for the difference between two dates represented in weeks using the getWeeks() method.

Let’s find the number of weeks between two org.joda.time.DateTime values:

@Test
public void givenTwoDateTimesInJodaTime_whenComputingDistanceInWeeks_thenFindIntegerWeeks() {
    DateTime dateTime1 = new DateTime(2024, 1, 17, 15, 50, 30);
    DateTime dateTime2 = new DateTime(2024, 6, 3, 10, 20, 55);
    int weeksDiff = Weeks.weeksBetween(dateTime1, dateTime2).getWeeks();

    assertEquals(19, weeksDiff);
}

The JUnit test should pass because the difference between the two DateTime values in weeks is 19.

However, Weeks can only store weeks; it doesn’t store days, hours, or minutes, for example. The two example DateTime values have a remainder of an additional four days.

We can achieve higher precision by using the org.joda.time.Days class:

@Test
public void givenTwoDateTimesInJodaTime_whenComputingDistanceInDecimalWeeks_thenFindDecimalWeeks() {
    DateTime dateTime1 = new DateTime(2024, 1, 17, 15, 50, 30);
    DateTime dateTime2 = new DateTime(2024, 6, 3, 10, 20, 55);

    int days = Days.daysBetween(dateTime1, dateTime2).getDays();
    float weeksDiff=(float) (days/7.0);

    assertEquals(19.571428, weeksDiff, 0.001);
}

Note that we cast the int value for the difference in days to float or double to get decimal-level precision.

4.2. Using LocalDate

The java.time.LocalDate class is an immutable date-time object that represents a date without a time-zone in the ISO-8601 calendar system, such as 2007-12-03.

With LocalDate instances, we can determine the difference in weeks using the ChronoUnit.WEEKS.between() method:

@Test
public void givenTwoLocalDatesInJava8_whenUsingChronoUnitWeeksBetween_thenFindIntegerWeeks() {
    LocalDate startLocalDate = LocalDate.of(2024, 01, 10);
    LocalDate endLocalDate = LocalDate.of(2024, 11, 15);

    long weeksDiff = ChronoUnit.WEEKS.between(startLocalDate, endLocalDate);

    assertEquals(44, weeksDiff);
}

As before with Weeks#weeksBetween, this truncates any extra days.

4.3. Using ZonedDateTime

The java.time.ZonedDateTime class is an immutable date-time class that represents a date with a time-zone in the ISO-8601 calendar system, such as 2007-12-03T10:15:30+01:00.

Again, we can determine the difference in weeks using the ChronoUnit.WEEKS.between() method:

@Test
public void givenTwoZonedDateTimesInJava8_whenUsingChronoUnitWeeksBetween_thenFindIntegerWeeks() {
    ZonedDateTime startDateTime = ZonedDateTime.parse("2022-02-01T00:00:00Z[UTC]");
    ZonedDateTime endDateTime = ZonedDateTime.parse("2022-10-31T23:59:59Z[UTC]");

    long weeksDiff = ChronoUnit.WEEKS.between(startDateTime, endDateTime);

    assertEquals(38, weeksDiff);
}

This also truncates any extra days.

5. Conclusion

In this article, we illustrated a few ways of calculating the difference between dates (with and without time), both in plain Java as well as using external libraries. Furthermore, we calculated the difference between dates in days, and in weeks.