compact1, compact2, compact3

java.time.temporal

Временный интерфейс

Все Суперинтерфейсы:

TemporalAccessor

Все Известные Подынтерфейсы:

ChronoLocalDate <D>, ChronoLocalDateTime <D>, ChronoZonedDateTime <D>

Все Известные Классы с реализацией:

HijrahDate, Момент, JapaneseDate, LocalDate, LocalDateTime, LocalTime, MinguoDate, OffsetDateTime, OffsetTime, ThaiBuddhistDate, Год, YearMonth, ZonedDateTime

public interface Temporal
extends TemporalAccessor

Интерфейс на уровне платформы, определяющий доступ для чтения-записи к временному объекту, такому как дата, время, смещение или некоторая комбинация их.

Это - основной тип интерфейса для даты, время и объекты смещения, которые достаточно полны, чтобы управляться, используя плюс и минус. Это реализуется теми классами, которые могут обеспечить и управлять информацией как полями или запросами. См. TemporalAccessor для версии только для чтения этого интерфейса.

Большинство даты и информации времени могут быть представлены как число. Они моделируются, используя TemporalField с числом, сохраненным, используя a long обработать большие значения. Год, месяц и день-месячного являются простыми примерами полей, но они также включают момент и смещения. См. ChronoField для стандартного набора полей.

Две части информации о дате/времени не могут быть представлены числами, хронологией и часовым поясом. Через них можно получить доступ queries использование статических методов, определенных на TemporalQuery.

Этот интерфейс является интерфейсом на уровне платформы, который не должен широко использоваться в коде программы. Вместо этого приложения должны создать и раздать экземпляры конкретных типов, такой как LocalDate. Есть много причин этого, часть которого - то, что реализации этого интерфейса могут быть в календарных системах кроме ISO. См. ChronoLocalDate для более полного обсуждения проблем.

Когда реализовать

class должен реализовать этот интерфейс, если это соответствует трем критериям:

• это обеспечивает доступ к информации о дате/времени/смещении, согласно TemporalAccessor
• набор полей непрерывен от самого большого до самого маленького
• набор полей полон, так, что никакое другое поле не необходимо, чтобы определить допустимый диапазон значений для полей, которые представляются

Четыре примера ясно дают понять это:

• LocalDate реализации этот интерфейс, поскольку это представляет ряд полей, которые непрерывны со дней к навсегда и не запрашивают внешней информации, чтобы определить законность каждой даты. Это поэтому в состоянии реализовать плюс/минус правильно.
• LocalTime реализации этот интерфейс, поскольку это представляет ряд полей, которые непрерывны от nanos до в течение дней и не запрашивают внешней информации, чтобы определить законность. Это в состоянии реализовать плюс/минус правильно, перенося день.
• MonthDay, комбинация месяца-летнего и дня-месячного, не реализует этот интерфейс. В то время как комбинация непрерывна от дней до месяцев в течение лет, у комбинации нет достаточной информации, чтобы определить допустимый диапазон значений в течение дня-месячного. Также, это неспособно реализовать плюс/минус правильно.
• День-недельного комбинации и день-месячного ("пятница 13-ое") не должны реализовать этот интерфейс. Это не представляет непрерывный набор полей как дни к недельным дням перекрытий к месяцам.

Требования реализации:

Этот интерфейс не устанавливает ограничений для переменчивости реализаций, однако неизменность строго рекомендуется. Все реализации должны быть Comparable.

С тех пор:

1.8

Сводка метода

Модификатор и Тип	Метод и Описание
default Temporal	minus(long amountToSubtract, TemporalUnit unit) Возвращает объект того же самого типа как этот объект с вычтенным установленным периодом.
default Temporal	minus(TemporalAmount amount) Возвращает объект того же самого типа как этот объект с вычтенным количеством.
long	periodUntil(Temporal endTemporal, TemporalUnit unit) Вычисляет количество времени до другого временного с точки зрения указанного модуля.
Временный	plus(long amountToAdd, TemporalUnit unit) Возвращает объект того же самого типа как этот объект с добавленным установленным периодом.
default Temporal	plus(TemporalAmount amount) Возвращает объект того же самого типа как этот объект с добавленным количеством.
default Temporal	with(TemporalAdjuster adjuster) Возвращает скорректированный объект того же самого типа как этот объект с внесенной корректировкой.
Временный	with(TemporalField field, long newValue) Возвращает объект того же самого типа как этот объект с указанным измененным полем.

