Today we’re exploring

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

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

, 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

provides its own types for representing date and time: such as

,

, and

. With version 0.2.0, all of these types are now serializable, as they are supported by the

library. We provide the set of serializers in the

package, which you can find bundled in the library.

Most of the types now have the default serializer. The types that do are

,

,

,

,

,

, and

. 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

/

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,

can be serialized component by component using

. In order to choose a serializer explicitly, use the regular

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:

and

are supported by

as plain enums.

Keep in mind that

is an optional dependency of

. To use the serialization features, add the

dependency to your project next to

.

Normalization of

DateTimePeriod

components

The

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:

.

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

, 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

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

time zone designator at the end, as in

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

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

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