Класс Instant

public static final Instant EPOCH

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

public static final Instant MIN

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

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

public static final Instant MAX

Максимальное поддерживаемое мгновение, '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) со значением, умноженным на 43200 (12 часов).
• DAYS - Возвращает Instant с добавлением указанного числа дней. Это эквивалентно plusSeconds(long) со значением, умноженным на 86400 (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 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.