Методы, наследованные от интерфейса java.time.temporal. TemporalAccessor

get, getLong, isSupported, query, range

Деталь метода

с

default Temporal with(TemporalAdjuster adjuster)

Возвращает скорректированный объект того же самого типа как этот объект с внесенной корректировкой.

Это корректирует это разовое датой согласно правилам указанного регулятора. Простой регулятор мог бы просто установить то из полей, таких как поле года. Более сложный регулятор мог бы назначить дату к прошлому дню месяца. В выборе общих корректировок обеспечивают TemporalAdjuster. Они включают обнаружение "в последний день месяца" и "следующей среды". Регулятор ответственен за обработку особых случаев, таких как переменные продолжительности месяца и високосных годов.

Некоторый пример кода, указывающий, как и почему этот метод используется:

  date = date.with(Month.JULY);        // most key classes implement TemporalAdjuster
  date = date.with(lastDayOfMonth());  // static import from Adjusters
  date = date.with(next(WEDNESDAY));   // static import from Adjusters and DayOfWeek
 

Требования реализации:

Реализации не должны изменить ни один этот объект. Вместо этого должна быть возвращена скорректированная копия оригинала. Это обеспечивает эквивалентное, безопасное поведение для неизменных и изменчивых реализаций.

Реализация по умолчанию должна вести себя эквивалентная этому коду:

  return adjuster.adjustInto(this);
 

Параметры:

adjuster - регулятор, чтобы использовать, не нуль

Возвраты:

объект того же самого типа с указанной внесенной корректировкой, не нуль

Броски:

DateTimeException - если неспособный вносить корректировку

ArithmeticException - если числовое переполнение происходит

с

Temporal with(TemporalField field,
              long newValue)

Возвращает объект того же самого типа как этот объект с указанным измененным полем.

Это возвращает новое основанное на объектах на этом со значением для указанного измененного поля. Например, на a LocalDate, это могло использоваться, чтобы установить год, месяц или день-месячного. У возвращенного объекта будет тот же самый заметный тип как этот объект.

В некоторых случаях изменение поля не полностью определяется. Например, если целевой объект является датой, представляющей 31-ого января, то изменение месяца до февраля было бы неясно. В случаях как это поле ответственно за разрешение результата. Обычно это выберет предыдущую допустимую дату, которая была бы прошлым допустимым днем февраля в этом примере.

Требования реализации:

Реализации должны проверить и обработать все поля, определенные в ChronoField. Если поле поддерживается, то корректировка должна быть выполнена. Если неподдерживающийся, то UnsupportedTemporalTypeException должен быть брошен.

Если поле не является a ChronoField, тогда результат этого метода получается, вызывая TemporalField.adjustInto(Temporal, long) передача this как первый параметр.

Реализации не должны изменить или этот объект или указанный временный объект. Вместо этого должна быть возвращена скорректированная копия оригинала. Это обеспечивает эквивалентное, безопасное поведение для неизменных и изменчивых реализаций.

Параметры:

field - поле, чтобы установить в результате, не нуле

newValue - новое значение поля в результате

Возвраты:

объект того же самого типа с указанным полевым набором, не нуль

Броски:

DateTimeException - если поле не может быть установлено

UnsupportedTemporalTypeException - если поле не поддерживается

ArithmeticException - если числовое переполнение происходит

плюс

default Temporal plus(TemporalAmount amount)

Возвращает объект того же самого типа как этот объект с добавленным количеством.

Это корректирует это временное, добавляя согласно правилам указанного количества. Количество обычно a Period но может быть любой другой тип, реализовывая TemporalAmount интерфейс, такой как Duration.

Некоторый пример кода, указывающий, как и почему этот метод используется:

  date = date.plus(period);                      // add a Period instance
  date = date.plus(duration);                    // add a Duration instance
  date = date.plus(workingDays(6));              // example user-written workingDays method
 

