Java ChronoPeriod Interface
Last modified: April 16, 2025
The java.time.chrono.ChronoPeriod interface represents a date-based
amount of time in the ISO-8601 calendar system. It models a period as a
combination of years, months, and days. ChronoPeriod is used for date-based
calculations.
ChronoPeriod is immutable and thread-safe. It works with
ChronoLocalDate implementations. The interface provides methods
to add or subtract periods from dates. It supports different calendar systems.
ChronoPeriod Interface Overview
ChronoPeriod extends TemporalAmount and provides
methods to get period components. Key operations include adding to dates,
comparing periods, and converting to other formats. The interface handles
periods in years, months, and days.
public interface ChronoPeriod extends TemporalAmount {
long get(TemporalUnit unit);
List<TemporalUnit> getUnits();
ChronoPeriod plus(TemporalAmount amountToAdd);
ChronoPeriod minus(TemporalAmount amountToSubtract);
ChronoPeriod multipliedBy(int scalar);
ChronoPeriod negated();
ChronoPeriod normalized();
boolean isZero();
boolean isNegative();
Chronology getChronology();
}
The code above shows key methods provided by ChronoPeriod. These
methods allow creating, comparing, and manipulating periods. The interface
supports operations with different calendar systems.
Creating ChronoPeriod Objects
ChronoPeriod objects are typically created using factory methods from
Period class. The between method calculates the
period between two dates. Parsing from strings is also supported.
package com.zetcode;
import java.time.LocalDate;
import java.time.Period;
import java.time.chrono.ChronoPeriod;
public class Main {
public static void main(String[] args) {
// Create from factory method
ChronoPeriod period1 = Period.of(2, 3, 10);
System.out.println("Period 1: " + period1);
// Calculate between dates
LocalDate start = LocalDate.of(2020, 1, 1);
LocalDate end = LocalDate.of(2025, 4, 15);
ChronoPeriod period2 = Period.between(start, end);
System.out.println("Period between dates: " + period2);
// Parse from string
ChronoPeriod period3 = Period.parse("P1Y2M15D");
System.out.println("Parsed period: " + period3);
}
}
This example demonstrates different ways to create ChronoPeriod objects. The
output shows periods in human-readable format. The between method
calculates the exact period between two dates.
Getting Period Components
A ChronoPeriod can be decomposed into its years, months, and days components. These values represent the amount of time in each unit. The methods are useful for displaying or processing period information.
package com.zetcode;
import java.time.Period;
import java.time.chrono.ChronoPeriod;
public class Main {
public static void main(String[] args) {
ChronoPeriod period = Period.of(3, 8, 25);
// Get individual components
System.out.println("Years: " + period.getYears());
System.out.println("Months: " + period.getMonths());
System.out.println("Days: " + period.getDays());
// Get using TemporalUnit
System.out.println("Total months: " +
period.get(java.time.temporal.ChronoUnit.MONTHS));
}
}
This example shows how to extract components from a ChronoPeriod. The
get method with TemporalUnit provides flexible
access to period components. Note that months and years are not normalized.
Adding and Subtracting Periods
ChronoPeriod supports temporal arithmetic through plus and
minus methods. These operations are useful for calculating
future or past periods. The operations maintain separate year, month, day
components.
package com.zetcode;
import java.time.Period;
import java.time.chrono.ChronoPeriod;
public class Main {
public static void main(String[] args) {
ChronoPeriod period1 = Period.of(1, 2, 15);
ChronoPeriod period2 = Period.of(0, 5, 10);
// Add periods
ChronoPeriod added = period1.plus(period2);
System.out.println("Added periods: " + added);
// Subtract periods
ChronoPeriod subtracted = period1.minus(period2);
System.out.println("Subtracted periods: " + subtracted);
// Add to date
java.time.LocalDate date = java.time.LocalDate.now();
System.out.println("Date plus period: " + date.plus(period1));
}
}
This example shows various ways to perform arithmetic with ChronoPeriod. Operations can combine periods or apply them to dates. Note that components are added separately without normalization.
Multiplying and Negating Periods
ChronoPeriod provides multipliedBy and negated
methods for scaling periods. These operations are useful for repeating
patterns or reversing period directions.
package com.zetcode;
import java.time.Period;
import java.time.chrono.ChronoPeriod;
public class Main {
public static void main(String[] args) {
ChronoPeriod period = Period.of(1, 3, 10);
// Multiply period
ChronoPeriod multiplied = period.multipliedBy(3);
System.out.println("Multiplied period: " + multiplied);
// Negate period
ChronoPeriod negated = period.negated();
System.out.println("Negated period: " + negated);
// Normalize period
ChronoPeriod normalized = Period.of(0, 15, 40).normalized();
System.out.println("Normalized period: " + normalized);
}
}
This example demonstrates scaling operations with ChronoPeriod. The
normalized method converts excess months to years. Note that
days are not converted to months during normalization.
Comparing Periods
ChronoPeriod can be compared using isZero, isNegative,
and equality checks. These comparisons are essential for validating periods or
checking for empty periods.
package com.zetcode;
import java.time.Period;
import java.time.chrono.ChronoPeriod;
public class Main {
public static void main(String[] args) {
ChronoPeriod period1 = Period.of(0, 0, 0);
ChronoPeriod period2 = Period.of(1, -2, 5);
ChronoPeriod period3 = Period.of(1, 2, 5);
System.out.println("Is period1 zero: " + period1.isZero());
System.out.println("Is period2 negative: " + period2.isNegative());
System.out.println("Are periods equal: " + period2.negated().equals(period3));
}
}
This example demonstrates various ways to compare ChronoPeriod objects. The comparison methods check individual components. Note that equality requires exact match of all components.
Working with Different Chronologies
ChronoPeriod supports different calendar systems through its
getChronology method. This allows working with non-ISO
calendars like Japanese or Thai Buddhist.
package com.zetcode;
import java.time.chrono.HijrahChronology;
import java.time.chrono.JapaneseChronology;
import java.time.chrono.ChronoPeriod;
import java.time.Period;
public class Main {
public static void main(String[] args) {
ChronoPeriod isoPeriod = Period.of(1, 2, 15);
System.out.println("ISO chronology: " + isoPeriod.getChronology());
// Create period with different chronology
ChronoPeriod hijrahPeriod = HijrahChronology.INSTANCE.period(1, 2, 15);
System.out.println("Hijrah chronology: " + hijrahPeriod.getChronology());
// Convert between chronologies
LocalDate isoDate = LocalDate.now();
LocalDate hijrahDate = HijrahChronology.INSTANCE.date(isoDate);
ChronoPeriod convertedPeriod = Period.between(
hijrahDate,
hijrahDate.plus(hijrahPeriod)
);
System.out.println("Converted period: " + convertedPeriod);
}
}
This example shows working with different calendar systems using ChronoPeriod. The interface provides consistent operations across various chronologies. Note that conversions between calendars may produce different results.
Source
Java ChronoPeriod Interface Documentation
In this article, we've covered the essential methods and features of the Java ChronoPeriod interface. Understanding these concepts is crucial for date-based calculations in modern Java applications.
Author
List all Java tutorials.