Wrangling Dates & Time in Android

In the previous video, you learned all the essential concepts about the Java Date-Time library. But since you’re a Kotlin developer you need to know that the JetBrains, Kotlin’s mother, has also released its own Date-Time library written in Kotlin.

The main goals of this library are:

• Providing fewer options since Java Date-Time API offers too many classes you can choose from.
• Offering more straightforward operators that don’t fail unexpectedly if they’re allowed by the API. For example, when we try to calculate the number of months using the Duration class the code will crash unexpectedly.
• Provide support for multiplatform projects.
• Implementing Kotlin style and guidelines.

That sounds great! So why did you just follow this entire course on another library?

Well, unfortunately there’s some downsides:

• The library has been in beta version since 2020.
• To date, it doesn’t provide any utility class to format and parse dates or time.
• It doesn’t support any replacement for the OffsetDateTime and ZonedDateTime classes.

But overall it’s seems a cool library. After all, if you are building a multiplatform app, it would be nice to implement just one library, wouldn’t it? Let’s take a look at the code.

As the first thing, we need to implement the library inside our project. So open the gradle file, and inside dependencies implement the library:

implementation("org.jetbrains.kotlinx:kotlinx-datetime:0.4.0")

Now let’s sync the project. Okay, let’s go back to our file. Defining an Instant is a little different than we usually do in the Date-Time API. To do so write:

val instant = Clock.System.now()
println("instant: $instant")

You can see the result is exactly the same as the Date-Time library. Defining a time zone is really similar but we have the class TimeZone instead of ZoneId. So let’s write:

val tz = TimeZone.of("Europe/Rome")

Now we’ll create LocalDateTime. So:

val local = LocalDate(2022, Month.OCTOBER, 25)
    .atTime(2, 30)

As you can see, the LocalDate directly defines a method to add a time to the LocalDate object. atTime return a LocalDateTime instance. Notice that LocalDate doesn’t have a of the method to create an instance, but you use its constructor. Of course, we could’ve use the LocalDateTime class instead.

You can make operations in a more intuitive way. For example, if you want to add 5 hours to an Instant you can simply say:

val editedInstant = instant + 5.hours
println("editedInstant: $editedInstant")

We can calculate the difference in time between two Instants returning a duration. Let’s write:

val duration: Duration = instant - instant.minus(50, DateTimeUnit.HOUR)
println("duration: $duration")

Saying DateTimeUnit.HOUR we’re subtracting 50 hours from the first intent. The beauty of this library is that if we select MONTH, for example, we’ll get an error immediately from the compiler. In the Java Date-Time library, however, we only get the error in run-time.

Another thing the Java library doesn’t allow us to do is converting a Duration into a Period. This library, however, is really simple. Just write:

val convertedIntoPeriod = duration.toDateTimePeriod()
println("days: $convertedIntoPeriod")

To sum up, the Kotlin date-time library still misses some functions, but it’s easy to use and saves us time, and lets you write cleaner code since it defines lots of utility methods.