Отметьте тот вызов plus сопровождаемый minus как гарантируют, не возвратит разовое датой то же самое.

Требования реализации:

Реализации не должны изменить ни один этот объект. Вместо этого должна быть возвращена скорректированная копия оригинала. Это обеспечивает эквивалентное, безопасное поведение для неизменных и изменчивых реализаций.

Реализация по умолчанию должна вести себя эквивалентная этому коду:

  return amount.addTo(this);
 

Параметры:

amount - количество, чтобы добавить, не нуль

Возвраты:

объект того же самого типа с указанной внесенной корректировкой, не нуль

Броски:

DateTimeException - если дополнение не может быть сделано

ArithmeticException - если числовое переполнение происходит

плюс

Temporal plus(long amountToAdd,
              TemporalUnit unit)

Возвращает объект того же самого типа как этот объект с добавленным установленным периодом.

Этот метод возвращает новое основанное на объектах на этом с добавленным установленным периодом. Например, на a LocalDate, это могло использоваться, чтобы добавить много лет, месяцев или дней. У возвращенного объекта будет тот же самый заметный тип как этот объект.

В некоторых случаях изменение поля не полностью определяется. Например, если бы целевой объект является датой, представляющей 31-ого января, то добавление одного месяца было бы неясно. В случаях как это поле ответственно за разрешение результата. Обычно это выберет предыдущую допустимую дату, которая была бы прошлым допустимым днем февраля в этом примере.

Требования реализации:

Реализации должны проверить и обработать все модули, определенные в ChronoUnit. Если модуль поддерживается, то дополнение должно быть выполнено. Если неподдерживающийся, то UnsupportedTemporalTypeException должен быть брошен.

Если модуль не является a ChronoUnit, тогда результат этого метода получается, вызывая TemporalUnit.addTo(Temporal, long) передача this как первый параметр.

Реализации не должны изменить или этот объект или указанный временный объект. Вместо этого должна быть возвращена скорректированная копия оригинала. Это обеспечивает эквивалентное, безопасное поведение для неизменных и изменчивых реализаций.

Параметры:

amountToAdd - количество указанного модуля, чтобы добавить, может быть отрицательным

unit - модуль периода, чтобы добавить, не нуль

Возвраты:

объект того же самого типа с установленным периодом добавил, не нуль

Броски:

DateTimeException - если модуль не может быть добавлен

UnsupportedTemporalTypeException - если модуль не поддерживается

ArithmeticException - если числовое переполнение происходит

минус

default Temporal minus(TemporalAmount amount)

Возвращает объект того же самого типа как этот объект с вычтенным количеством.

Это корректирует это временное, вычитая согласно правилам указанного количества. Количество обычно a Period но может быть любой другой тип, реализовывая TemporalAmount интерфейс, такой как Duration.

Некоторый пример кода, указывающий, как и почему этот метод используется:

  date = date.minus(period);                      // subtract a Period instance
  date = date.minus(duration);                    // subtract a Duration instance
  date = date.minus(workingDays(6));              // example user-written workingDays method
 

Отметьте тот вызов plus сопровождаемый minus как гарантируют, не возвратит разовое датой то же самое.

Требования реализации:

Реализации не должны изменить ни один этот объект. Вместо этого должна быть возвращена скорректированная копия оригинала. Это обеспечивает эквивалентное, безопасное поведение для неизменных и изменчивых реализаций.

Реализация по умолчанию должна вести себя эквивалентная этому коду:

  return amount.subtractFrom(this);
 

Параметры:

amount - количество, чтобы вычесть, не нуль

Возвраты:

объект того же самого типа с указанной внесенной корректировкой, не нуль

Броски:

DateTimeException - если вычитание не может быть сделано

ArithmeticException - если числовое переполнение происходит

минус

default Temporal minus(long amountToSubtract,
                       TemporalUnit unit)

Возвращает объект того же самого типа как этот объект с вычтенным установленным периодом.

