DEV Community: Manh-Ha VU

Mastering Kotlin indexed access operator

Manh-Ha VU — Sun, 24 May 2020 13:44:12 +0000

Indexed access operator in Kotlin provides an easy-to-read syntax for random-access like data structures like Array, List and Map, ... But Kotlin is powerful enough that we can implement our own indexed access operator for our custom data structure. In this post, we will walk through a chessboard example to understand better this operator and also operator overloading in general.

You might have seen it, many times

If you have ever called the set/get method on a List/Array/Map on Kotlin,

nutritionFacts.set("Saturated fat", 10.grams)

// and later on
nutritionFacts.get("Saturated fat")

you might have encountered this suggestion from IntelliJ/Android Studio: "Should be replaced with indexing ...". And if you accept the suggestion, your code might turn out to be like this:

nutritionFacts["Saturated fat"] = 10.grams

// and retrieve
val quantity = nutritionFacts["Saturated fat"]

This situation can be seen often when you copy a code in Java then convert it to Kotlin in IntelliJ/Android Studio. The pair of brackets [ ] which encapsulate an index value (a string "Saturated fat" in the previous example) is the indexed access operator. It serves generally two purposes: get (retrieve) and set (mutate) value of an index. The set part is of course only applicable for mutable collections (Array, MutableList, HashMap, ...).

This operator is very obvious if you are using a collection type and key value of some primitive types (Int, String, ...). But what if we want the to use this operator on a data structure of our own?

In the next sections, we will work on a data structure which represents a chess board and we will implement this operator on this data structure to simplify access

We start with a chess board model

enum class Kind {
    KING, QUEEN, ROOK, BISHOP, KNIGHTS, PAWN
}

enum class Color {
    BLACK, WHITE
}

data class Piece(
    val color: Color, 
    val kind: Kind
)

class ChessBoard {
    private val squares: Array<Array<Piece?>> = Array(SIZE) {
        Array(SIZE) { null }
    }

    companion object {
        const val SIZE: Int = 8
    }
}

We then need a way to set/assign a piece to a square in a chess board. It is necessary if we want to implement higher level operation (move, checkmate, ...). A simplest way could be:

class ChessBoard {
    fun set(row: Int, column: Int, piece: Piece?) {
        squares[row][column] = piece
    }
}

val blackRook = Piece(BLACK, ROOK)
board.set(0, 7, blackRook) // assign blackRook to square (0, 7)
// later
board.set(0, 7, null) // remove the rook

Even if the set method is easy to understand for a developer, it is not obvious for a chess player. We should always aim to use the same language as domain experts. Otherwise, we also have leaked the implementation detail (array index based for row and column) to our API (set method). And the set method signature does not restrict the value for row and column.

Refactoring with indexed access operator

The standard method for recording moves in chess is algebraic notation, meaning using pairs like b4, e6, ... to identify squares in the board. To be coherent with the game we will you this notation in our code.

// Ranks (rows) denoted 1 to 8 from bottom to top according to White's perspective
//
// Raw value of rank is used as array index in chessboard. It is reversed compared to rank
// because rows in array is 0 to 7 from top to bottom
enum class Rank(internal val rawValue: Int) { 
    ONE(7), TWO(6), THREE(5), FOUR(4), FIVE(3), SIX(2), SEVEN(1), EIGHT(0)
}

// Columns
enum class File(internal val rawValue: Int) {
    A(0), B(1), C(2), D(3), E(4), F(5), G(6), H(7)
}

Then we can update our set method:

class ChessBoard {
    fun set(file: File, rank: Rank, piece: Piece?) {
        squares[rank.rawValue][file.rawValue] = piece
    }
}

val blackRook = Piece(BLACK, ROOK)
board.set(H, ONE, blackRook) // assign blackRook to square h1

Now we have a better method signature, if we can think about the indexing syntax:

board[H, ONE] = blackRook

by just adding operator keyword to our set method and voilà. Yes, that's easy as pie 😉.

class ChessBoard {
    operator fun set(file: File, rank: Rank, piece: Piece?) {
        squares[rank.rawValue][file.rawValue] = piece
    }
}

Behind the scene, the operator keyword and the method name set is telling Kotlin compiler that we are defining the behavior of indexed access operator for our class Chessboard. The name set is mandatory for this operator.

And we can now define the accessor method (get) with the same idea:

class ChessBoard {
    operator fun get(file: File, rank: Rank): Piece? {
        return squares[rank.rawValue][file.rawValue]
    }
}

val piece = board[H, ONE]

Alternative implementation

Depending on your taste, you might prefer 1D index to 2D one, like

val piece = board[sqr(H, ONE)]

We just need a little adaptation for previous code:

data class Square(
    val file: File, 
    val rank: Rank
)

fun sqr(file: File, rank: Rank): Square {
    return Square(file, rank)
}

class Chessboard {
    operator fun set(square: Square, piece: Piece?) {
        squares[square.rank.rawValue][square.file.rawValue] = piece
    }

    operator fun get(square: Square): Piece? {
        return squares[square.rank.rawValue][square.file.rawValue]
    }
}

Conclusion

Indexed access operator is a great improvement for container-like data structures with random access characteristic to increase the readability of your code. In this post, we've gone through implementations of 2D and 1D index for a custom data structure. You have now all it takes to implement your own.

