kotlinx-datetime 0.2.0 Is Out
Today we’re exploring
kotlinx-datetime 0.2.0 — a new version of our multiplatform library for working with dates and times, which was released along with Kotlin 1.5.0. We published the very first version of the library last summer, and this is our next step on the path to a stable release.
kotlinx-datetime at the Kotlin 1.4 Online Event: you can check out this talk by Ilya Gorbunov to learn more about the design principles and features of the library. Should you have any questions about
kotlinx-datetime, we’d recommend participating in the upcoming Kotlin 1.5 Online Event and pose them to the Kotlin team.
Version 0.2.0 comes with a number of improvements:
- Normalization of
- Ability to parse
Instantfrom a string with a UTC offset
Try it out! – just make sure you have Kotlin version 1.5.0 installed. Let’s take a closer look at the features!
kotlinx-datetime provides its own types for representing date and time: such as
TimeZone. With version 0.2.0, all of these types are now serializable, as they are supported by the
kotlinx.serialization library. We provide the set of serializers in the
kotlinx.datetime.serializers package, which you can find bundled in the library.
Most of the types now have the default serializer. The types that do are
ZoneOffset. They can be used as properties in your serializable classes without explicit annotations:
The default serializer is based on an ISO 8601 string representation of a type and uses
parse() to serialize and deserialize values.
Some of the types have alternative serializers to make it possible to use different serialization strategies that can be more efficient than the default in particular formats. For example,
LocalDate can be serialized component by component using
LocalDateComponentSerializer. In order to choose a serializer explicitly, use the regular
@Serializable(with = ...) annotation. You can also defer this choice to run time using the contextual serializer.
There are also types that do not have a serializer:
Month are supported by
kotlinx.serialization as plain enums.
Keep in mind that
kotlinx.serialization is an optional dependency of
kotlinx-datetime. To use the serialization features, add the
kotlinx-serialization-core dependency to your project next to
DateTimePeriod class represents the period between 2 instants as a combination of various time unit types: years, months, days, hours, minutes, seconds, and nanoseconds. For each of those time unit types, the class has a corresponding property that receives a value from the constructor parameter, for example:
DateTimePeriod(months = 14, minutes = 90).
Previously, the components were independent and just held the values passed to the constructor. However, this could lead to cases in which two objects with different component values were not equal but had the same ISO representation. Serializing one such value and then deserializing it back could result in a value different from the original.
In this version, we changed the internal representation of
DateTimePeriod, adding a component normalization step to its constructor. The components are now internally normalized to a combination of nanoseconds, days, and months, which solves the initial issue and also makes the value returned by the component property getter easy to read even if it is large.
Instant from a string with a UTC offset
Instant class represents a moment of time. The library lets you parse it from a string with date and time representations that follow the ISO 8601 standard.
Before 0.2.0, we accepted only the format with the
Z time zone designator at the end, as in
2021-01-02T03:02:01Z for example, meaning that the time is specified in the UTC+0 offset. From now on, we support non-zero UTC offsets as well:
Give it a try
kotlinx-datetime 0.2.0 is available from Maven Central. To give it a try in your project:
- Make sure you have Maven Central set as a repository.
kotlinx-datetimeas a dependency (don’t forget to specify a source set if you’re working on a multiplatform project).
To get detailed instructions on how to use the library, please refer to our README.
Share your feedback
The library is Experimental, and the API could still change. We are on the way to a stable release and could really use your feedback.
kotlinx-datetime 0.2.0 and share your experience with us! Report any issues you encounter to the project’s issue tracker and ask any questions you have in our Slack (you can get an invite here).