Antarctica Time Zones in Kotlin on GraalVM

They say you can tell someone is a developer by whispering the word “timezone” in their ear and watching a shudder go down their spine. Here, from Wikipedia, is a picture of the time zones in Antarctica.

Time zones in Antarctica, from Wikipedia
Time zones in Antarctica, from Wikipedia

Amazing, right? But the funny part isn’t immediately obvious. See how the South Pole is inside that hashed area with alternating red and white stripes? That section is called the Ross Dependency and is claimed by New Zealand, and while most countries don’t recognize territorial claims in Antarctica, that area follows the time zone rules for New Zealand.

That means the South Pole, which experiences six months of daylight followed by six months of darkness, spends part of the year on Daylight Savings Time. Seriously.

Here’s a simple Kotlin script (for the JVM) to check whether or not that’s true at the moment:

import java.time.*

val instant =
val southPole = instant.atZone(ZoneId.of("Antarctica/South_Pole"))
val dst =
println("It is ${southPole.toLocalTime()} " + 
        "(UTC${southPole.offset}) at the South Pole")
println("The South Pole ${if (dst) "is" else "is not"} " +
        "on Daylight Savings Time")

This is really just Java code using classes from the java.time package, but written using Kotlin syntax.

Running this on my Mac (macOS Catalina, version 10.15.2) running Java 11 gives:

$ kotlinc -script southpole.kts
 It is 05:17:54.524607 (UTC+13:00) at the South Pole
 The South Pole is on Daylight Savings Time

Yeah, go figure. This can be fleshed out a bit to see all the time zones in Antarctica:

import java.time.Instant
import java.time.ZoneId
import java.time.ZonedDateTime

