Pad a Number in Kotlin

1. Overview

In this quick tutorial, we’ll explore how to pad numbers in Kotlin.

2. Introduction to the Problem

When we talk about padding numbers, usually, there are two common padding requirements: start (left) padding and end (right) padding.

As usual, let’s understand the problem through examples. Let’s say we’re given a list of numbers:

val inputNumbers = listOf(7, 42, 4200, 42000, 420000)

Now, let’s say our first requirement is that for the numbers with lengths less than five, we want to pad zeros to the beginning of those numbers so that they all have a length of 5. If a number’s length is five or greater, we’ll leave it as is. Thus, here’s the expected result for this requirement:

val expectedPadStart = listOf("00007", "00042", "04200", "42000", "420000")

Our second requirement is that for the numbers with lengths less than five, we want to pad spaces to the end of those numbers so that they all have a length of 5. If a number’s length is five or greater, we don’t want to change it. So, for the given numbers, this is the result we expect:

val expectedPadEnd = listOf("7    ", "42   ", "4200 ", "42000", "420000")

Some external libraries provide utility methods to do string padding easily. However, in this tutorial, we’ll focus on the Kotlin standard library. After a while, we’ll see that padding numbers with Kotlin standard library is pretty straightforward too.

For simplicity, we’ll use unit-test assertions to verify if our solutions work as expected.

3. Padding Numbers With the String.format() Function

In Java, we can pad a string using the String.format() method. Similarly, Kotlin’s String has a format() function as well.

If we peek at its implementation, it’s an extension function. Internally, it calls Java’s String.format() method:

public inline fun String.format(vararg args: Any?): String = java.lang.String.format(this, *args)

Now that we’ve understood what Kotlin’s format() function does, we can build the format strings and solve the problem:

inputNumbers.map{"%05d".format(it) }.let {
    assertThat(it).isEqualTo(expectedPadStart)
}

inputNumbers.map{"%-5d".format(it) }.let {
    assertThat(it).isEqualTo(expectedPadEnd)
}

As the code above shows, we use “%05d” as the format string to do zero left paddings. It means that we’d like to left-pad the decimal integer with ‘0‘ so that it has a width of five.

Then, we take “%-5d” as the format string to do the right padding with spaces.

If we run the tests, they pass. So, the problem gets solved by the format() function.

However, it’s worth mentioning that Java’s Formatter only supports spaces and zeros (for left padding only) as the padding character, as the space character has been hardcoded in the java.util.Formatter.justify() private method.

Therefore, for example, if we would like to right-pad our numbers with ‘#‘, we need first to pad them with spaces and then replace the spaces with ‘#’:

inputNumbers.map { "%-5d".format(it).replace(" ", "#") }.let {
    assertThat(it).isEqualTo(listOf("7####", "42###", "4200#", "42000", "420000"))
}

4. Padding Numbers With the padStart() and the padEnd() Functions

Kotlin has introduced two pretty handy functions in the String class for string padding: padStart() and padEnd().

Both functions accept two arguments: the desired string length after padding and the character to pad the string with. 

Next, let’s solve the problem using the padStart() and the padEnd() functions:

inputNumbers.map { "$it".padStart(5, '0') }.let {
    assertThat(it).isEqualTo(expectedPadStart)
}

inputNumbers.map { "$it".padEnd(5, ' ') }.let {
    assertThat(it).isEqualTo(expectedPadEnd)
}

As we can see in the code above, we’ve first used Kotlin’s string template to convert the integer to a string. And then, we’ve called the padStart() and the padEnd() functions to apply the actual padding operations.

The test passes if we give it a run.

Since the padStart() and the padEnd() functions support the customized padding character, the two functions are pretty handy if a padding character other than zero or space is required. For example, we can right-pad the numbers with underscores:

inputNumbers.map { "$it".padEnd(5, '_') }.let {
    assertThat(it).isEqualTo(listOf("7____", "42___", "4200_", "42000", "420000"))
}

5. Conclusion

In this article, we’ve learned through examples how to pad numbers in Kotlin. We’ve introduced two approaches: String.format() and padStart()/padEnd().

The padStart() and padEnd() approach is more straightforward, as we don’t need to build the format string. Further, we can also customize the padding character in these two methods.

As always, the full source code used in the article can be found over on GitHub.