Wrangling Dates & Time in Android

[Slide 01 - Composition of an Instant] [//]

One of the most important classes of the Date-Time library is the Instant class. As you can see here, Instant defines 3 different things. The time, the date, and the UTC which stands for Coordinated Universal Time**.** We can in fact see an Instant as a class that puts all these 3 things together.

[Slide 02 - Utility of an Instant] [//]

But what is really an Instant? Well, you can see an instant as a precise moment on the timeline. This could be nearly anything, an event tracked in the logs, the moment you received a message from a friend, or the exact time you had your first beer. It’s interesting to know that although the Instant class is based on the international standard ISO 8601, under the hood, it still uses the nanoseconds from the 1st January 1970.

Since we’re trying to represent a moment on the timeline, we need the parameters to define this exact moment. That’s why Instant defines the time and date of a moment. It’s crucial to know that it also defines a UTC but it’s always set to 0. This means you won’t be able to set any time zone or offset. Okay, now it’s time to get our hands dirty with some code.

Current Instant

As the first thing, let’s define an Instant. To do that we can simply use the static method now. In this way, you get the current moment in time. So let’s write:

val currentInstant = Instant.now()

and we can print it, so:

println("currentInstant: $currentInstant")

So, let’s run the code. In the logs, we got the current moment in ISO 8601.

• We have today’s date.
• You can see the time after the T.
• And if we take a closer look you are going to see a letter “Z” at the end of printing. This means we’re using the default time zone with the UTC set to 0.

Adding and Subtracting Time

Instant also provides methods to perform calculations. For example, we can add 10 hours to currentInstant. So let’s define another instance, which we call inTenHours.

The plus method wants 2 parameters. The first is the amount of time we want to sum, and the second is the unit of time we want to sum. In this example we want to sum 10 hours to the previous Instant, so can say 10 and HOURS.

val inTenMinutes = currentInstant.plus(10, ChronoUnit.HOURS)

To pass HOURS we relied on the ChronoUnit utility class which defines any time unit you’ll need. Now let’s sprint and run the code. As you can see we added 10 hours to the previous date.

Comparing two Dates

The Instant class defines other methods including isAfter. As you can imagine this function tells you what date is the most recent one. We can test this method on our previous instances. So write:

val isCurrentInstantAfterEpoch = currentInstant.isAfter(inTenHours)

And of course it’ll return false. Instant also defines the opposite method isBefore.

Parsing a Date and Making Calculations

Another interesting method is until. If you want to know how many days you’ve lived till now this is the method for you. First, you need to parse the date of your birthday. For this example we’ll take Marco as our case study. Marco was born on the 21 of December 2000.

val dateOfBirth = Instant.parse("2000-12-21T09:00:00.00Z")

Here the function will parse this string into an Instant object. Second we need to calculate the days.

As plus, the until method wants 2 parameters. The first is the Instant to compare, and the second is the unit of time we’ll use to compare the two instants.

val daysSinceBirth = dateOfBirth.until(Instant.now(), ChronoUnit.DAYS)

Notice this time we used the DAYS value. Let’s print and run the code.

println("daysSinceBirth: $daysSinceBirth")

And here we can find the days passed since Marco’s first breath.