DateFormat in Android Explained - How to use DateFormat? (android.text.format.DateFormat)

The Android platform provides its own DateFormat utility to format dates and times in various ways. There are a lot of options when it comes to formatting dates - SimpleDateFormatter being another popular alternative. I’d like to discuss Android’s DateFormat since it’s included as part of the platform ‘for free’. Should we use it and what are some of its quirks?

Three core abilities

There are three main ‘things’ the DateFormat class allows us to do. As mentioned, it is a utility so we want it to be useful. For reference, I’ll be using the Kotlin examples rather than Java.

1. Date conversion

Simply: it allows us to format something into a displayable date. Specifically: it allows us to pass in a particular format String (such as "MMM dd, yyyy") and the date that we want to convert, represented by a Long, Date, or Calendar object.

NOTE: For the format String, you can use Android’s reserved Date and Time Patterns keywords or you can use standard Unicode patterns. The documentation for this class refers to UTS #35 that displays various time and date patterns.

I find it a quite annoying that UTS #35 doesn’t do ordinal dates. It says in the document that they’ll likely add this in the future. Ordinal dates are when we see, for example, “23rd” or “25th” - those letters after the digits. However, we can just use alternative methods to add those in if we really wanted.

2. Date Format retrieval

Simply: it allows us to retrieve a date format based on the Android application context. Specifically: By passing in the app context, we determine the best date based on the user’s country as defined on the device. Why is this important? In Australia it’s common to have the date first in short dates such as DD/MM/YYYY but in the United States it’s common to display short dates with the month first as MM/DD/YYYY.

NOTE: The interesting thing to note here is that in all of the defined format retrieval methods getDateFormat(context: Context!), getLongDateFormat(context: Context!), getMediumDateFormat(context: Context!) and getTimeFormat(context: Context!) they all return a DateFormat object. However, this is not the DateFormat method described here from android.text.format.DateFormat. These methods are actually returning a java.text.DateFormat. By looking at the documentation for java.text.DateFormatyou’ll see that there are actually completely different public methods that accept completely different parameters compared to the android.text.format.DateFormat implementation.

3. Random other utilities

The are another three utilities DateFormat provides:

a) The ability to check whether a time should be formatted in 24-hour time based on the device’s preferences with is24HourFormat(context: Context!) returned as a Boolean.

b) The ability to retrieve the correct date format ordering from the device with getDateFormatOrder(context: Context!) that returns a 3-element CharArray with the order that a user has their dates ordered in. For example: as date, month, year for [d, M, y] in order. In various countries, this order could be different.

c) The ability to retrieve the best date and time pattern based on a given locale with getBestDateTimePattern(locale: Locale!, skeleton: String!). In this case, we don’t pass in the application context, but rather a given locale. What’s a locale? Think of it as a shortened String that identifies a particular country, such as en_US for the United States. We also pass in a ‘skeleton’. A skeleton is basically just a UTS #35 String as described above such as DD/MM/YYYY.

DateFormat (android.text.format.DateFormat) Examples

Let’s look at some simple examples. In the following demonstrations, we create a simple TextView and display a date in the text property of that view.

Setting up, we’ll use a Java Date object from java.util.Date. As mentioned above, we can use a Long, Date, or Calendar object with this utility. The default constructor for Date() will just return a representation of the current date and time.

import java.util.Date
import android.widget.TextView
...
var date: Date = Date() 
...
val textView: TextView = itemView.findViewById(R.id.date_view)
...

We can now use that object somewhere in our code. We could display the date in a customised long form as Sat 18 Jan, 11:05 with

textView.text = DateFormat.format("EEE dd MMM, hh:mm", this.date)

Or, we could display a long date automatically without passing a custom String. We can pass the context from the device so the method automatically figures out how to display the correct lengthened form of the date based on the device country set. Note in the example below how we ‘chain’ together two libraries in order to be succinct. In the first part we obtain the long date format - that returns a DateFormat (Important: java.text.DateFormat NOT android.text.format.DateFormat). We then use the result of that DateFormat to call a method called .format which comes from java.text.DateFormat and not android.text.format.DateFormat. From there, we format the result by passing our date that we instantiated previously. I personally find it improves the readability of the code doing it this way.

textView.text = DateFormat.getLongDateFormat(context).format(this.date)

We can do the same thing with a shortened version of the date based on the context of the device.

textView.text = DateFormat.getDateFormat(context).format(this.date)

Further Information

You can find the documentation for DateFormat at https://developer.android.com/reference/android/text/format/DateFormat.html. I hope this article has helped improve your understanding of how the library works.