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