val regex = """.*Antarctica.*""".toRegex()
val instant: Instant =

    .filter { regex.matches(it) }
    .map { instant.atZone(ZoneId.of(it)) }
    .sortedBy { it.offset.totalSeconds }
    .forEach { zdt ->
        println(String.format("%7s: %25s %7s",

This produces:

  -03:00:        Antarctica/Rothera   false
  -03:00:         Antarctica/Palmer   false
       Z:          Antarctica/Troll   false
  +03:00:          Antarctica/Syowa   false
  +05:00:         Antarctica/Mawson   false
  +06:00:         Antarctica/Vostok   false
  +07:00:          Antarctica/Davis   false
  +08:00:          Antarctica/Casey   false
  +10:00: Antarctica/DumontDUrville   false
  +11:00:      Antarctica/Macquarie   false
  +13:00:        Antarctica/McMurdo    true
  +13:00:     Antarctica/South_Pole    true

So at the moment, both the South Pole and the scientists at McMurdo Station are on daylight savings time. Keep that in mind next time you plan to set up a conference call with them. And in case you’re wondering, the temperature at McMurdo Station today ranges from a high of 29 F down to a low of 19 F. Not too bad. It is, after all, summer down there.

(Also, if you’re wondering about that “Troll” time zone, that apparently is for Troll Station in Queen Maud Land and it’s practically sitting on the Greenwich meridian. I was kind of hoping someone from the IANA was, well, trolling us.)

The code in the script above is hopefully reasonably clear, with a few explanations:

  • The getAvailableZoneIds method (from Java) returns a Set<String> representing the “region ids” for all the time zones around the world (approximately 600).
  • The filter passes only those in Antarctica.
  • The atZone method returns a ZonedDateTime, so the result of the map operation is a Stream<ZonedDateTime>.
  • These are then sortedBy their offsets in total seconds from GMT, and then printed as the time zone offset, the region ID, and whether or not the time zone is experiencing daylight savings time.

Easy peasy, penguin squeezy, at least until the rest of the Antarctic ice sheet melts or falls into the sea.

Native Image On GraalVM

As it says on the GraalVM web site, Graal is a universal virtual machine for running applications written in multiple languages. Please keep that in mind, because if you talk to one of the Graal developers and you refer only to the native image tool (which I’m about to do), you’ll annoy them unnecessarily. They’re rather sensitive about that, so be careful. I promise I understand that it’s a complete virtual machine, with cross-language capabilities.

Still, what I like about Graal is the native image generator, which allows you to “ahead of time” compile Java code into a stand-alone executable. There are various ways to install the VM and the compiler. For this particular demo, I’m going to use the Gradle plugin.

If you take a look at the source code for my book Kotlin Cookbook, located in this GitHub repository, you’ll find the following sections in the build file build.gradle.kts:

plugins {
    kotlin("jvm") version "1.3.61"
    id("com.palantir.graal") version "0.6.0-58-gce10e7e"

val scriptname: String by project  // from

graal {
    outputName(scriptname) // output is build/graal/${scriptname}

The gradle-graal plugin is a simple wrapper around the GraalVM tooling that downloads the necessary tools and caches them locally. It adds the graal task seen in the snippet, which asks for the class with the main method in it. There are actually many properties you can configure — see the plugin documentation for details.

In this case I’m arguably being a bit too clever, but the ideas are:

  • I have a series of Kotlin scripts in a package called scripts under src/main/kotlin.
  • I put the name of the script I want in my local file. The “by project” delegate is used by Gradle to read properties out of that file.
  • When Kotlin compiles a script (meaning code that isn’t wrapped inside a class), by default it generates a class called ScriptKt. I’m using that as the name of the class Graal needs.

The plugin requires me to have a main method in my script, so here’s a mild refactoring of the overall program:

package scripts

import java.time.Instant
import java.time.ZoneId

fun main() {
    val regex = """.*Antarctica.*""".toRegex()
    val instant =

    val zones = ZoneId.getAvailableZoneIds()
        .filter { regex.matches(it) }
        .map { instant.atZone(ZoneId.of(it)) }
        .sortedBy { it.offset.totalSeconds }

    zones.forEach { zdt ->
        println(String.format("%7s: %25s %7s", zdt.offset,,

    val southPole = instant.atZone(
    val dst =
    println("It is ${southPole.toLocalTime()} " +
            "(UTC${southPole.offset}) at the South Pole")
    println("The South Pole ${if (dst) "is" else "is not"} " +
            "currently on Daylight Savings Time")

The plugin adds a handful of tasks to Gradle. Running gradle tasks gives (among the rest):

Graal tasks
downloadGraalTooling - Downloads and caches GraalVM binaries.
extractGraalTooling - Extracts GraalVM tooling from downloaded archive using the system's tar command or Gradle's copy method.
nativeImage - Runs GraalVM's native-image command with configured options and parameters.
sharedLibrary - Runs GraalVM's native-image command configured to produce a shared library.

The one I want is the nativeImage task. Running this (the first time, so the download of the toolkit is included):

$ ./gradlew nativeImage

> Task :extractGraalTooling
Downloading: Component catalog from
Processing component archive: Native Image
Downloading: Component native-image: Native Image  from
[#####               ]                                                                                                      t: Installing new component: Native Image (org.graalvm.native-image, version 19.2.0)

> Task :nativeImage
Build on Server(pid: 36964, port: 55606)*
[antarctica:36964]    classlist:   2,658.08 ms
[antarctica:36964]        (cap):   2,267.25 ms
[antarctica:36964]        setup:   3,204.49 ms
[antarctica:36964]   (typeflow):   2,251.16 ms
[antarctica:36964]    (objects):   1,932.88 ms
[antarctica:36964]   (features):     248.91 ms
[antarctica:36964]     analysis:   4,527.18 ms
[antarctica:36964]     (clinit):      89.98 ms
[antarctica:36964]     universe:     264.94 ms
[antarctica:36964]      (parse):     319.07 ms
[antarctica:36964]     (inline):   1,054.46 ms
[antarctica:36964]    (compile):   2,818.36 ms
[antarctica:36964]      compile:   4,477.76 ms
[antarctica:36964]        image:     474.30 ms
[antarctica:36964]        write:     175.90 ms
[antarctica:36964]      [total]:  15,920.48 ms
native image available at build/graal/antarctica (5 MB)  

There are now three different ways to execute the original Kotlin script:

  • Compile with kotlinc-jvm; execute it with kotlin
  • Create a jar file by including the runtime; execute it with java
  • Create the native image; execute it directly

So here is using kotlinc-jvm and kotlin:

> kotlinc-jvm antarctica.kt // generates AntarcticaKt.class
> kotlin AntarcticaKt
... output from before ...
> time kotlin AntarcticaKt
kotlin A.. 0.23s user 0.04s system 146% cpu 0.188 total

Now creating the jar first and running java:

> kotlinc-jvm antarctica.kt -include-runtime -d antarctica.jar
> java -jar antarctica.jar
... output from before ...
> time java -jar antarctica.jar
java ...  0.21s user 0.03s system 151% cpu 0.159 total

And finally for the native image:

> sdk install java 19.3.0.r11-grl
> sdk use java 19.3.0.r11-grl
Using java version 19.3.0.r11-grl in this shell
> gu install native-image
Downloading: Component catalog from
 Processing Component: Native Image
 Downloading: Component native-image: Native Image  from
 Installing new component: Native Image (org.graalvm.native-image, version 19.3.0)
> native-image -jar antarctica.jar
... lots of output similar to before ...
> ./antarctica
... works ...
> time ./antarctica
./antarctica  0.00s user 0.00s system 68% cpu 0.008 total

Okay, I lied. I didn’t use the Gradle plugin for the terminal demo. I removed the package statement, moved the script to my root, and installed the tools locally. I use the awesome SDKMAN! tool to manage multiple JDKs, so with it I installed the latest GraalVM version of the JDK, and used its gu command to install native-image, and so on.

Summarizing the results from this admittedly trivial experiment:

kotlin: 0.23s user 0.04s system 146% cpu 0.188 total
  java: 0.21s user 0.03s system 151% cpu 0.159 total
native: 0.00s user 0.00s system  68% cpu 0.008 total

Wow, that’s quite a speed improvement (nearly 20x) with the native image tool, which presumably all comes from avoiding the JVM startup time and memory costs. So sure, I had no good reason to do this, but it’s fun to see a speed up like that.

I should note that the native image tool requires the local toolchain to work, so things like glibc-devel, zlib-devel, and gcc need to be available, as they are on a Mac.

I hope you enjoyed this demo. All the steps are included in my Kotlin Cookbook, now available from O’Reilly Media and in print form on Amazon and from other booksellers.

Now if we could just transport some of that Antarctic ice to Australia where they could really use it…


A Few Astronomical Examples in Kotlin

The website Open Notify provides a few URLs that return JSON data from NASA. There are currently three links supported:

Just for fun, this blog post uses Kotlin to access each one, transform the results in Kotlin data classes, and presents the results. In each case, since only HTTP GET requests are supported, the code uses the extension function readText that was added to the class. It also parses the resulting JSON data using Google’s GSON parser.

As usual, the code for these examples resides in the GitHub repository for my new book, Kotlin Cookbook.

People In Space

Consider the “number of people in space” service first. The JSON response takes the form:

  "message": "success",
  "people": [
    {"name": NAME, "craft": SPACECRAFT_NAME},

The following Kotlin data classes match up with that JSON structure:

data class AstroResult(
    val message: String,
    val number: Int,
    val people: List<Assignment>

data class Assignment(
    val craft: String,
    val name: String

An Assignment connects a craft to an astronaut name, and the AstroResult has a String message (which out to be “success“), a number, and a list of assignments.

Going from the base URL to the AstroResult is easy enough. Just instantiate a Gson object and invoke its fromJson method:


GSON doesn’t know anything about Kotlin. It’s a Java library, so it expects to convert JSON strings into Java classes. The syntax uses the double colon to get the KClass (the Kotlin class), whose java property returns the Java class.

This result could be assigned to a local variable for printing, but that’s what the scope functions like also or let are for. For example, to print the results, try this:

).also { astroResult ->
    println("There are ${astroResult.number} people in space:")
    astroResult.people.forEach { assignment ->
        println("\t${} aboard ${assignment.craft}")

As of December 2019, this prints:

There are 6 people in space:
    Christina Koch aboard ISS
    Alexander Skvortsov aboard ISS
    Luca Parmitano aboard ISS
    Andrew Morgan aboard ISS
    Oleg Skripochka aboard ISS
    Jessica Meir aboard ISS

Even simpler, though not as nicely structured, is to just drill down to the names and print them:

    .also(::println)  // or use let instead of also

As a developer I knew once said, “My debugger is .also(::println)“.

For no good reason, you could create a class for the whole process, and why not make it executable at the same time?

class AstroRequest {
    companion object {
        private const val ASTRO_URL = 

    operator fun invoke(): AstroResult =

The URL is a constant, so you might as well say so. The operator function invoke means that you can use the “parentheses operator”, (), to execute an instance of this class, as the following test shows:

class AstroRequestTest {
    fun `get people in space`() {
        val request = AstroRequest()
        val result = request()  // calls "invoke" function
        assertThat(result.message, `is`("success"))
        assertThat(result.number, `is`(greaterThanOrEqualTo(0)))
        assertThat(result.people.size, `is`(result.number))

If you really want to go to extremes (and guarantee you get challenged in a code review), you can actually combine the instantiation and execution into one line:

val result = AstroRequest()()

which works, but please don’t do that. ๐Ÿ™‚

Position of the ISS

Moving now to the service that returns the position of the International Space Station, the JSON form of the response is:

  "message": "success", 
  "timestamp": UNIX_TIME_STAMP, 
  "iss_position": {
    "latitude": CURRENT_LATITUDE, 
    "longitude": CURRENT_LONGITUDE

Ah, the joys of the Unix time stamp. Fortunately, since I’m assuming we’re running on the JVM, there is a straightforward (but overly complicated) way to convert the timestamp into an instance of java.time.ZonedDateTime in your local time zone. Here are the resulting data classes:

data class IssPosition(
    val latitude: Double,
    val longitude: Double

data class IssResponse(
    val message: String,
    val iss_position: IssPosition,
    val timestamp: Long
) {
    val zdt: ZonedDateTime
        get() = ZonedDateTime.ofInstant(

The IssPosition class just combines the latitude and longitude, so there’s nothing special about that. The IssResponse class includes the message (again, “success”) and the ISS position. The property uses an underscore so no additional annotations are needed to do the JSON mapping. The fun part comes with the timestamp.

The timestamp may be identified as a UNIX timestamp, but as far as Kotlin is concerned it’s just a Long representing the number of seconds elapsed since the current epoch began on midnight, January 1, 1970, UTC. You can certainly use a function to convert the long to a ZonedDateTime, but since the result is just a dependent property, it seems appropriate to make it a property with a custom get method.

Taking the same object-oriented approach as before, here is a class to return either the entire response, or just the position:

class ProcessAstroData {
    companion object {
        const val url = ""

    fun getResponse(): IssResponse =

    fun getPosition() =
        getResponse().also {
            println("As of " + it.zdt.format(

The getPosition function could just be written as getPosition().iss_position, but as a side effect it prints the time of the request.

To run this, use the following lines:

val demo = ProcessAstroData()
val (lat, lng) = demo.getPosition()
println("$lat deg N, $lng deg W")

If there was ever a class built for destructuring, it’s a wrapper for latitude and longitude. The current result is:

As of December 19, 2019 at 5:31:47 PM EST
49.0682 deg N, 160.2318 deg W

Overhead Pass Predictions

Moving finally to the overhead pass predictions for the ISS, the JSON output for that service looks like:

  "message": "success",
  "request": {
    "latitude": LATITUE,
    "longitude": LONGITUDE, 
    "altitude": ALTITUDE,
    "passes": NUMBER_OF_PASSES,
    "datetime": REQUEST_TIMESTAMP
  "response": [
    {"risetime": TIMESTAMP, "duration": DURATION},

This time, however, there are input values required. The user has to supply the latitude and longitude, and can optionally supply an altitude and a number of passes (which defaults to five). According to the documentation, the parameters in the service are specified as lat, lon, alt, and n, respectively.

Once again using simple Long variables where the service is expecting a timestamp, the following data classes map to this structure:

data class OverheadResponse(
    val message: String,
    val request: OverheadRequest,
    val response: List<TimeAndDuration>

data class OverheadRequest(
    val latitude: Double,
    val longitude: Double,
    val altitude: Double,
    val passes: Int,
    val datetime: Long

data class TimeAndDuration(
    val risetime: Long,
    val duration: Long

Since there are several timestamp fields, this time use a function to convert the Long values to formatted strings:

fun formatTimestamp(timestamp: Long): String =

Here is a class to do the work:

class Overhead {
    companion object {
        const val base = ""

    fun getOverheadResponse(lat: Double, 
                            lng: Double,
                            alt: Double = 0.0,
                            num: Int = 5): OverheadResponse {
        val url = "$base?lat=$lat&lon=$lng&alt=$alt&n=$num"
        val json = URL(url).readText()
        return Gson().fromJson(json,

Use optional parameters in the Kotlin function to represent the default values for the service. To get the overhead pass times, instantiate the class, get the response, and format them:

// Marlborough, CT
val latitude = 41.6314
val longitude = -72.4596

val output = Overhead().getOverheadResponse(latitude, longitude)
output.response.forEach {

The output at the time of this writing is:

December 20, 2019 at 5:42:26 AM EST
December 20, 2019 at 7:17:35 AM EST
December 20, 2019 at 8:55:03 AM EST
December 20, 2019 at 10:32:58 AM EST
December 20, 2019 at 12:10:04 PM EST

These examples used simple GET requests to access the free services and GSON to parse the resulting JSON data. Along the way it used data classes, companion objects, an executable class, optional parameters, and conversion of Unix timestamps to classes from the java.time package. Hopefully you’ll find something interesting in it. Or you can fire it into the sun. ๐Ÿ™‚


Fibonacci in Kotlin

I didn’t realize it until I noticed the trending topic on Twitter, but Saturday, November 23 was Fibonacci Day. That gave me an opportunity to drag out one of my favorite old jokes:

For those unaware or who don’t remember, the Fibonacci series starts with 0 and 1, and then each subsequent number is the sum of the previous two. The Fibonacci numbers are thus 0, 1, 1, 2, 3, 5, 8, 13, …. By the definition, the “zeroth” Fibonacci number F0 = 0, the first F1 = 1, the second F2 = 1, the third F3 = 2, and so on.

(Note the gag only works in the U.S., because we express our dates as month/day/year rather than day/month/year like the rest of the world. For us, November 23 is 11/23, thus Fibonacci day, ha ha. Sorry about the US-centric approach. On the other hand, there’s no 23rd month, so the rest of the world would miss out on Fibonacci day, and that would be sad.)

Naive Recursive Implementation

The Fibonacci algorithm is a classic example of a recursive function, expressed as Fn = Fn-1 + Fn-2:

fib(n) = fib(n - 1) + fib(n - 2)

The problem with a naive implementation of that algorithm is that the amount of duplicated work grows exponentially. For example,

fib(5) = fib(4) + fib(3) 
       = fib(3) + fib(2) + fib(2) + fib(1) 
       = fib(2) + fib(1) + fib(1) + fib(0) 
                + fib(1) + fib(0) + 1
       = fib(1) + fib(0) + 1 + 1 + 0 + 1 + 0 + 1 
       = 1 + 0 + 1 + 1 + 0 + 1 + 0 + 1
       = 5

Yikes, and that’s just for the fifth Fibonacci number. The problem is that intermediate results aren’t being saved, so each number is recalculated over and over again, and the higher you go, the more duplicated work there is.

Tail Call Optimization

In Kotlin, there are several ways to fix this. One is to use tail recursion, which involves replacing recursion with iteration. An implementation in Kotlin can take advantage of the tailrec keyword:

tailrec fun fibonacci(n: Int, a: Int = 0, b: Int = 1): Int =
    when (n) {
        0 -> a
        1 -> b
        else -> fibonacci(n - 1, b, a + b)

There’s a fair amount going on here. First, in order to write a recursive function as a tail call, the recursive call itself has to come last in the implementation. In this example, the last evaluated expression is the else clause in the when loop, which calls the function again.

Also, when you write your function to be called recursively, you need to use an additional parameter to act as the accumulator. Here, n is the nth desired Fibonacci number, the value of b is the previous value, and the value of a is the one before that. In the recursive call, the new value of b is the current value of b plus the value of a, so that is effectively the accumulator.

The next interesting part is that the return type is specified explicitly. Normally in Kotlin when you implement a function as a single expression (using an = sign at the end of the signature) you can leave out the return type. If you do that in this case, however, IntelliJ IDEA complains with “Type checking has run into a recursive problem. Easiest workaround: specify types of your declarations explicitly.” Yeah, okay, I can do that, thus the a : Int at the end of the signature.

The next good part is using default values for the second and third arguments in the function. By initializing a to 0 and b to 1, the function can be invoked as fibonacci(10) without giving values for the other two parameters. That’s the way you want to call the function anyway, so that’s helpful. Unfortunately, Java doesn’t support default parameters, so to make sure the compiler generates overloads that Java can see, the JmvOverloads annotation is added. Now the fibonacci function can be called from Java with only a single argument.

That leads to the best part, which is the tailrec modifier. You could write this tail call algorithm directly in Java, but it wouldn’t save any memory. In Kotlin, however, this page in the reference guide says that compiler will automatically “optimize out the recursion, leaving behind and fast and efficient loop version instead.”

If you play the game in IntelliJ where you “Show Kotlin Bytecodes” and the hit the Decompile button, the resulting Java code looks like:

public static final int fibonacci(int n, int a, int b) {
    while(true) {
        int var10000;
        switch(n) {
        case 0:
            var10000 = a;
        case 1:
            var10000 = b;
            var10000 = n - 1;
            int var10001 = b;
            b += a;
            a = var10001;
            n = var10000;

        return var10000;

The recursive call has been implemented as a while(true) loop with the accumulator in the default section.

Kotlin fold and reduce

That’s all well and good, and normally I’d go on to discuss ways to test this function, but there are a couple of alternative ways to implement the algorithm. One is this particularly interesting version:

fun fibonacciFold(n: Int) =
    (2 until n).fold(1 to 1) { (prev, curr), _ -> 
        curr to (prev + curr) 

Now that’s poetry, in that it’s simple, elegant, and really needs to be explained before it makes any sense. First of all, credit where credit is due. This is from Marcin Moskala (@marcinmoskala on Twitter). He included it in a blog post at Kotlin Academy, based on one of his tweets.

His first example, fib1, is the inefficient recursive algorithm. His second, fib2, is an iterative version of the same. The third one, fib3, is like the tail-call version described above. Finally, the last one, fib4, is the one I want to talk about, repeated in the syntax block prior to the tweet.

First, the expression (2 until n) is a range that runs from 2 to n - 1. An inclusive range would be 2..n.

Next comes the fold function. Kotlin has both fold and reduce functions. The fold function takes two parameters, while reduce only takes one:

inline fun <T, R> Iterable<T>.fold(
    initial: R,
    operation: (acc: R, T) -> R
): R

inline fun <S, T : S> Iterable<T>.reduce(
    operation: (acc: S, T) -> S
): S

Each of them applies the provided operation to each element of the Iterable, and the last evaluated expression from the operation becomes the new value of the acc (accumulator) argument on the next iteration. The difference is that fold takes an initial value for the accumulator, while reduce uses the first element from the sequence to initialize the accumulator.

For those more familiar with Java, the reduce function on Java streams behaves the same way, except that it is overloaded to take either a single BinaryOperator (like Kotlin’s reduce) or two values, where the first is an initial value called identityand the second is a BinaryOperator (like Kotlin’s fold). Note that in Java they refer to the first argument as identity rather than initial, which is more in keeping with the theory of functional programming. In either case the first argument is used as the initial value of the provided operation accumulator, but it’s supposed to be the identity value for the binary operator. The Kotlin implementation works the same way, but doesn’t stress that distinction.

Returning to the Fibonacci calculation, the fold function uses the Pair of 1 to 1 as its initial value, so the operation needs to return a new instance of Pair each time. There are two arguments to the lambda provided as the operation. The first argument is also a Pair, which acts as the accumulator, and the second argument would be each value in the range from 2 to n - 1. The algorithm doesn’t actually need those values, so the implementation just uses an underscore to indicate they’re ignored.

The implementation of the operation creates a new Pair whose first element is the current value and whose second element is the sum of the previous value and the current value. Finally, when the limit of the range is reached, the function returns the second element from the Pair as the desired value.

As usual with a fold function, it’s easiest to understand if you see it in action. Here is a version of it with the previous and current values written out each time:

fun fibonacciFoldDebug(n: Int) =
    (2 until n).fold(1 to 1) { (prev, curr), _ ->
        println("prev=$prev, curr=$curr")
        curr to (prev + curr)

Here is the output of F(10):

prev=1, curr=1
prev=1, curr=2
prev=2, curr=3
prev=3, curr=5
prev=5, curr=8
prev=8, curr=13
prev=13, curr=21
prev=21, curr=34
Fib(10) == 55

The initial Pair of 1 to 1 initialized the prev and curr variables, which take new values as described in the fold operation. Once again, a recursive problem has been transformed into an iterative one, but this time in a really beautiful way. You can comfortably compute Fibonacci numbers as far as Int values work, and if you need something higher just reimplement this with BigInteger (and replace + with add) and keep going.


There’s one more fundamentally different approach to the same problem, this time using sequences. A sequence in Kotlin is just like a stream in Java, in that values go through a series of intermediate operations followed by a terminal operation, and no data is pulled through the sequence until there is a terminal operation.

There are several ways to create a sequence in Kotlin, from the asSequence function on collections to the generateSequence function that takes a lambda to evaluate for each element. There is also, however, the basic function called sequence:

fun <T> sequence(
    block: suspend SequenceScope<T>.() -> Unit
): Sequence<T>

The sequence function is a suspend function (so it can be used with coroutines) that takes a lambda with a receiver. The lambda takes no arguments and returns nothing (i.e., Unit), and the receiver is an instance of SequenceScope. The documentation says the function returns a sequence by lazily yielding values one by one.

In fact, that documentation page actually contains a Fibonacci example, repeated here:

fun fibonacci() = sequence {
    var terms = Pair(0, 1)

    // this sequence is infinite
    while (true) {
        terms = Pair(terms.second, terms.first + terms.second)

Look familiar? The iteration occurs over Pair instances, as before, in an infinite loop. The yield function “yields a value to the Iterator being built and suspends until the next value is requested.” Note that this returns a sequence, so to invoke it you need to add a terminal operation. The way the code in the documentation example calls this function is:


The take function is another intermediate operation that requests ten elements, and toList is, at long last, a terminal operation which converts the sequence into a List. The code prints the first 10 Fibonacci numbers in a list, [0, 1, 1, 2, 3, 5, 8, 13, 21, 34].

Wow, right? Lots of ways to solve the same problem. Of course, any functions like this need to be tested. That, too, can be an interesting story, which I’ll leave for the next blog post in this series.

As always, all the code (including extensive JUnit 5 tests) from this post can be found in this GitHub repository for my new book, the Kotlin Cookbook.


Annotated TOC for Kotlin Cookbook

Last week I received an email asking about a table Of contents for my new Kotlin Cookbook, saying they couldn’t find one either on the O’Reilly Media site or on Amazon. It’s a lot easier to make a decision about buying a recipe book if you have a list of recipes.

When I checked last week, no table of contents was available. Fortunately that’s no longer the case. If you go to the Amazon listing and click on the “Look Inside” link, the table of contents is included, along with the preface, which includes a description of each chapter.

It couldn’t hurt, however, to repeat both of those here as well. That way if anyone asks I can just give them this link, plus you can add whatever comments you like to this post and I’ll see them and potentially be able to respond.

Cover for my Kotlin Cookbook
Cover for my Kotlin Cookbook

Here is the list of chapter descriptions from the Preface.

  • Chapter 1, Installing and Running Kotlin, covers the basic process of installing and running Kotlin, including using the REPL, working with build tools like Maven and Gradle, and employing the native image generator in Graal.
  • Chapter 2, Basic Kotlin, covers some fundamental features of Kotlinโ€”such as nullable types, overloading operators, and converting between typesโ€”before examining some more esoteric issues including working with bitwise shift operators or the to extension function on the Pair class.
  • Chapter 3, Object Oriented Programming in Kotlin, focuses on object-oriented features of the language that developers from other languages might find surprising or unusual. It includes how to use the const keyword, how Kotlin handles backing properties, delayed initialization, and the dreaded Nothing class, which is guaranteed to confuse existing Java developers.
  • Chapter 4, Functional Programming, has only a few recipes, which involve functional features that need their own explanations. Functional programming concepts are covered throughout the book, especially when talking about collections, sequences, and coroutines, but there are a handful of techniques included in this chapter that you may find unusual or particularly interesting.
  • Chapter 5, Collections, covers arrays and collections, dealing mostly with non-obvious methods like destructing collections, sorting by multiple properties, building a window on a collection, and creating progressions.
  • Chapter 6, Sequences, shows how Kotlin handles sequences of items lazily, similar to the way Java uses streams. Recipes cover generating sequences, yielding from them, and working with infinite sequences.
  • Chapter 7, Scope Functions, covers another topic unique to Kotlin: functions that execute a block of code in the context of an object. Functions like let, apply, and also are quite useful in Kotlin, and this chapter illustrates why and how to use them.
  • Chapter 8, Kotlin Delegates, discusses a convenient feature of Kotlin: how it implements delegation. Delegation lets you employ composition rather than inheritance, and Kotlin includes several delegates in the standard library, like lazy, observable, and vetoable.
  • Chapter 9, Testing, covers the important topic of testing, with a particular focus on JUnit 5. In its current version, JUnit is designed to work well with Kotlin, and that includes both its regular usage and employing it in Spring Framework applications. This chapter discusses several approaches that make writing and executing tests easier.
  • Chapter 10, Input/Output, includes a couple of recipes specifically for managing resources. File I/O is covered, as is the use function, which has broad applicability in several contexts.
  • Chapter 11, Miscellaneous, covers topics that do not fit easily in any other category. Topics such as how to get the current Kotlin version, how to force the when statement to be exhaustive even when it doesn’t return a value, and how to use the replace function with regular expressions are covered. In addition, the TODO function and the Random class are discussed, as well as how to integrate with Java exception handling.
  • Chapter 12, The Spring Framework, involves the Spring Framework along with Spring Boot, which is very friendly to Kotlin. A few recipes are included to show how to use Kotlin classes as managed beans, how to implement JPA persistence, and how to inject dependencies when needed.
  • Chapter 13, Coroutines and Structured Concurrency, covers the subject of coroutines, one of the most popular features of Kotlin and the basis of concurrent and parallel programming in the language. Recipes cover the basics, like builders and dispatchers, along with how to cancel and debug coroutines, and how to run them on your own custom Java thread pool.

Hopefully those descriptions will be helpful. For the actual recipes, the following list has been (slightly) enhanced by using code formatting for Kotlin functions or keywords.

  1. Installing and Running Kotlin
    1.1 Running Kotlin Without a Local Compiler
    1.2 Installing Kotlin Locally
    1.3 Compiling and Running Kotlin from the Command Line
    1.4 Using the Kotlin REPL
    1.5 Executing a Kotlin Script
    1.6 Building a Standalone Application Using GraalVM
    1.7 Adding the Kotlin Plugin for Gradle (Groovy Syntax)
    1.8 Adding the Kotlin Plugin for Gradle (Kotlin Syntax)
    1.9 Using Gradle to Build Kotlin Projects
    1.10 Using Maven with Kotlin
  2. Basic Kotlin
    2.1 Using Nullable Types in Kotlin
    2.2 Adding Nullability Indicators to Java
    2.3 Adding Overloaded Methods for Java
    2.4 Converting Between Types Explicitly
    2.5 Printing to Different Bases
    2.6 Raising a Number to a Power
    2.7 Using Bitwise Shift Operators
    2.8 Using Bitwise Boolean Operators
    2.9 Creating Pair Instances with to
  3. Object-Oriented Programming in Kotlin
    3.1 Understanding the Difference Between const and val
    3.2 Creating Custom Getters and Setters
    3.3 Defining Data Classes
    3.4 The Backing Property Technique
    3.5 Overloading Operators
    3.6 Using lateinit for Delayed Initialization
    3.7 Using Safe Casting, Reference Equality, and Elvis to Override equals
    3.8 Creating a Singleton
    3.9 Much Ado About Nothing
  4. Functional Programming
    4.1 Using fold in Algorithms
    4.2 Using the reduce Function for Reductions
    4.3 Applying Tail Recursion
  5. Collections
    5.1 Working with Arrays
    5.2 Creating Collections
    5.3 Creating Read-Only Views from Existing Collections
    5.4 Building a Map from a Collection
    5.5 Returning a Default When a Collection Is Empty
    5.6 Restricting a Value to a Given Range
    5.7 Processing a Window on a Collection
    5.8 Destructuring Lists
    5.9 Sorting by Multiple Properties
    5.10 Defining Your Own Iterator
    5.11 Filtering a Collection by Type
    5.12 Making a Range into a Progression
  6. Sequences
    6.1 Using Lazy Sequences
    6.2 Generating Sequences
    6.3 Managing Infinite Sequences
    6.4 Yielding from a Sequence
  7. Scope Functions
    7.1 Initializing Objects After Construction with apply
    7.2 Using also for Side Effects
    7.3 Using the let Function and Elvis
    7.4 Using let with a Temporary Variable
  8. Kotlin Delegates
    8.1 Implementing Composition by Delegation
    8.2 Using the lazy Delegate
    8.3 Ensuring That a Value Is Not Null
    8.4 Using the observable and vetoable Delegates
    8.5 Supplying Maps as Delegates
    8.6 Creating Your Own Delegates
  9. Testing
    9.1 Setting the Test Class Life Cycle
    9.2 Using Data Classes for Tests
    9.3 Using Helper Functions with Default Arguments
    9.4 Repeating JUnit 5 Tests with Different Data
    9.5 Using Data Classes for Parameterized Tests
  10. Input/Output
    10.1 Managing Resources with use
    10.2 Writing to a File
  11. Miscellaneous
    11.1 Working with the Kotlin Version
    11.2 Executing a Lambda Repeatedly
    11.3 Forcing when to Be Exhaustive
    11.4 Using the replace Function with Regular Expressions
    11.5 Converting to Binary String and Back
    11.6 Making a Class Executable
    11.7 Measuring Elapsed Time
    11.8 Starting Threads
    11.9 Forcing Completion with TODO
    11.10 Understanding the Random Behavior of Random
    11.11 Using Special Characters in Function Names
    11.12 Telling Java About Exceptions
  12. The Spring Framework
    12.1 Opening Spring-Managed Bean Classes for Extension
    12.2 Persisting Kotlin Data Classes
    12.3 Injecting Dependencies
  13. Coroutines and Structured Concurrency
    13.1 Choosing Coroutine Builders
    13.2 Replacing async/await with withContext
    13.3 Working with Dispatchers
    13.4 Running Coroutines on a Java Thread Pool
    13.5 Cancelling Coroutines
    13.6 Debugging Coroutines

I believe that’s 87 recipes total. I could have added at least a dozen more, but as Katie Mack (@AstroKatie on Twitter) once said, “the hardest thing about writing a book is that eventually you have to stop writing the book.” My book is done and I believe what’s there is solid. If I ever get to revisit it for a second edition, I’m sure I’ll have much more to say, but this hopefully will give you a good cross-section of what Kotlin can do and how to do it.


Kotlin Palindrome Checker

This post, based on code from my new Kotlin Cookbook, shows how to write a palindrome checker in Kotlin. Along the way it discusses raw strings and regular expressions, writing functions as single statements, and creating an extension function on String.

First, a quick definition. A palindrome is a string whose characters are the same forwards and backwards, ignoring case and with punctuation removed. Here are a few palindromes, which can serve as test cases later:

  • racecar
  • Madam, in Eden, I’m Adam.
  • Flee to me, remote elf!
  • Sex at noon taxes.
  • A Santa pets rats, as Pat taps a star step at NASA.

Make of them what you will. ๐Ÿ™‚

To make a palindrome checker, you need to remove case sensitivity and replace all the punctuation with empty strings. The first task is trivial: just use the String functions toLowerCase or toUpperCase, whichever you prefer.

To handle regular expressions, Kotlin has a few mechanisms, but one is to use a raw string with the regex in it and then invoke the toRegex function on it.

In the case of a palindrome, a decent regex would be """[\W+]""". The square brackets represent a choice. The expression is a predefined character class \W, meaning the opposite of \w, where the lowercase version represents any word character. Word characters are lowercase a-z, uppercase A-Z, the numbers 0-9, and an underscore, _. Therefore \W represents all non-word characters, which can be used to get rid of all punctuation (other than underscores, but if that’s important, that can always be added later). The plus sign means one or more, so the overall effect is to look for one or more non-word characters. Since this post (and the book) is written for the JVM version of Kotlin, you can see the JavaDocs for java.util.regex.Pattern class for details.

The triple quotes surrounding the regex represent a “raw” string in Kotlin, so you don’t have to escape the backslash on the W when writing a regular expression. Raw strings can be written over several lines, too, but that’s not necessary here. To make the raw string into a regular expression, invoke the toRegex function on it.


The tricky “replace” function

To use the regular expression, String has a function called replace, but it’s a bit tricky. There are two overloaded versions of replace, one whose first argument is a string and one whose first argument is a regex. The signatures are:

// First arg is String, last arg has default value "false"
public fun String.replace(
    oldValue: String,
    newValue: String,
    ignoreCase: Boolean
): String


// First arg is a regular expression
public inline fun CharSequence.replace(
    regex: Regex,
    replacement: String
): String

For the first version of replace, the library implementation shows that the ignoreCase parameter has a default value of false, so invoking the function without that parameter is legal. That, unfortunately, makes it easy to confuse with the second version, as the following test case shows.

fun `demonstrate replace with a string vs regex`() {
        { assertEquals("one*two*", "one.two.".replace(".", "*")) },
        { assertEquals("********", 
              "one.two.".replace(".".toRegex(), "*")) }

The first assertion replaces the single dots in “one.two.” with a single star, *, because it’s using the version of replace that takes a string as the first argument. That means it looks for literal dots in the string and replaces them with a star.

The second assertion uses the version of replace that takes a regular expression as the first argument. In regular expressions, a single dot represents any single character, so the result is to replace all the letters in “one.two.” with stars, as shown.

I should mention that I didn’t come up with that example on my own. I saw it in a slide found here, which is one of the presentations, hosted at SpeakerDeck, provided by the Kotlin core team members. The slides are a little dated, but still useful. You can find all of them linked from this GitHub repository.

isPalindrome Function

Returning to the palindrome checker, version 1 is shown as a function called isPalindrome that takes a string argument and returns a boolean:

fun isPalindrome(string: String): Boolean {
    val testString = string.toLowerCase()
        .replace("""[\W+]""".toRegex(), "")
    return testString == testString.reversed()

This works by converting the supplied string to lower case, then using the replace function with the needed regex, and then using == to see if it is equivalent to its reverse. It’s notable that in Kotlin String has a reverse function, and that operator overloading means that the == sign invokes the equals function.

While this works, it’s arguably not idiomatic. Kotlin favors single statement functions, where you can just assign a statement implementation to the function signature. The hard part in this particular function is that it is currently two statements — one to create the test string, and one to do the equality check. This is where the convenient scope function called let comes in, as you can see in version 2 of the palindrome function:

fun isPalindrome(string: String) =
          .replace("""[\W+]""".toRegex(), "")
          .let { it == it.reversed() }

The replace function returns the new string, so you can chain another function call to it. Then, according to the documentation, the let function “calls the specified function block with this value as its argument and returns its result”. The provided block is a lambda with a single argument, referred to as it, and returns the last evaluated expression, which is the boolean that results from the equivalence check.

To really bring this home, this top-level function seems to be a natural extension function on the String class (or CharSequence interface) , so here is the final version of the function:

fun String.isPalindrome() =
        .replace("""[\W+]""".toRegex(), "")
        .let { it == it.reversed() }

Inside the extension function, the current instance is referenced as this, but the rest of the implementation is the same.

Finally, here are a couple of tests to demonstrate that the function works correctly:

fun `these are palindromes`() {
        { assertTrue("Madam, in Eden, I'm Adam".isPalindrome()) },
        { assertTrue("Flee to me, remote elf!".isPalindrome()) },
        { assertTrue("Sex at noon taxes".isPalindrome()) },
        { assertTrue("A Santa pets rats, as Pat taps a star step at NASA".isPalindrome()) }

fun `check isPalindrome is not just returning true`() {
    assertFalse("this is not a palindrome.isPalindrome())

The result is a simple function that can be used for any string, and the implementation shows how to use replace, reverse, regular expressions, the let function, and how to implement a simple extension function.

As usual, the source code can be found in the GitHub repository for my Kotlin Cookbook. The tests there include one for the massive 543-word palindrome, written as a multi-line string, from the Gigantic List of Palindromes. Just being able to verify that palindrome was entertaining enough to do this entire exercise. ๐Ÿ™‚


A Deep Dive into the KotlinVersion Class

Getting the current Kotlin version is easy, but the actual KotlinVersion class is much more interesting. This post shows how to get the Kotlin version programmatically, but then looks at the details of the KotlinVersion class, including how it demonstrates a great way to write an equals method and more.

Note that this demo is part of my new book, Kotlin Cookbook, from O’Reilly Media.

Book cover for Kotlin Cookbook
The Kotlin Cookbook, coming this Fall from O’Reilly Media

Also, I was lucky enough to be interviewed by Hadi Harriri on his Talking Kotlin podcast, and this class came up. That episode has not yet been released, but should be out soon depending on his current backlog.

To start, here is the trivial one-liner to find out which version of Kotlin is executing your code:

fun main() {
    println("The current Kotlin version is ${KotlinVersion.CURRENT}")

At the time of this writing, the current release version of Kotlin is 1.3.50, and when you run this script on that version that’s what you get.

Where life gets interesting is when you look at how the KotlinVersion class is implemented. The next series of snippets will examine that in some detail. The KotlinVersion class in the standard library is in the kotlin package, and begins:

public class KotlinVersion(val major: Int, 
                           val minor: Int, 
                           val patch: Int
) : Comparable<KotlinVersion> {

The class is marked public, which isn’t necessary (public is the default) but is typical of library classes. Then follows the primary constructor, which takes three integer values, labeled major, minor, and patch. After the colon after the signature shows that the class implements the Comparable interface for instances of itself, which is already pretty interesting. The Comparable interface in Kotlin is just like its counterpart in Java. It establishes a “natural ordering” on instances of the class.

The Comparable interface in the standard library consists of:

public interface Comparable<in T> {
    public operator fun compareTo(other: T): Int

Again, the word public is not necessary either on the class or the function, but doesn’t hurt anything. The compareTo function is labeled an operator function. In this case, the function is used whenever you use <, >, ==, or one of the combination comparison functions, <=, >=, or !=. The function returns an integer whose value doesn’t matter, but should be negative, zero, or positive if the current object is less than, equal to, or greater than its argument.

Returning to the KotlinVersion class, the implementation of compareTo is:

override fun compareTo(other: KotlinVersion): Int = version - other.version

This assumes that the KotlinVersion class has a version property. The primary constructor didn’t show one, so the implementation provides a private property of that name and the function to compute it:

private val version = versionOf(major, minor, patch)

private fun versionOf(major: Int, minor: Int, patch: Int): Int {
    require(major in 0..MAX_COMPONENT_VALUE && 
            minor in 0..MAX_COMPONENT_VALUE && 
            patch in 0..MAX_COMPONENT_VALUE) {
        "Version components are out of range: $major.$minor.$patch"
     return major.shl(16) + minor.shl(8) + patch

So the version property is computed from the major, minor, and patch values. The require statement is a pre-condition that verifies the individual values fall within the required range. For all three, the minimum is zero and the maximum is MAX_COMPONENT_VALUE. Like most constants, MAX_COMPONENT_VALUE is found in the companion object:

companion object {
    public const val MAX_COMPONENT_VALUE = 255

    public val CURRENT: KotlinVersion = KotlinVersion(1, 3, 50)

Note the use of both const and val together. From a Java perspective, the properties inside the companion object are effectively static, and the val keyword indicates they’re both final as well. The const modifier means the value is a compile-time constant, rather than being specified at runtime. The max value is therefore hard-wired to 255, and on this version of Kotlin the CURRENT value is an instance of the KotlinVersion class where major, minor, and patch values are 1, 3, and 50, respectively.

That takes care of the require block in the versionOf function. What about the actual value it returns? That’s computed using the shift-left (or left-shift, but the other way reads better) operator function, shl. That is an infix function that shifts the current value by the specified number of bits. Its signature is given by:

public final infix fun shl(
    bitCount: Int
): Int

This is an infix function, so the idiomatic way to invoke it would be major shl 16, minor shl 8, etc, but the form used here works anyway. Basically, the function shifts by two bytes for major and one byte for minor, which gives them enough of an offset that it is very unlikely a different set of major/minor/patch values will result in the same version. For the record, using 1, 3, and 50 gives 65,536 for 1 shl 16 and 768 for 3 shl 8, and the sum from the versionOf function is 66,354:

fun `left-shift for major, minor, and patch of 1, 3, and 50`() {
    assertEquals(65536, 1 shl 16)
    assertEquals(768, 3 shl 8)
    assertEquals(66354, (1 shl 16) + (3 shl 8) + 50)

The major, minor, and patch values are therefore combined into a single integer, which is used for the ordering. The next interesting part is how the KotlinVersion class implements the standard overrides of toString, equals, and hashCode:

override fun toString(): String = "$major.$minor.$patch"

override fun equals(other: Any?): Boolean {
    if (this === other) return true
    val otherVersion = (other as? KotlinVersion) ?: return false
    return this.version == otherVersion.version

override fun hashCode(): Int = version

There’s nothing terribly surprising about the overrides of toString or hashCode. The former is just formatting, and the latter reuses that version calculation just discussed, which is pretty convenient since the left-shifted offset mechanism described above is exactly how Josh Bloch recommended creating a decent hashCode function in his Effective Java book for the last twenty-some-odd years. ๐Ÿ™‚

The real fun is in the override of the equals function. The KotlinVersion class, like all Kotlin classes, extends Any. As a reminder, the Any class looks like:

package kotlin

public open class Any {
    public open operator fun equals(other: Any?): Boolean
    public open fun hashCode(): Int
    public open fun toString(): String

Returning to the implementation of equals in KotlinVersion, the first check uses the triple equals operator === to see if the current reference and the argument are both pointing to the same instance. If so, the result is equal and no further checking is necessary.

If the two objects are different, the code needs to check the version property. Because the argument to the equals function is nullable, you can’t simply access the version property without checking for null first. The safe cast operator, as?, is used to check that. If the argument is not null, this casts it to an instance of KotlinVersion. If the argument is null, the safe cast operator returns null, so the Elvis operator, ?:, is used to simply return false rather than continue.

That’s really interesting, actually. The “return false” statement aborts the assignment of the otherVersion property. The results is Nothing, a class almost guaranteed to confuse Java developers, but beyond the scope of this discussion. Suffice it to say that because Nothing is a subclass of every other class, the resulting type of otherVersion is KotlinVersion, as desired.

Assuming we make it to the last line in the equals method, now there is a value for otherVersion and a value for the current version. The comparison then checks version == otherVersion.version for equality (since they’re both Int values) and returns the result.

That’s quite a lot of power for three lines of code, and is a great example of how to implement an equivalence check for a nullable property (which happens to be another recipe in the book).

To complete the story, the class has a secondary constructor that can be used when the patch value is unknown.

public constructor(major: Int, minor: Int) : this(major, minor, 0)

Then there are two overloads of the isAtLeast function:

public fun isAtLeast(major: Int, minor: Int): Boolean =
    this.major > major || 
        (this.major == major && this.minor >= minor)

public fun isAtLeast(major: Int, minor: Int, patch: Int): Boolean =
    this.major > major || 
        (this.major == major &&
            (this.minor > minor || 
                 this.minor == minor && this.patch >= patch))

A couple of tests show how the basic comparisons work:

fun `comparison of KotlinVersion instances work`() {
    val v12 = KotlinVersion(major = 1, minor = 2)
    val v1341 = KotlinVersion(1, 3, 41)
        { assertTrue(v12 < KotlinVersion.CURRENT) },
        { assertTrue(v1341 <= KotlinVersion.CURRENT) },
        { assertEquals(KotlinVersion(1, 3, 41),
            KotlinVersion(major = 1, minor = 3, patch = 41)) }

fun `versions are Ints less than max`() {
    val max = KotlinVersion.MAX_COMPONENT_VALUE
        { assertTrue(KotlinVersion.CURRENT.major < max) },
        { assertTrue(KotlinVersion.CURRENT.minor < max) },
        { assertTrue(KotlinVersion.CURRENT.patch < max) }

Because the KotlinVersion class implements Comparable, it can be used in a range and has a contains method. In other words, you can write:

fun `check current version inside range`() {
    assertTrue(KotlinVersion.CURRENT in 

What you can not do, however, is to iterate over that range, because ranges are not progressions, but that’s a post for another day.

I hope you enjoyed this deep dive into what is arguably a trivial, but highly instructive, class in the Kotlin library. The GitHub repository for the book is located here and contains this example as well as many, many others.