Indexed access operator is one specific case of operator overloading. If done incorrectly or used abusively, instead of making our code easier to read, it can lead to very unnecessary cryptic code. As with great power comes great responsibility, we should use them with caution.

Using Kotlin scope functions to create deeply nested Java objects easily

Manh-Ha VU — Tue, 19 May 2020 07:42:14 +0000

In some cases, especially when working with an API with a provided Java SDK, we often find ourselves in creating a (very) deeply nested Java object using setters. Creating Java object with a lot of setters is annoying and error-prone. Kotlin scope function can help to make our code much more readable in these cases.

Problem

Here is a short example of object creation using setters to understand the problem. A more complex example can be found below.

val name = PersonalName()
name.firstName = "Wile"
name.surname = "Coyote"
name.surnamePrefix = "E."
name.title = "Mr."

val personalInformation = PersonalInformation()
personalInformation.dateOfBirth = "19490917"
personalInformation.gender = "male"
personalInformation.name = name

In this example, we have to introduce unnecessary variables to set the child objects, which might easily introduce a bug if forgetting to link mother and child objects.

If Address and PersonalName are data classes, things might get easier:

PersonalInformation(
    dateOfBirth = "19490917"
    gender = "male"
    name = PersonalName(
        firstName = "Wile"
        surname = "Coyote"
        surnamePrefix = "E."
        title = "Mr."
    )
)

Unfortunately, these classes are part of an external library, we should not, of course, waste our time rewriting them. But, can we do it better? Yes, we can use the excellent scope function apply() for this job.

Refactor using Kotlin scope function

Before giving more explanation in the next section, we will use directly the apply() function to demonstrate the power of the scope function. The apply function is an extension function that is available on any class.

// PersonalName can be rewritten as
val name = PersonalName().apply {
    firstName = "Wile"
    surname = "Coyote"
    surnamePrefix = "E."
    title = "Mr."
}

// And PersonalInformation can be rewritten
val personalInformation = PersonalInformation().apply {
    dateOfBirth = "19490917"
    gender = "male"
    name = name
}

or without the intermediary variable name:

PersonalInformation().apply {
    dateOfBirth = "19490917"
    gender = "male"
    name = PersonalName().apply {
      firstName = "Wile"
      surname = "Coyote"
      surnamePrefix = "E."
      title = "Mr."
  }
}

We can see that this version is not far from the data class version. A more complex example can be found below.

How does apply() work?

apply() function is actually pretty simple. It has following (simplified) signature:

fun <T> T.apply(block: T.() -> Unit): T {
    block()
    return this
}

If you aren't familiar with T.() -> Unit, technically it is a function literal with receiver. In other words, inside the block() function, we have access to the T object via this reference. Using the same example above:

val name = PersonalName().apply {
    firstName = "Wile"
    surname = "Coyote"
    surnamePrefix = "E."
    title = "Mr."
}

// is actually equivalent to this more verbose code
val name = PersonalName().apply {
    this.firstName = "Wile"
    this.surname = "Coyote"
    this.surnamePrefix = "E."
    this.title = "Mr."   
}

In the second code block, this = current instance of PersonalName = T in the apply() signature. In a Kotlin/Java class, most of the time, when calling class' method/property, you don't need to specify this reference. This is the same idea as in the first code block.

Without the receiver syntax, meaning:

fun <T> T.apply(block: (T) -> Unit): T

we'd have to write by specifying it reference in the block(). The code is a little longer and less natural. In this case, it = current instance of PersonalName

val name = PersonalName().apply {
    it.firstName = "Wile"
    it.surname = "Coyote"
    it.surnamePrefix = "E."
    it.title = "Mr."
}

Apply() is not the only scope function, there are more other functions like also, let, use, with, ... which are very well explained in the Kotlin reference. We might talk more about them in a later post.

More complex example

All examples of this post are borrowed from Ingenico API documentation.

Before using apply()

val billingAddress = Address()
billingAddress.additionalInfo = "b"
billingAddress.city = "Monument Valley"
billingAddress.countryCode = "US"
billingAddress.houseNumber = "13"
billingAddress.state = "Utah"
billingAddress.street = "Desertroad"
billingAddress.zip = "84536"

val name = PersonalName()
name.firstName = "Wile"
name.surname = "Coyote"
name.surnamePrefix = "E."
name.title = "Mr."

val personalInformation = PersonalInformation()
personalInformation.dateOfBirth = "19490917"
personalInformation.gender = "male"
personalInformation.name = name

val customer = Customer()
customer.accountType = "none"
customer.billingAddress = billingAddress
customer.locale = "en_US"
customer.merchantCustomerId = "1234"
customer.personalInformation = personalInformation

After using apply():

Customer().apply {
    accountType = "none"
    billingAddress = Address().apply {
        additionalInfo = "b"
        city = "Monument Valley"
        countryCode = "US"
        houseNumber = "13"
        state = "Utah"
        street = "Desertroad"
        zip = "84536"
    }
    locale = "en_US"
    merchantCustomerId = "1234"
    personalInformation = PersonalInformation().apply {
        dateOfBirth = "19490917"
        gender = "male"
        name = PersonalName().apply {
            firstName = "Wile"
            surname = "Coyote"
            surnamePrefix = "E."
            title = "Mr."
        }
    }
}

Conclusion

This post has just touched the tip of the iceberg on the expressivity power of Kotlin. With just a very small function like apply(), the readability of our code has been improved considerably. Working with deeply nested Java object is no longer a hassle in Kotlin.