ChronoUnitYEARS

ChronoUnitYEARS is a calendar-based time unit used in date-time libraries to represent a single calendar year. It is the conceptual counterpart of a year in the context of temporal calculations, distinct from a fixed-length duration such as a number of days.

Semantics and calendar basis: ChronoUnitYEARS measures complete calendar years according to a defined chronology, typically the ISO (Gregorian) calendar. Because a year can be 365 or 366 days due to leap years, the exact number of days in a ChronoUnitYEARS interval varies by year. The unit is therefore anchored in calendar arithmetic rather than a constant day count.

Usage and operations: ChronoUnitYEARS is used to add or subtract years from temporal objects and to compute the difference in whole years between two temporal values. When adding, the operation advances the year field while preserving the month and day when possible, subject to calendar rules (for example, adding a year to February 29 in a leap year results in February 28 in a non-leap year). When measuring, the between or difference calculation yields the number of complete calendar years between two dates, not merely a fixed day count.

Relationship to broader APIs: ChronoUnitYEARS is analogous to the YEARS unit in modern date-time APIs, such as the ChronoUnit.YEARS constant in Java’s time package. It interacts with ChronoLocalDate, Temporal, and Period-like constructs to support calendar-aware calculations across different chronologies.

Limitations: This unit is suitable for calendar-based questions but not for fixed-duration approximations. Across different calendar systems, the exact interpretation can vary, so clarity about the chronology in use is important. See also ChronoUnit, Temporal, and Period for related concepts.