Класс Instant

public static final Instant EPOCH

Константа для момента эпохи 1970-01-01T00:00:00Z.

public static final Instant MIN

Минимальное поддерживаемое значение Instant, '-1000000000-01-01T00:00Z'. Может использоваться приложением для обозначения "далёкого прошлого".

На один год раньше минимального значения LocalDateTime. Это обеспечивает достаточные значения для обработки диапазона ZoneOffset, которые влияют на момент, помимо локального времени. Значение также выбрано таким образом, чтобы значение года помещалось в int.

public static final Instant MAX

Максимальное поддерживаемое значение Instant, '1000000000-12-31T23:59:59.999999999Z'. Может использоваться приложением для обозначения "далёкого будущего".

На один год позже максимального значения LocalDateTime. Это обеспечивает достаточные значения для обработки диапазона ZoneOffset, которые влияют на момент, помимо локального времени. Значение также выбрано таким образом, чтобы значение года помещалось в int.

public static Instant now()

Получает текущий момент времени из системных часов.

Для получения текущего момента будет запрошен system UTC clock.

Использование этого метода предотвращает возможность использования альтернативного источника времени для тестирования, так как часы фактически жёстко закодированы.

public static Instant now(Clock clock)

Получает текущий момент времени из указанных часов.

Будет запрошен указанный объект часов для получения текущего времени.

Использование этого метода позволяет использовать альтернативные часы для тестирования. Альтернативные часы могут быть введены с помощью dependency injection.

public static Instant ofEpochSecond(long epochSecond)

Получает экземпляр Instant, используя секунды от эпохи 1970-01-01T00:00:00Z.

Поле наносекунд установлено в ноль.

public static Instant ofEpochSecond(long epochSecond, long nanoAdjustment)

Получает экземпляр Instant, используя секунды от эпохи 1970-01-01T00:00:00Z и наносекундную дробную часть секунды.

Этот метод позволяет передавать произвольное количество наносекунд. Фабрика изменит значения секунд и наносекунд, чтобы гарантировать, что хранимые наносекунды находятся в диапазоне от 0 до 999 999 999. Например, следующие значения приведут к точно такому же моменту времени:

  Instant.ofEpochSecond(3, 1);
  Instant.ofEpochSecond(4, -999_999_999);
  Instant.ofEpochSecond(2, 1000_000_001);
 

public static Instant ofEpochMilli(long epochMilli)

Получает экземпляр Instant, используя миллисекунды от эпохи 1970-01-01T00:00:00Z.

Секунды и наносекунды извлекаются из указанных миллисекунд.

public static Instant from(TemporalAccessor temporal)

Получает экземпляр Instant из временного объекта.

Получает момент времени, основываясь на указанном временном объекте. TemporalAccessor представляет собой произвольный набор данных о дате и времени, который эта фабрика преобразует в экземпляр Instant.

Преобразование извлекает поля INSTANT_SECONDS и NANO_OF_SECOND.

Этот метод соответствует сигнатуре функционального интерфейса TemporalQuery, позволяя использовать его в качестве запроса через ссылку на метод, Instant::from.

public static Instant parse(CharSequence text)

Получает экземпляр Instant из текстовой строки, такой как 2007-12-03T10:15:30.00Z.

Строка должна представлять собой допустимый момент времени в UTC и анализируется с помощью DateTimeFormatter.ISO_INSTANT.

public boolean isSupported(TemporalField field)

Проверяет, поддерживается ли указанное поле.

Проверяет, можно ли запросить этот момент времени для указанного поля. Если false, то вызов методов range, get и with(TemporalField, long) вызовет исключение.

Если поле является ChronoField, то запрос реализуется здесь. Поддерживаемые поля:

• NANO_OF_SECOND
• MICRO_OF_SECOND
• MILLI_OF_SECOND
• INSTANT_SECONDS

Все остальные ChronoField экземпляры вернут false.

Если поле не является ChronoField, результат этого метода получается вызовом TemporalField.isSupportedBy(TemporalAccessor), передавая this в качестве аргумента. Поддержка поля определяется самим полем.

public boolean isSupported(TemporalUnit unit)

Проверяет, поддерживается ли указанная единица измерения.

Проверяет, можно ли добавить или вычесть указанную единицу измерения из этого момента времени. Если false, вызов методов plus(long, TemporalUnit) и minus вызовет исключение.

Если единица измерения является ChronoUnit, запрос реализуется здесь. Поддерживаемые единицы измерения:

• NANOS
• MICROS
• MILLIS
• SECONDS
• MINUTES
• HOURS
• HALF_DAYS
• DAYS

