java.time.chrono (Java SE 15 & JDK 15)
Description: declaration: module: java.base, package: java.time.chrono
Keywords: java.time.chrono package

Module java.base

# Package java.time.chrono

Generic API for calendar systems other than the default ISO.

The main API is based around the calendar system defined in ISO-8601. However, there are other calendar systems, and this package provides basic support for them. The alternate calendars are provided in the `java.time.chrono` package.

A calendar system is defined by the `Chronology` interface, while a date in a calendar system is defined by the `ChronoLocalDate` interface.

It is intended that applications use the main API whenever possible, including code to read and write from a persistent data store, such as a database, and to send dates and times across a network. The "chrono" classes are then used at the user interface level to deal with localized input/output. See `ChronoLocalDate` for a full discussion of the issues.

Using non-ISO calendar systems in an application introduces significant extra complexity. Ensure that the warnings and recommendations in `ChronoLocalDate` have been read before working with the "chrono" interfaces.

The supported calendar systems includes:

- `Hijrah calendar`
- `Japanese calendar`
- `Minguo calendar`
- `Thai Buddhist calendar`

## Example

This example lists today's date for all of the available calendars.

       // Enumerate the list of available calendars and print today's date for each.
           Set<Chronology> chronos = Chronology.getAvailableChronologies();
           for (Chronology chrono : chronos) {
               ChronoLocalDate date = chrono.dateNow();
               System.out.printf("   %20s: %s%n", chrono.getId(), date.toString());
           }

This example creates and uses a date in a named non-ISO calendar system.

       // Print the Thai Buddhist date
           ChronoLocalDate now1 = Chronology.of("ThaiBuddhist").dateNow();
           int day = now1.get(ChronoField.DAY_OF_MONTH);
           int dow = now1.get(ChronoField.DAY_OF_WEEK);
           int month = now1.get(ChronoField.MONTH_OF_YEAR);
           int year = now1.get(ChronoField.YEAR);
           System.out.printf("  Today is %s %s %d-%s-%d%n", now1.getChronology().getId(),
                     dow, day, month, year);
       // Print today's date and the last day of the year for the Thai Buddhist Calendar.
           ChronoLocalDate first = now1
                     .with(ChronoField.DAY_OF_MONTH, 1)
                     .with(ChronoField.MONTH_OF_YEAR, 1);
           ChronoLocalDate last = first
                     .plus(1, ChronoUnit.YEARS)
                     .minus(1, ChronoUnit.DAYS);
           System.out.printf("  %s: 1st of year: %s; end of year: %s%n", last.getChronology().getId(),
                     first, last);

This example creates and uses a date in a specific ThaiBuddhist calendar system.

       // Print the Thai Buddhist date
           ThaiBuddhistDate now1 = ThaiBuddhistDate.now();
           int day = now1.get(ChronoField.DAY_OF_MONTH);
           int dow = now1.get(ChronoField.DAY_OF_WEEK);
           int month = now1.get(ChronoField.MONTH_OF_YEAR);
           int year = now1.get(ChronoField.YEAR);
           System.out.printf("  Today is %s %s %d-%s-%d%n", now1.getChronology().getId(),
                     dow, day, month, year);

       // Print today's date and the last day of the year for the Thai Buddhist Calendar.
           ThaiBuddhistDate first = now1
                     .with(ChronoField.DAY_OF_MONTH, 1)
                     .with(ChronoField.MONTH_OF_YEAR, 1);
           ThaiBuddhistDate last = first
                     .plus(1, ChronoUnit.YEARS)
                     .minus(1, ChronoUnit.DAYS);
           System.out.printf("  %s: 1st of year: %s; end of year: %s%n", last.getChronology().getId(),
                     first, last);

## Package specification

Unless otherwise noted, passing a null argument to a constructor or method in any class or interface in this package will cause a `NullPointerException` to be thrown. The Javadoc "@param" definition is used to summarise the null-behavior. The "@throws `NullPointerException`" is not explicitly documented in each method.

All calculations should check for numeric overflow and throw either an `ArithmeticException` or a `DateTimeException`.

Since:
  1.8

- Interface Summary
  Interface | Description
  --- | ---
  ChronoLocalDate | A date without time-of-day or time-zone in an arbitrary chronology, intended for advanced globalization use cases.
  ChronoLocalDateTime<D extends ChronoLocalDate> | A date-time without a time-zone in an arbitrary chronology, intended for advanced globalization use cases.
  Chronology | A calendar system, used to organize and identify dates.
  ChronoPeriod | A date-based amount of time, such as '3 years, 4 months and 5 days' in an arbitrary chronology, intended for advanced globalization use cases.
  ChronoZonedDateTime<D extends ChronoLocalDate> | A date-time with a time-zone in an arbitrary chronology, intended for advanced globalization use cases.
  Era | An era of the time-line.

- Class Summary
  Class | Description
  --- | ---
  AbstractChronology | An abstract implementation of a calendar system, used to organize and identify dates.
  HijrahChronology | The Hijrah calendar is a lunar calendar supporting Islamic calendars.
  HijrahDate | A date in the Hijrah calendar system.
  IsoChronology | The ISO calendar system.
  JapaneseChronology | The Japanese Imperial calendar system.
  JapaneseDate | A date in the Japanese Imperial calendar system.
  JapaneseEra | An era in the Japanese Imperial calendar system.
  MinguoChronology | The Minguo calendar system.
  MinguoDate | A date in the Minguo calendar system.
  ThaiBuddhistChronology | The Thai Buddhist calendar system.
  ThaiBuddhistDate | A date in the Thai Buddhist calendar system.

- Enum Summary
  Enum | Description
  --- | ---
  HijrahEra | An era in the Hijrah calendar system.
  IsoEra | An era in the ISO calendar system.
  MinguoEra | An era in the Minguo calendar system.
  ThaiBuddhistEra | An era in the Thai Buddhist calendar system.