Instant

Платформы и требования к версии: Common (2.3)

class Instant : Comparable<Instant> , Serializable

Момент времени.

Момент времени должен однозначно идентифицироваться независимо от часового пояса. Например, 1970-01-01, 00:00:00 не обозначает момент времени, поскольку это событие происходит в разное время в разных часовых поясах: человек в Токио подумает, что это уже 1970-01-01, на несколько часов раньше, чем человек в Берлине. Для представления таких сущностей используйте LocalDateTime из kotlinx-datetime. В отличие от этого, «момент, когда часы в Лондоне впервые показали 00:00 1 января 2000 года» — это конкретный момент времени, как и «1970-01-01, 00:00:00 UTC+0», поэтому его можно представить как Instant.

Instant использует шкалу времени UTC-SLS (сглаженная дополнительная секунда). Эта шкала времени не содержит моментов, соответствующих дополнительным секундам, а вместо этого «сглаживает» положительные и отрицательные дополнительные секунды на протяжении последних 1000 секунд дня, в который происходит добавление секунды.

Получение текущего момента

Основной способ получить текущий момент — использовать интерфейс Clock:

val clock: Clock = Clock.System
val instant = clock.now()

Реализация Clock.System использует системные часы платформы для получения текущего момента. Обратите внимание, что эти часы не гарантированно монотонны, и пользователь или система могут изменить их в любой момент, поэтому их не следует использовать для измерения временных интервалов. Для этого рассмотрите возможность использовать TimeSource.Monotonic и TimeMark вместо Clock.System и Instant.

Арифметические операции

Операторы plus и minus можно использовать для добавления Duration к Instant и вычитания её из него:

Clock.System.now() + 5.seconds // 5 seconds from now

Кроме того, оператор minus возвращает Duration, представляющую разницу между двумя моментами времени:

val kotlinRelease = Instant.parse("2016-02-15T12:00:00+03:00")
val kotlinStableDuration = Clock.System.now() - kotlinRelease

Особенности платформ

В JVM доступны функции расширения Instant.toJavaInstant() и java.time.Instant.toKotlinInstant() для преобразования между объектами kotlin.time и java.time, используемыми для той же цели. Аналогично, в JS доступны функции расширения Instant.toJSDate() и Date.toKotlinInstant().

По техническим причинам преобразование Instant в NSDate Foundation и обратно предоставляется в kotlinx-datetime с помощью функций расширения Instant.toNSDate() и NSDate.toKotlinInstant(). Возможно, в будущем эти функции станут доступны в kotlin.time.

Создание, сериализация и десериализация

С помощью fromEpochSeconds можно создать момент времени, указав количество секунд, прошедших с 1970-01-01T00:00:00Z (эпохи Unix). Свойства epochSeconds и nanosecondsOfSecond позволяют получить количество секунд и наносекунд, прошедших с эпохи.

val instant = Instant.fromEpochSeconds(1709898983, 123456789)
instant.epochSeconds // 1709898983
instant.nanosecondsOfSecond // 123456789

Функция fromEpochMilliseconds позволяет создать момент времени, указав количество миллисекунд, прошедших с эпохи. С помощью toEpochMilliseconds можно получить количество миллисекунд, прошедших с эпохи. Обратите внимание, что Instant поддерживает наносекундную точность, поэтому преобразование в миллисекунды приводит к потере точности.

val instant1 = Instant.fromEpochSeconds(1709898983, 123456789)
instant1.nanosecondsOfSecond // 123456789
val milliseconds = instant1.toEpochMilliseconds() // 1709898983123
val instant2 = Instant.fromEpochMilliseconds(milliseconds)
instant2.nanosecondsOfSecond // 123000000

Методы parse и toString позволяют получить Instant из строки и преобразовать его в строку в расширенном формате ISO 8601, который включает обозначение часового пояса.

val instant = Instant.parse("2023-01-02T22:35:01+01:00")
instant.toString() // 2023-01-02T21:35:01Z