* Access to date and time using fields and units, additional value type classes and * base support for calendar systems other than the default ISO. *
** This package expands on the base package to provide additional functionality for * more powerful use cases. Support is included for: *
** Dates and times are expressed in terms of fields and units. * A unit is used to measure an amount of time, such as years, days or minutes. * All units implement {@link java.time.temporal.TemporalUnit}. * The set of well known units is defined in {@link java.time.temporal.ChronoUnit}, such as {@code DAYS}. * The unit interface is designed to allow applications defined units. *
** A field is used to express part of a larger date-time, such as year, month-of-year or second-of-minute. * All fields implement {@link java.time.temporal.TemporalField}. * The set of well known fields are defined in {@link java.time.temporal.ChronoField}, such as {@code HOUR_OF_DAY}. * Additional fields are defined by {@link java.time.temporal.JulianFields}, {@link java.time.temporal.WeekFields} * and {@link java.time.temporal.ISOFields}. * The field interface is designed to allow applications defined fields. *
** This package provides tools that allow the units and fields of date and time to be accessed * in a general way most suited for frameworks. * {@link java.time.temporal.Temporal} provides the abstraction for date time types that support fields. * Its methods support getting the value of a field, creating a new date time with the value of * a field modified, and querying for additional information, typically used to extract the offset or time-zone. *
** One use of fields in application code is to retrieve fields for which there is no convenience method. * For example, getting the day-of-month is common enough that there is a method on {@code LocalDate} * called {@code getDayOfMonth()}. However for more unusual fields it is necessary to use the field. * For example, {@code date.get(ChronoField.ALIGNED_WEEK_OF_MONTH)}. * The fields also provide access to the range of valid values. *
* ** A key part of the date-time problem space is adjusting a date to a new, related value, * such as the "last day of the month", or "next Wednesday". * These are modeled as functions that adjust a base date-time. * The functions implement {@link java.time.temporal.TemporalAdjuster} and operate on {@code Temporal}. * A set of common functions are provided in {@link java.time.temporal.Adjusters}. * For example, to find the first occurrence of a day-of-week after a given date, use * {@link java.time.temporal.Adjusters#next(DayOfWeek)}, such as * {@code date.with(next(MONDAY))}. * Applications can also define adjusters by implementing {@code TemporalAdjuster}. *
** There are additional interfaces to model addition to and subtraction from a date-time. * These are {@link java.time.temporal.TemporalAdder} and {@link java.time.temporal.TemporalSubtractor}. *
** In addition to adjusting a date-time, an interface is provided to enable querying - * {@link java.time.temporal.TemporalQuery}. * The most common implementations of the query interface are method references. * The {@code from(TemporalAccessor)} methods on major classes can all be used, such as * {@code LocalDate::from} or {@code Month::from}. * Further implementations are provided in {@link java.time.temporal.Queries}. * Applications can also define queries by implementing {@code TemporalQuery}. *
* ** Different locales have different definitions of the week. * For example, in Europe the week typically starts on a Monday, while in the US it starts on a Sunday. * The {@link java.time.temporal.WeekFields} class models this distinction. *
** The ISO calendar system defines an additional week-based division of years. * This defines a year based on whole Monday to Monday weeks. * This is modeled in {@link java.time.temporal.ISOFields}. *
* ** 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 {@code java.time.calendar} package. *
** A calendar system is defined by the {@link java.time.temporal.Chrono} interface, * while a date in a calendar system is defined by the {@link java.time.temporal.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. *
** Using non-ISO calendar systems in an application introduces significant extra complexity. * Ensure that the warnings and recommendations in {@code ChronoLocalDate} have been read before * working with the "chrono" interfaces. *
** This example creates and uses a date in a non-ISO calendar system. *
*
* // Print the Thai Buddhist date
* ChronoLocalDate<ThaiBuddhistChrono> now1 = ThaiBuddhistChrono.INSTANCE.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.getChrono().getId(),
* dow, day, month, year);
*
* // Enumerate the list of available calendars and print today for each
* Set<Chrono<?>> chronos = Chrono.getAvailableChronologies();
* for (Chrono<?> chrono : chronos) {
* ChronoLocalDate<?> date = chrono.dateNow();
* System.out.printf(" %20s: %s%n", chrono.getId(), date.toString());
* }
*
* // Print today's date and the last day of the year for the Thai Buddhist Calendar.
* ChronoLocalDate<ThaiBuddhistChrono> first = now1
* .with(ChronoField.DAY_OF_MONTH, 1)
* .with(ChronoField.MONTH_OF_YEAR, 1);
* ChronoLocalDate<ThaiBuddhistChrono> last = first
* .plus(1, ChronoUnit.YEARS)
* .minus(1, ChronoUnit.DAYS);
* System.out.printf(" %s: 1st of year: %s; end of year: %s%n", last.getChrono().getId(),
* first, last);
*
*
* * Unless otherwise noted, passing a null argument to a constructor or method in any class or interface * in this package will cause a {@link java.lang.NullPointerException NullPointerException} to be thrown. * The Javadoc "@param" definition is used to summarise the null-behavior. * The "@throws {@link java.lang.NullPointerException}" is not explicitly documented in each method. *
** All calculations should check for numeric overflow and throw either an {@link java.lang.ArithmeticException} * or a {@link java.time.DateTimeException}. *
* @since JDK1.8 */ package java.time.temporal;