Класс 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)

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

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

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

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

public Instant with(TemporalField field, long newValue)

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

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

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

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

Во всех случаях, если новое значение выходит за допустимый диапазон значений для поля, будет выброшено исключение 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)

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

Возвращает скопированное значение, основанное на этом, с добавленным указанным значением. Значение, как правило, 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.