Working with Dates in Kotlin

1. Introduction 

In this quick tutorial, we’ll learn about working with dates in Kotlin.

We’ll be looking into Date-related operations such as creating, formatting and manipulating dates.

2. Creating a Date

The quickest way to create a Date object is using LocalDate‘s parse() method:

var date = LocalDate.parse("2018-12-12")

The parse() method by default uses the standard date format yyyy-MM-dd.

We can also pass our own format to parse a date String:

var formatter = DateTimeFormatter.ofPattern("dd-MM-yyyy")
var date = LocalDate.parse("31-12-2018", formatter)

And, if we need more control we can explicitly specify the year, day and month using LocalDate‘s of() method:

var date = LocalDate.of(2018, 12, 31)

3. Formatting a Date

Next, let’s look into how we can format our date objects back to Strings.

The default way of formatting Date using default format in Kotlin is invoking the toString() method.

Let’s create a date

var date = LocalDate.parse("2018-12-31")

and look at the default output of using toString:

assertThat(date.toString()).isEqualTo("2018-12-31")

This looks readable as the output format is yyyy-MM-dd, but again, we may need to format the date to custom formats depending on our use-cases.

To format our date to different formats we can use LocalDate‘s format() method and supply to it our custom format using DateTimeFormatter:

var formatter = DateTimeFormatter.ofPattern("dd-MMMM-yyyy")
var formattedDate = date.format(formatter)

This outputs a nicely formatted date:

assertThat(formattedDate).isEqualTo("31-December-2018")

4. Extracting Date Components

LocalDate provides many methods that we can use to extract specific components from Date.

Some of these are quite trivial such as extracting the year, month or day from a Date:

var date = LocalDate.parse("2018-12-31")
assertThat(date.year).isEqualTo(2018)
assertThat(date.month).isEqualTo(Month.DECEMBER)
assertThat(date.dayOfMonth).isEqualTo(31)

We can also extract other information like era, dayOfTheWeek or dayOfTheMonth:

assertThat(date.era.toString()).isEqualTo("CE")        
assertThat(date.dayOfWeek).isEqualTo(DayOfWeek.MONDAY)
assertThat(date.dayOfYear).isEqualTo(365)

5. Working with Period

Finally, let’s look into working with Periods in Kotlin.

Periods represent a distance on the timeline. We can create a Period using Period‘s class factory method:

var period = Period.of(1, 2, 3)

This creates a Period of 1 year, 2 months and 3 days.

To add this Period to an existing date, we use the LocalDate‘s  plus() method:

var date = LocalDate.of(2018, 6, 25)
var modifiedDate = date.plus(period)

This will add 1 year, 2 months and 3 days to the given date and produce the modified date:

assertThat(modifiedDate).isEqualTo("2019-08-28")

Similarly, we can subtract a Period from a given date:

var date = LocalDate.of(2018, 6, 25)
var modifiedDate = date.minus(period)

And as expected, the modified date will be:

assertThat(modifiedDate).isEqualTo("2017-04-22")

Also, we can use Periods to represent the distance between two dates.

Let’s suppose we have two dates, exactly 6 months apart from each other:

var date1 = LocalDate.parse("2018-06-25")
var date2 = LocalDate.parse("2018-12-25")

Now, we can represent the distance between these two dates using Period’s between method:

var period = Period.between(date1, date2)

The period variable will produce the following:

assertThat(period.toString()).isEqualTo("P6M")

P stands for Period and 6M means 6 months.

6. Conclusion

In this article, we have learned the basics of how to work with Dates in Kotlin.

We have looked into how to create date instances using various methods and how to format date objects back into readable texts.

Furthermore, we looked into extracting components from Date objects and finally how to work with Periods in Kotlin.

The code used in this tutorial is available over on Github.