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

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

Проверяет, можно ли получить значение указанного поля для этого момента времени. Если это невозможно, вызовы методов 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)

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

Проверяет, можно ли прибавить указанную единицу измерения к этой дате и времени или вычесть её из них. Если это невозможно, вызовы методов 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, в котором значение наносекунд в секунде заменено указанным значением микросекунд в секунде, умноженным на 1 000. Количество секунд эпохи не изменяется.
• 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 plusSaturating(Duration duration)

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

Если результат «раньше» MIN, этот метод возвращает MIN. Если результат «позже» MAX, он возвращает MAX. В противном случае возвращается результат plus(duration).

public Instant plus(long amountToAdd, TemporalUnit unit)

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

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

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

• NANOS - возвращает экземпляр Instant с прибавленным указанным количеством наносекунд. Эквивалентно вызову plusNanos(long).
• MICROS - возвращает экземпляр Instant с прибавленным указанным количеством микросекунд. Эквивалентно вызову plusNanos(long), где величина умножена на 1 000.
• MILLIS - возвращает экземпляр Instant с прибавленным указанным количеством миллисекунд. Эквивалентно вызову plusNanos(long), где величина умножена на 1 000 000.
• SECONDS - возвращает экземпляр Instant с прибавленным указанным количеством секунд. Эквивалентно вызову plusSeconds(long).
• MINUTES - возвращает экземпляр Instant с прибавленным указанным количеством минут. Эквивалентно вызову plusSeconds(long), где величина умножена на 60.
• HOURS - возвращает экземпляр Instant с прибавленным указанным количеством часов. Эквивалентно вызову plusSeconds(long), где величина умножена на 3 600.
• 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)

Вычисляет Duration до другого Instant.

Начальной и конечной точками являются 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.