Все остальные ChronoUnit экземпляры вернут false.

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

public ValueRange range(TemporalField field)

Получает диапазон допустимых значений для указанного поля.

Объект диапазона выражает минимальное и максимальное допустимые значения для поля. Этот момент используется для повышения точности возвращаемого диапазона. Если невозможно вернуть диапазон, потому что поле не поддерживается или по какой-либо другой причине, выбрасывается исключение.

Если поле является ChronoField, то запрос реализуется здесь. supported fields вернёт соответствующие экземпляры диапазона. Все другие ChronoField экземпляры будут выбрасывать UnsupportedTemporalTypeException.

Если поле не является ChronoField, то результат этого метода получается путём вызова TemporalField.rangeRefinedBy(TemporalAccessor), передавая this в качестве аргумента. Возможно ли получить диапазон определяется полем.

public int get(TemporalField field)

Получает значение указанного поля из этого момента как int.

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

Если поле является ChronoField, то запрос реализуется здесь. supported fields вернёт допустимые значения на основе этой даты и времени, за исключением INSTANT_SECONDS, которое слишком велико для int и выбрасывает DateTimeException. Все другие ChronoField экземпляры будут выбрасывать UnsupportedTemporalTypeException.

Если поле не является ChronoField, то результат этого метода получается путём вызова TemporalField.getFrom(TemporalAccessor), передавая this в качестве аргумента. Возможно ли получить значение, и что оно представляет собой, определяется полем.

public long getLong(TemporalField field)

Получает значение указанного поля из этого момента как long.

Это запрос этого момента для значения указанного поля. Если невозможно вернуть значение, потому что поле не поддерживается или по какой-либо другой причине, выбрасывается исключение.

Если поле является ChronoField, то запрос реализуется здесь. supported fields вернёт допустимые значения на основе этой даты и времени. Все другие ChronoField экземпляры будут выбрасывать UnsupportedTemporalTypeException.

Если поле не является ChronoField, то результат этого метода получается путём вызова TemporalField.getFrom(TemporalAccessor), передавая this в качестве аргумента. Возможно ли получить значение, и что оно представляет собой, определяется полем.

public long getEpochSecond()

Получает количество секунд с эпохи Java 1970-01-01T00:00:00Z.

Счётчик эпохи секунд — это простой счётчик секунд, где секунда 0 — 1970-01-01T00:00:00Z. Часть наносекунд возвращается методом getNano().

public int getNano()

Получает количество наносекунд, последующих по времени, с начала секунды.

Значение наносекунд-в-секунде измеряет общее количество наносекунд с секунды, возвращённой методом getEpochSecond().

public Instant with(TemporalAdjuster adjuster)

Возвращает скопированную изменённую копию этого момента.

Это возвращает Instant, основанную на этой, с изменённым моментом. Изменение выполняется с использованием указанной стратегии корректировки. Прочитайте документацию корректировщика, чтобы понять, какое изменение будет выполнено.

Результат этого метода получается вызовом метода TemporalAdjuster.adjustInto(Temporal) на указанном корректировщике, передавая this в качестве аргумента.

Этот экземпляр неизменяем и не затрагивается этим вызовом метода.

public Instant with(TemporalField field, long newValue)

Возвращает копию этого момента с указанным полем, установленным на новое значение.

Это возвращает Instant, основанную на этой, со значением для указанного поля, изменённым. Если невозможно установить значение, потому что поле не поддерживается или по какой-либо другой причине, выбрасывается исключение.

Если поле является ChronoField, то корректировка реализуется здесь. Поддерживаемые поля ведут себя следующим образом:

• NANO_OF_SECOND - Возвращает Instant с указанным наносекунд-в-секунде. Эпоха-секунда останется неизменной.
• MICRO_OF_SECOND - Возвращает Instant с наносекунд-в-секунде, заменёнными на указанные микросекунд-в-секунде, умноженными на 1000. Эпоха-секунда останется неизменной.
• MILLI_OF_SECOND - Возвращает Instant с наносекунд-в-секунде, заменёнными на указанные миллисекунд-в-секунде, умноженными на 1 000 000. Эпоха-секунда останется неизменной.
• INSTANT_SECONDS - Возвращает Instant с указанной эпоха-секундой. Наносекунд-в-секунде останутся неизменными.

Во всех случаях, если новое значение находится вне допустимого диапазона значений для поля, будет выброшено DateTimeException.

Все остальные ChronoField экземпляры будут выбрасывать UnsupportedTemporalTypeException.

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

Этот экземпляр неизменяем и не затрагивается этим вызовом метода.

public Instant truncatedTo(TemporalUnit unit)

