Mastering Date and Time Handling in Kotlin for Android Developers

The software industry has evolved more quickly in 10 years than most industries do in 1,000, yet we continue to grapple with the basic elements of date and time. Practically all our apps rely on time in some way, and when our users are spread all over the world it can be fiendishly difficult to get the timestamps right.

Kotlin language, the dominant Android programming language, provides native classes (or blueprints) to help us deal with date and time. However, we need to consider a number of nuances such as:

• Initializing dates.
• Converting formats.
• Extracting components.
• Performing advanced manipulations.
• Generating timestamps.
• Harnessing the power of kotlinx-datetime.

This article will consider all of the above points, with hands-on examples and practical scenarios to fully grasp Kotlin’s date-time capabilities tailored for Android developers.

Another important topic in Android development is data management. If you are interested in learning more about this topic, you can read our article on Kotlin Collections.

Chapter 1: Mastering LocalDate in Kotlin

LocalDate allows us to create a local instance of a date based on the year, month and day, without a timezone.

So we’re going to begin by unpacking the nuances of LocalDate, from simple string-to-date conversions to custom date formats tailored for diverse audiences, using  real-world coding examples.

If your Android app has to deal with dates and will be used worldwide, having a remote logging tool can be really handy. It can help you debug problems when dealing with different time zones and date formats.

Quick Date Creation

From String to Date with parse()

Scenario: Imagine a travel app: it needs to turn users’ inputs into workable date objects, thereby streamlining the reservation process. This is where the parse() function, one of the key elements of LocalDate , comes in.

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

Parse Custom Date String Formats to LocalDate with DateTimeFormatter

Scenario: Picture an international health or fitness app, with users from various regions logging their milestones. Here we need to take LocalDate a stage further and create an adaptable date format, to ensure consistent readability, irrespective of location. We achieve this by adding a new class, DateTimeFormatter, and selecting the pattern we want.

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

Builing Dates Component-by-Component

Scenario: In budgeting apps, users set goals for specific durations. We need to give users the freedom to create fixed dates from individual elements, to ensure precise financial insights.

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

Streamlining Date Displays

Consistent Date Format

Scenario: For scheduling apps (such as calendars or booking platforms), users need to be able to identify and reserve times effortless. So we need to give them a standard date display.

val formattedDate = date.format(DateTimeFormatter.ofPattern("yyyy-MM-dd"))

Extracting Date Parts

Isolating Date Elements

Scenario: Consider a birthday app. For notifications, we’d want to extract the day and month but withhold the year.

val dayOfMonth = date.dayOfMonth
val month = date.month

If you are interested in learning Android development with Kotlin we have an article that will cover your needs and list the best resources to learn Android development.

Chapter 2: Working with Kotlin Dates for Android Apps

Now let’s get to the core of managing dates in Kotlin for Android.

Each type of app will have its own particular date requirements depending on its specific use case. In this chapter, you’ll learn how to handle each of them using specific Kotlin date functions.

We’ll begin with the Period class, which shows you how to express dates in periods of time rather than static figures.

Understanding Kotlin’s Period for Time Intervals

We’ve already covered the challenge of expressing dates in absolute terms, i.e. a single static figure containing the day, month and year. But what about when you have to define a date in relative terms; in other words, by its proximity to an earlier date? Kotlin’s Period class enables you to do this and make your reminders more accurate and helpful.

Introducing Periods

Scenario: In an event management app, users may set reminders like ‘10 days before the concert.’ Using Period, you can make these reminders more accurate and helpful. val period = Period.of(0, 0, 10)

Manipulating Android Kotlin Dates with Periods

Scenario: In subscription-based apps, such as a premium news app, users need timely reminders about renewals. By adding the period to the subscription start date, we can give users these essential alerts in advance.

val startDate = LocalDate.of(2018, 6, 25) val endDate = startDate.plus(period)

Fetching Current Dates and Times in Kotlin for Android

Whether you’re working on a messaging app or a daily planner, you’ll need to access the current date and time occasionally. Kotlin provides you with methods to do this and meet your Android app needs.

Leveraging Kotlin’s now() function

Scenario: For social media apps, timestamps on posts or comments help users keep track of the conversation flow. Here’s what that looks like in code.

val currentDate = LocalDate.now() val currentDateTime = LocalDateTime.now()

Using Java’s Calendar in Kotlin Apps

