Вышел kotlinx-datetime 0.2.0

Anastasia Shadrina

Read this post in other languages:

• English
,
• Deutsch
,
• 日本語
,
• 한국어
,
• 简体中文

Сегодня мы рассказываем о kotlinx-datetime 0.2.0 — новой версии нашей мультиплатформенной библиотеки для работы с датами и временем, которая вышла вместе с Kotlin 1.5.0. Публикация первой версии библиотеки состоялась прошлым летом, и версия 0.2.0 — наш следующий шаг на пути к релизу стабильной версии.

Библиотеку kotlinx-datetime мы представили на онлайн-конференции, посвященной Kotlin 1.4. Подробнее о ее возможностях и принципах дизайна можно узнать из выступления Ильи Горбунова.

В версии 0.2.0 вас ждут разные улучшения:

• поддержка kotlinx.serialization;
• нормализация компонентов DateTimePeriod;
• возможность обработки класса Instant в строках со смещением от UTC

Попробуйте новую версию библиотеки — для этого нужно просто установить версию Kotlin 1.5.0. А теперь подробнее о новых возможностях.

Поддержка kotlinx.serialization

kotlinx-datetime предлагает собственные типы для представления даты и времени, такие как Instant, LocalDate и TimeZone. В версии 0.2.0 все эти типы можно сериализовать, поскольку теперь их поддерживает библиотека kotlinx.serialization. В библиотеку kotlinx-datetime встроен пакет <0>kotlinx.datetime.serializers, который содержит набор сериализаторов.

Большинство типов теперь имеют сериализатор по умолчанию. Это касается типов Instant, LocalDate, LocalDateTime, DateTimePeriod, DatePeriod, TimeZone и ZoneOffset. Их можно использовать как свойства в сериализуемых классах без явных аннотаций:

<pre class="kotlin-code" style="visibility: hidden; padding: 36px 0;" data-highlight-only="true">import kotlinx.datetime.LocalDate
import kotlinx.serialization.Serializable
import kotlinx.serialization.json.Json
import kotlinx.serialization.encodeToString

@Serializable
class Person(val name: String, val birthDate: LocalDate)

fun main() {
    val harry = Person("Harry", LocalDate(1980, 7, 31))
    println(Json.encodeToString(harry))
    // {"name":"Harry","birthDate":"1980-07-31"}
}

Используемый по умолчанию сериализатор основан на строковом представлении типа, соответствующем стандарту ISO 8601, и использует для сериализации и десериализации значений метод toString()/parse().

Для некоторых типов существуют альтернативные сериализаторы. Это позволяет использовать разные стратегии сериализации, которые для отдельных форматов могут быть эффективнее, чем стратегия по умолчанию. Например, тип LocalDate можно сериализовать покомпонентно с помощью LocalDateComponentSerializer. Чтобы явно выбрать сериализатор, используйте стандартную аннотацию @Serializable(with = ...). Кроме того, можно использовать контекстный сериализатор и сделать выбор во время выполнения.

import kotlinx.datetime.LocalDate
import kotlinx.datetime.serializers.LocalDateComponentSerializer
import kotlinx.serialization.Serializable
import kotlinx.serialization.json.Json
import kotlinx.serialization.encodeToString

@Serializable
class Person(
    val name: String,
    @Serializable(with = LocalDateComponentSerializer::class)
    val birthDate: LocalDate
)

fun main() {
    val harry = Person("Harry", LocalDate(1980, 7, 31))
    println(Json.encodeToString(harry))
    // {"name":"Harry","birthday":{"year":1980,"month":7,"day":31}}
}

Для некоторых типов не существует сериализаторов: библиотека kotlinx.serialization поддерживает DayOfWeek и Month как простые перечисления.

Обратите внимание, что kotlinx.serialization — это опциональная зависимость для kotlinx-datetime. Чтобы пользоваться возможностями сериализации, добавьте в свой проект зависимость kotlinx-serialization-core для kotlinx-datetime.

Нормализация компонентов DateTimePeriod

Класс DateTimePeriod представляет период между двумя моментами времени как сочетание разных типов единиц времени: лет, месяцев, дней, часов, минут, секунд и наносекунд. Для каждого из этих типов единиц времени у DateTimePeriod есть соответствующее свойство, которое получает значение от параметра конструктора, например: <0>DateTimePeriod(months = 14, minutes = 90).

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

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

val period1 = DateTimePeriod(months = 14, minutes = 90)
val period2 = DateTimePeriod(years = 1, months = 2, hours = 1, minutes = 30)
println(period1 == period2)  // true
println(period1)             // P1Y2MT1H30M // ISO-8601
println(period2)             // P1Y2MT1H30M // ISO-8601
println(period1.years)       // 1
println(period1.months)      // 2
println(period1.days)        // 0
println(period1.hours)       // 1
println(period1.minutes)     // 30
println(period1.seconds)     // 0
println(period1.nanoseconds) // 0

Обработка класса Instant в строках со смещением от UTC

Класс Instant представляет момент времени. Библиотека позволяет выделить его из строки, которая содержит представление даты и времени, соответствующее стандарту ISO 8601.

В прежних версиях библиотеки можно было использовать только формат с указателем часового пояса Z, например, 2021-01-02T03:02:01Z. Это означало, что время указано с нулевым смещением от UTC. Теперь мы также поддерживаем время с ненулевым смещением от UТС:

val instant1 = Instant.parse("2021-01-02T03:02:01Z")
val instant2 = Instant.parse("2021-01-02T06:02:01+03:00")
println(instant1) // 2021-01-02T03:02:01Z
println(instant2) // 2021-01-02T03:02:01Z

Попробуйте!

Библиотека kotlinx-datetime 0.2.0 доступна на Maven Central. Чтобы попробовать использовать ее в вашем проекте:

• Убедитесь, что настроили Maven Central в качестве репозитория.

repositories {
    mavenCentral()
}

• Добавьте kotlinx-datetime в качестве зависимости (и не забудьте уточнить коллекцию исходных кодов для мультиплатформенных проектов).

dependencies {
    implementation("org.jetbrains.kotlinx:kotlinx-datetime:0.2.0")
}

Подробные указания по использованию библиотеки можно найти в README.

Что думаете?

Библиотека доступна в режиме экспериментальной функциональности, поэтому API еще может меняться. Мы готовим релиз стабильной версии и ждем ваших отзывов.

Попробуйте библиотеку kotlinx-datetime 0.2.0 и поделитесь с нами впечатлениями! О любых возникших проблемах сообщайте в баг-трекере проекта, а если у вас возникнут вопросы, их можно задать в Slack (для этого нужно получить приглашение).

Ваша команда Kotlin
The Drive to Develop

Subscribe to Kotlin Blog updates

Subscribe form

By submitting this form, I agree to the JetBrains Privacy Policy Notification icon

Отправляя эту форму, я разрешаю JetBrains s.r.o. («JetBrains») использовать мое имя, электронный адрес и геоданные для отправки мне новостных рассылок, включая коммерческие предложения, а также разрешаю JetBrains осуществлять обработку моих персональных данных с указанной целью. Я соглашаюсь с тем, что такая обработка может выполняться с использованием сторонних сервисов в соответствии с Политикой конфиденциальности JetBrains. Я могу в любой момент отозвать согласие в своем профиле. Кроме того, ссылка для отмены подписки содержится в каждом электронном письме.

Submit

Принято!