Возвращает копию этого Instant, усечённую до указанного единицы измерения.

Усечение момента возвращает копию исходного с полями, меньшими, чем указанная единица, установленные в ноль. Поля рассчитываются на основе использования смещения UTC, как видно в toString. Например, усечение с помощью единицы MINUTES округляет вниз до ближайшей минуты, устанавливая секунды и наносекунды в ноль.

Единица должна иметь продолжительность, которая делится на длину стандартного дня без остатка. Это включает все предоставленные единицы времени в ChronoUnit и DAYS. Другие единицы вызовут исключение.

Этот экземпляр неизменяем и не затрагивается этим вызовом метода.

public Instant plus(TemporalAmount amountToAdd)

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

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

Вычисление делегируется объекту значения вызовом TemporalAmount.addTo(Temporal). Реализация значения свободна реализовывать добавление как угодно, но обычно она обращается к plus(long, TemporalUnit). Обратитесь к документации реализации значения, чтобы определить, можно ли его успешно добавить.

Этот экземпляр неизменяемый и не изменяется этим вызовом метода.

public Instant plus(long amountToAdd, TemporalUnit unit)

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

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

Если поле является ChronoUnit, то добавление реализуется здесь. Поддерживаемые поля ведут себя следующим образом:

• NANOS - Возвращает Instant с добавлением указанного количества наносекунд. Это эквивалентно plusNanos(long).
• MICROS - Возвращает Instant с добавлением указанного количества микросекунд. Это эквивалентно plusNanos(long) со значением, умноженным на 1000.
• MILLIS - Возвращает Instant с добавлением указанного количества миллисекунд. Это эквивалентно plusNanos(long) со значением, умноженным на 1 000 000.
• SECONDS - Возвращает Instant с добавлением указанного количества секунд. Это эквивалентно plusSeconds(long).
• MINUTES - Возвращает Instant с добавлением указанного количества минут. Это эквивалентно plusSeconds(long) со значением, умноженным на 60.
• HOURS - Возвращает Instant с добавлением указанного количества часов. Это эквивалентно plusSeconds(long) со значением, умноженным на 3600.
• HALF_DAYS - Возвращает Instant с добавлением указанного количества полусуток. Это эквивалентно plusSeconds(long) со значением, умноженным на 43 200 (12 часов).
• DAYS - Возвращает Instant с добавлением указанного количества дней. Это эквивалентно plusSeconds(long) со значением, умноженным на 86 400 (24 часа).

Все остальные ChronoUnit экземпляры будут выбрасывать UnsupportedTemporalTypeException.

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

Этот экземпляр неизменяемый и не изменяется этим вызовом метода.

public Instant plusSeconds(long secondsToAdd)

Возвращает копию этого момента времени с добавлением указанной продолжительности в секундах.

Этот экземпляр неизменяемый и не изменяется этим вызовом метода.

public Instant plusMillis(long millisToAdd)

Возвращает копию этого момента времени с добавлением указанной продолжительности в миллисекундах.

Этот экземпляр неизменяемый и не изменяется этим вызовом метода.

public Instant plusNanos(long nanosToAdd)

Возвращает копию этого момента времени с добавлением указанной продолжительности в наносекундах.

Этот экземпляр неизменяемый и не изменяется этим вызовом метода.

public Instant minus(TemporalAmount amountToSubtract)

Возвращает копию этого момента времени с вычитанием указанного значения.

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

Вычисление делегируется объекту значения вызовом TemporalAmount.subtractFrom(Temporal). Реализация значения свободна реализовывать вычитание как угодно, но обычно она обращается к minus(long, TemporalUnit). Обратитесь к документации реализации значения, чтобы определить, можно ли его успешно вычесть.

Этот экземпляр неизменяемый и не изменяется этим вызовом метода.

public Instant minus(long amountToSubtract, TemporalUnit unit)

Возвращает копию этого момента времени с вычитанием указанного значения.

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

Этот метод эквивалентен plus(long, TemporalUnit) с отрицательным значением. Смотрите этот метод для полного описания того, как работает добавление, и, следовательно, вычитание.

Этот экземпляр неизменяемый и не изменяется этим вызовом метода.

public Instant minusSeconds(long secondsToSubtract)

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

Этот экземпляр неизменяемый и не изменяется этим вызовом метода.

public Instant minusMillis(long millisToSubtract)

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

Этот объект неизменяемый и не изменяется в результате вызова этого метода.

public Instant minusNanos(long nanosToSubtract)

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

Этот объект неизменяемый и не изменяется в результате вызова этого метода.

public <R> R query(TemporalQuery<R> query)

Запрашивает этот момент времени с использованием указанного запроса.