Scenario: If you’ve got an older app and are transitioning from Java to Kotlin, the Java Calendar method might be more familiar, ensuring a smooth transition phase.

val currentTime = Calendar.getInstance().time

Opting for Traditional java.util.Date in Kotlin

Scenario: In certain e-commerce apps, especially those interfacing with legacy systems, the Date() method might be the go-to choice for compatibility reasons.

val current = Date()

Chapter 3: Mastering Timestamps in Kotlin for Android Apps

Now let’s go a bit further back. In fact we’re going to go right back to the beginning of recorded time… or at least the Android version.

January 1, 1970 is Android’s main reference-point when it comes to logging specific moments. In fact, all timestamps are denoted by the number of milliseconds that have elapsed since this date. These timestamps are used for everything from track in-app interactions to comparing datapoints.

Kotlin’s smooth compatibility with Java, which has a whole variety of methods for handling timestamps, gives developers more options. Here’s how to make the most of them.

Using java.util.Date for Timestamps in Kotlin

java.util.Date is the classic way to use and interpret timestamps with Java. It’s been around for years and developers love its simplicity.

Creating Timestamps with java.util.Date: Scenario: Imagine a fitness app where users log workouts. By capturing the exact moment a workout starts and ends, the app can provide accurate session durations.

val date = Date()
val currentTimestamp: Long = date.time

Modern Timestamp Techniques with Kotlin & java.time

Now let’s look at the java.time package in Java 8, which has been around since 2014. java.time provides Kotlin developers with an enhanced set of tools for date-time management, and is particularly useful for harmonizing timestamps across multiple locations.

Consistent Timestamps with java.time:

Scenario: Imagine a messaging app that connects users globally. Alice, from London, sends a message at her local time of 3pm. Bob, in Tokyo, should see that message timestamped appropriately to his local time.

With java.time, the app can ensure that the message timestamp is consistent and accurately represents the send time across all time zones. This way, regardless of where users are, they’ll experience messages in the correct sequence and context.

// Acquiring the current time instant in UTC
val currentInstant = Instant.now()

// Converting the instant to a local date-time based on a specific time zone
val londonTime = currentInstant.atZone(ZoneId.of("Europe/London"))
val tokyoTime = currentInstant.atZone(ZoneId.of("Asia/Tokyo"))

Debugging in Kotlin Multiplatform is easy, as you can use typical tools like adding breakpoints and printing logs in the console. Learn more on how to debug Kotlin Android applications in the following article:

Chapter 4: Kotlin’s Multiplatform DateTime Library: A Deep Dive