Этот метод возвращает новое основанное на объектах на этом с вычтенным установленным периодом. Например, на a LocalDate, это могло использоваться, чтобы вычесть много лет, месяцев или дней. У возвращенного объекта будет тот же самый заметный тип как этот объект.

В некоторых случаях изменение поля не полностью определяется. Например, если бы целевой объект является датой, представляющей 31-ого марта, то вычитание одного месяца было бы неясно. В случаях как это поле ответственно за разрешение результата. Обычно это выберет предыдущую допустимую дату, которая была бы прошлым допустимым днем февраля в этом примере.

Требования реализации:

Реализации должны вести себя в поместье, эквивалентном поведению метода значения по умолчанию.

Реализации не должны изменить или этот объект или указанный временный объект. Вместо этого должна быть возвращена скорректированная копия оригинала. Это обеспечивает эквивалентное, безопасное поведение для неизменных и изменчивых реализаций.

Реализация по умолчанию должна вести себя эквивалентная этому коду:

  return (amountToSubtract == Long.MIN_VALUE ?
      plus(Long.MAX_VALUE, unit).plus(1, unit) : plus(-amountToSubtract, unit));
 

Параметры:

amountToSubtract - количество указанного модуля, чтобы вычесть, может быть отрицательным

unit - модуль периода, чтобы вычесть, не нуль

Возвраты:

объект того же самого типа с вычтенным установленным периодом, не нуль

Броски:

DateTimeException - если модуль не может быть вычтен

UnsupportedTemporalTypeException - если модуль не поддерживается

ArithmeticException - если числовое переполнение происходит

periodUntil

long periodUntil(Temporal endTemporal,
                 TemporalUnit unit)

Вычисляет количество времени до другого временного с точки зрения указанного модуля.

Это вычисляет количество времени между двумя временными объектами того же самого типа с точки зрения сингла TemporalUnit. Запуск и конечные точки this и указанное временное. Результат будет отрицателен, если конец будет перед запуском. Например, период в часах между двумя временными объектами может быть вычислен, используя startTime.periodUntil(endTime, HOURS).

Вычисление возвращает целое число, представляя число полных модулей между двумя temporals. Например, период в часах между временами 11:30 и 13:29 только будет одним часом, поскольку это - одна минута за исключением двух часов.

Есть два эквивалентных способа использовать этот метод. Первое должно вызвать этот метод непосредственно. Второе должно использовать TemporalUnit.between(Temporal, Temporal):

   // these two lines are equivalent
   temporal = start.periodUntil(end, unit);
   temporal = unit.between(start, end);
 

Выбор должен быть сделан основанный, которого делает код более читаемым.

Например, этот метод позволяет числу дней между двумя датами быть вычисленным:

  long daysBetween = start.periodUntil(end, DAYS);
  // or alternatively
  long daysBetween = DAYS.between(start, end);
 

Требования реализации:

Реализации должны начать, проверяя гарантировать, что ввод временный объект имеет тот же самый заметный тип как реализация. Они должны тогда выполнить вычисление для всех экземпляров ChronoUnit. UnsupportedTemporalTypeException должен быть брошен для ChronoUnit экземпляры, которые неподдерживаются.

Если модуль не является a ChronoUnit, тогда результат этого метода получается, вызывая TemporalUnit.between(Temporal, Temporal) передача this как первый параметр и ввод, временный как второй параметр.

В сводке реализации должны вести себя способом, эквивалентным этому коду:

  // check input temporal is the same type as this class
  if (unit instanceof ChronoUnit) {
    // if unit is supported, then calculate and return result
    // else throw UnsupportedTemporalTypeException for unsupported units
  }
  return unit.between(this, endTemporal);
 

Ни этот объект, ни указанное временное, не могут быть изменены.

Параметры:

endTemporal - временный конец, того же самого типа как этот объект, не нуль

unit - модуль, чтобы измерить количество в, не нуль

Возвраты:

количество времени между этим временным объектом и указанным с точки зрения модуля; положительный, если указанный объект позже чем этот, отрицательный, если это ранее чем этот

Броски:

DateTimeException - если количество не может быть вычислено

UnsupportedTemporalTypeException - если модуль не поддерживается

ArithmeticException - если числовое переполнение происходит