kotlinx-datetime 0.2.0 Is Out

Anastasia Shadrina

Read this post in other languages:

• Deutsch
,
• 日本語
,
• 한국어
,
• Русский
,
• 简体中文

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.

We introduced 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.

Register for the Event

Version 0.2.0 comes with a number of improvements:

• kotlinx.serialization support
• Normalization of DateTimePeriod components
• Ability to parse Instant from 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.serialization support

kotlinx-datetime provides its own types for representing date and time: such as Instant, LocalDate, and 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 Instant, LocalDate, LocalDateTime, DateTimePeriod, DatePeriod, TimeZone, and ZoneOffset. They can be used as properties in your serializable classes without explicit annotations:

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"}
}

The default serializer is based on an ISO 8601 string representation of a type and uses toString()/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.

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}}
}

There are also types that do not have a serializer: DayOfWeek and 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 kotlinx-datetime.

Normalization of DateTimePeriod components

The 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.

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

Parsing Instant from a string with a UTC offset

The 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:

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

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.

repositories {
    mavenCentral()
}

• Add kotlinx-datetime as a dependency (don’t forget to specify a source set if you’re working on a multiplatform project).

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

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.

Try out 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).

Subscribe to Kotlin Blog updates

Subscribe form

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

By submitting this form, I agree that JetBrains s.r.o. ("JetBrains") may use my name, email address, and location data to send me newsletters, including commercial communications, and to process my personal data for this purpose. I agree that JetBrains may process said data using third-party services for this purpose in accordance with the JetBrains Privacy Policy. I understand that I can revoke this consent at any time in my profile. In addition, an unsubscribe link is included in each email.

Submit

Thanks, we've got you!