Kotlin logo

The Kotlin Blog

Kotlin Programming Language by JetBrains

Libraries

Вышел kotlinx-datetime 0.2.0

Сегодня мы рассказываем о 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-datetime 0.2.0 по-прежнему доступна в режиме экспериментальной функциональности. API может быть изменен в любой момент.

Поддержка 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. Их можно использовать как свойства в сериализуемых классах без явных аннотаций:

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

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

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

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

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

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

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

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

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

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

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

Попробуйте!

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

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

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

Что думаете?

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

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

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

Discover more