In 2020 JetBrains, the creators of Kotlin, introduced [kotlinx-datetime](<https://github.com/Kotlin/kotlinx-datetime>), a multiplatform library. Built on top of java.time, it goes a stage further and gives Kotlin developers a comprehensive set of tools for dealing with date and time operations.

From scheduling tasks in apps to analyzing time-based data, understanding date-time operations is crucial for various applications.

Setting the Scene with kotlinx-datetime

Before diving into the capabilities of kotlinx-datetime, you need to get it up and running in your Kotlin project.

1. Make sure the Kotlin Multiplatform Plugin is integrated.
2. Introduce the dependency to the mix: implementation "org.jetbrains.kotlinx:kotlinx-datetime:x.y.z" // Ensure to replace x.y.z with the latest version available.

Design Philosophy

Here are some key principles that will help you understand kotlinx-datetime.

• Pragmatism: The library targets various common issues that developers encounter with dates and times.
• Convenience Over Generality: Kotlinx-datetimeis designed for most use-cases, sacrificing some domain-specific utilities.
• Clear Boundary: There is a distinct separation between physical time and geographically specific civil time (the time in a particular part of the world). The library avoids mixing both.
• Standard Adherence: Built on the ISO 8601 standard, there o support for non-ISO date-time formats or localization.

Practical Applications with Core Data Types in Android

And finally, here is a selection of core data types and how they relate to kotlinx-datetime.

An instant represents a specific moment on the UTC-SLS timeline.

Usage Scenario: The recording generated when a user submits a form:

val formSubmissionTime = Clock.System.now()

LocalDateTime is a combination of date and time, minus timezone specifics.

Usage Scenario: A reminder to users of an upcoming appointment:

val appointmentReminder = LocalDateTime(2023, 11, 5, 15, 30)

LocalDate centers on the date.

Usage Scenario: Capturing a user’s date of birth:

val userDOB = LocalDate(1995, 5, 12)

LocalTime isolates time and omits the date.

Usage Scenario: Setting an alarm in local time:

val wakeUpCall = LocalTime(7, 0) // 7:00 AM

Employing Common Date-Time Operations in Android Apps

Here are some typical use cases in the apps we build everyday.

Translating an Instant to Local Date-Time

Adjusting notifications to align with a user’s local timezone:

val userTimezone = TimeZone.currentSystemDefault()
val userNotificationTime = formSubmissionTime.toLocalDateTime(userTimezone)

Date Arithmetic Operations

Notifying users of events, for instance, a sale that wraps up in 3 days:

val saleEndReminder = Clock.System.todayIn(TimeZone.currentSystemDefault()).plus(3, DateTimeUnit.DateBased.DAY)

Learn about Kotlin Coroutines in Android development through our hands-on guide to building a Recipe Finder App. It’s practical and informative for developers.

Chapter 5: Navigating the Depths of Kotlin’s Date & Time for Android

Elevate your Android development by delving deep into Kotlin’s robust date-time mechanisms.

Simple Date Changes and Date Operations

Scenario: Task Scheduler app – dynamically adjust task dates as needed.

val adjustedDate = LocalDate.now()
  .minusDays(5)
  .plusWeeks(3)
  .withDayOfMonth(15)

Date Duration Calculation

Scenario: Fitness Tracker – Calculate the difference between two dates to show time since the last workout.

val timeGap = Duration.between(earlierDate, laterDate)
val daysGap = timeGap.toDays()

Change the timezone of an instant

Scenario: Virtual Meeting Tool – convert a date to display event in the user-specific time zone.

val tokyoDateTime = ZonedDateTime.now()
  .withZoneSameInstant(ZoneId.of("Asia/Tokyo"))

Date Ranges Done Right

Scenario: Promo Code Checker – validate a date range to confirm the active period of promotional codes.

val start = LocalDate.of(2022, 9, 1)
val end = LocalDate.of(2022, 9, 30)
val dateSpan = start..end

if(LocalDate.now() in dateSpan) {
  println("Valid date range")
}

Extract Date Components

Scenario: In a Birthday Reminder, fetch just the day and the month of the date for timely greetings.

val dayOfMonth = date.dayOfMonth
val month = date.month
println("Birthday: $month-$dayOfMonth")

Consistent Date Displays – Format Date to String

Scenario: For Event Booking Tools, use a standard date format for users to swiftly identify and reserve events.

val formattedDate = date.format(DateTimeFormatter.ofPattern("yyyy-MM-dd"))

By using Kotlin’s date-time prowess in your Android applications, you can create intuitive and user-friendly experiences.

Embracing W3C DateTime Standards

The W3C, or World Wide Web Consortium, provides a clear and concise version of the ISO 8601 date-time standards. This standard ensures consistent and reliable date and time displays across different platforms and devices. Here you have a summary of the standart formatting:

5.1 Levels of Detail:

1. Just the Year: 1997
2. Year + Month: 1997-07
3. Full Date: 1997-07-16
4. Date & Time (Hours + Minutes): 1997-07-16T19:20+01:00
5. Adding Seconds: 1997-07-16T19:20:30+01:00
6. With Fractional Seconds: 1997-07-16T19:20:30.45+01:00

5.2 Format Strings:

• YYYY: 4-digit year.
• MM/DD: Month/Day in two digits.
• hh, mm, ss: Time units – hour, minute, and second.
• s: Fractional second.
• TZD: Time zone (‘Z’ for UTC or offset like +hh:mm).

5.3 Handling Time Zones:

1. Universal Time (UTC): Marked with Z. Example: 1994-11-05T13:15:30Z.
2. Local Time + Offset: Uses an offset such as +hh:mm. Example for a timezone -05:00: 1994-11-05T08:15:30-05:00.

To sum up

Managing dates and times in Kotlin, particularly for Android development, can seem daunting with challenges like fluctuating time zones and local preferences. However the solutions offered by Kotlin, including java.time and kotlinx-datetime, provide a smoother way to manage date and time operations.

Incorporating these tools into your mobile applications will ensure precise date handling, transforming a complicated task into an intuitive process. The deeper you dive into Kotlin’s capabilities, the sooner you’ll master date-time functions in your Kotlin-based apps.

So stay curious, and keep innovating.