Запрашивает этот момент времени с использованием указанного объекта стратегии запроса. Объект TemporalQuery определяет логику получения результата. Прочитайте документацию запроса, чтобы понять, каким будет результат этого метода.

Результат этого метода получается путем вызова метода TemporalQuery.queryFrom(TemporalAccessor) на указанном запросе, передав this в качестве аргумента.

public Temporal adjustInto(Temporal temporal)

Настраивает указанный объект временной шкалы так, чтобы он содержал этот момент времени.

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

Настройка эквивалентна двукратному использованию Temporal.with(TemporalField, long), передав ChronoField.INSTANT_SECONDS и ChronoField.NANO_OF_SECOND в качестве полей.

В большинстве случаев более понятно использовать обратный порядок вызова с помощью Temporal.with(TemporalAdjuster):

   // these two lines are equivalent, but the second approach is recommended
   temporal = thisInstant.adjustInto(temporal);
   temporal = temporal.with(thisInstant);
 

Этот объект неизменяемый и не изменяется в результате вызова этого метода.

public long until(Temporal endExclusive, TemporalUnit unit)

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

Вычисляет количество времени между двумя объектами Instant в терминах одной TemporalUnit. Начальная и конечная точки - это this и указанный момент времени. Результат будет отрицательным, если конец предшествует началу. Вычисление возвращает целое число, представляющее количество полных единиц между двумя моментами времени. Temporal, переданные в этот метод, преобразуются в Instant с помощью from(TemporalAccessor). Например, количество секунд между двумя датами можно рассчитать с помощью startInstant.until(endInstant, SECONDS).

Существуют два равнозначных способа использования этого метода. Первый - вызвать этот метод. Второй - использовать TemporalUnit.between(Temporal, Temporal):

   // these two lines are equivalent
   amount = start.until(end, SECONDS);
   amount = SECONDS.between(start, end);
 

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

Вычисление реализовано в этом методе для ChronoUnit. Поддерживаются единицы NANOS, MICROS, MILLIS, SECONDS, MINUTES, HOURS, HALF_DAYS и DAYS. Другие значения ChronoUnit вызовут исключение.

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

Этот объект неизменяемый и не изменяется в результате вызова этого метода.

public Duration until(Instant endExclusive)

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

Начальная и конечная точки - это this и указанный момент времени. Результат будет отрицательным, если конец предшествует началу. Вызов этого метода эквивалентен Duration.between(this, endExclusive).

Этот объект неизменяемый и не изменяется в результате вызова этого метода.

public OffsetDateTime atOffset(ZoneOffset offset)

Объединяет этот момент времени со смещением, чтобы создать OffsetDateTime.

Возвращает OffsetDateTime, сформированный из этого момента времени со смещением от UTC/Гринвича. Если момент времени слишком большой, чтобы поместиться в дату-время со смещением, будет выброшено исключение.

Этот метод эквивалентен OffsetDateTime.ofInstant(this, offset).

public ZonedDateTime atZone(ZoneId zone)

Объединяет этот момент времени с часовым поясом, чтобы создать ZonedDateTime.

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

Этот метод эквивалентен ZonedDateTime.ofInstant(this, zone).

public long toEpochMilli()

Преобразует этот момент времени в количество миллисекунд от эпохи 1970-01-01T00:00:00Z.

Если этот момент времени представляет точку на временной шкале, которая слишком далеко расположена в будущем или прошлом, чтобы поместиться в long миллисекунд, то генерируется исключение.

Если этот момент времени имеет точность больше, чем миллисекунда, то при преобразовании любая избыточная информация о точности будет отброшена так, как если бы количество наносекунд было подвергнуто целочисленному делению на миллион.

public int compareTo(Instant otherInstant)

Сравнивает этот момент времени с указанным моментом времени.

Сравнение основано на позиции моментов времени на временной шкале. Оно «совместимо с equals», как определено в Comparable.

public boolean isAfter(Instant otherInstant)

Проверяет, следует ли этот момент времени после указанного момента времени.

Сравнение основано на позиции моментов времени на временной шкале.

public boolean isBefore(Instant otherInstant)

Проверяет, предшествует ли этот момент времени указанному моменту времени.

Сравнение основано на позиции моментов времени на временной шкале.

public boolean equals(Object other)

Проверяет, равен ли этот момент времени указанному моменту времени.

Сравнение основано на позиции моментов времени на временной шкале.

public int hashCode()

Возвращает хэш-код для этого момента времени.

public String toString()

Строковое представление этого момента времени с использованием представления ISO-8601.

Используемый формат совпадает с DateTimeFormatter.ISO_INSTANT.