Home / Date/Time / Duration and Period
Date/Time beginner

Duration and Period

Calculate time differences with type-safe Duration and Period.

Code Comparison
✕ Pre-Java 8 
// How many days between two dates?
long diff = date2.getTime()
    - date1.getTime();
long days = diff
    / (1000 * 60 * 60 * 24);
// ignores DST, leap seconds
✓ Java 8+ 
long days = ChronoUnit.DAYS
    .between(date1, date2);
Period period = Period.between(
    date1, date2);
Duration elapsed = Duration.between(
    time1, time2);
Why the modern way wins
🎯

Type-safe

Duration for time, Period for dates — no confusion.

🛡️

Correct math

Handles DST transitions, leap years, and leap seconds.

📖

Readable

ChronoUnit.DAYS.between() reads like English.

Old Approach
Millisecond Math
Modern Approach
Duration / Period
Since JDK
8
Difficulty
beginner
JDK Support
Duration and Period
Available

Widely available since JDK 8 (March 2014)

How it works

Duration is for time-based amounts (hours, minutes, seconds). Period is for date-based amounts (years, months, days). ChronoUnit.between() for simple differences. All handle edge cases correctly.

Related patterns

Date/Time beginner

java.time API basics

Pre-Java 8
// Mutable, confusing, zero-indexed months
Calendar cal = Calendar.getInstance();
cal.set(2025, 0, 15); // January = 0!
Date date = cal.getTime();
// not thread-safe
Java 8+
LocalDate date = LocalDate.of(
    2025, Month.JANUARY, 15);
LocalTime time = LocalTime.of(14, 30);
Instant now = Instant.now();
// immutable, thread-safe
Hover to see modern ➜
JDK 8+ →
Date/Time beginner

Date formatting

Pre-Java 8
// Not thread-safe!
SimpleDateFormat sdf =
    new SimpleDateFormat("yyyy-MM-dd");
String formatted = sdf.format(date);
// Must synchronize for concurrent use
Java 8+
DateTimeFormatter fmt =
    DateTimeFormatter.ofPattern(
        "yyyy-MM-dd");
String formatted =
    LocalDate.now().format(fmt);
// Thread-safe, immutable
Hover to see modern ➜
JDK 8+ →
Date/Time beginner

Math.clamp()

Java 8
// Clamp value between min and max
int clamped =
    Math.min(Math.max(value, 0), 100);
// or: min and max order confusion
Java 21+
int clamped =
    Math.clamp(value, 0, 100);
// value constrained to [0, 100]
Hover to see modern ➜
JDK 21+ →
Share 𝕏 🦋 in ⬡