General convention

Although one might think that kotlin has inherited all the base collection types from the Java it's not quite true. Kotlin transparently maps existing Java collections into the Kotlin by using some tricks such as typealiasing. Collections hierarchy in Kotlin make code even more safer by imposing separation between mutable and immutable data structures. Take a look on the interfaces diagram:

Having dedicated interfaces for immutable collections makes expressions are purely functional - no need to worry if api consumer modifies list on the way or even worse, attempt to insert into the immutable collection(goodbye UnsupportedOperationException!). Indeed, immutability is enforced in compile time by contract.

A note about Iterable vs Sequence

Those are very similar types of the base entities even with the same signatures, let's take a look

public interface Sequence<out T> {
    public operator fun iterator(): Iterator<T>
}

public interface Iterable<out T> {
    public operator fun iterator(): Iterator<T>
}

Those two base classes define the way data will be processed in the chain of the calls:

• Operations on Iterable produce result immideatelly, so the full intermideate result will be passed between calls in the chain. The result is evaluated eagerly after each step.
• Operations on the Sequence treat data items comming thorough as it would be an infinite stream, the closest analogy would be java8 Stream or RxObservable. Items passed via the chain of the calls one by one. Result is evaluated lazily.

As for now we focus on the Iterable and it's descendants(Collection, List, Map, etc..) . Luckily, many operations exist for both interfaces with exactly the same signatures

Simple list transformations filter, map, forEach

Those are the probably the most widely used operators and they do exactly after their name. The provided function is applied to the each element of the operation

val adminNames = users
  .filter { it.isAdmin }
  .map { it.name }

pupils.forEach { 
  println("${it.name}: ${it.score}")
}

filter* and map* families

There are way more similar operations provided in the Kotlin stdlib giving extra flexibility when it need:

val userList = users
  .filterNotNul()
  .filterNot { it.isBanned }
  .mapTo(mutableHashSet()) { it.userId }
  .mapIndexed { (idx, userId) -> "#${idx}: {it.userId}" }

In many occasions you'll find the same pattern - verb [not] [indexed] [to]. No need to memorise - the names come out intuitively:

Operations returning single element: first, last, single, elementAt, get

first and last return first and last elements (obviously).

val firstUser = users.first()
val firstAdminUser = users.first { it.isAdmin }
val lastBannedUser = users.last { it.isBanned }

single returns one element and throws exception if more than 1 element in collection matches the predicate

val oneLove = listOf("java", "kotlin",  "javascript").singleOrNull { it == "kotlin" } 

Also those operations can have return alternative value - provided by closure or null:

val oneLove = languages.singleOrNull { it == "kotlin" }
val tenthWinnerName = user.getOrElse(10) { "NO WINNER" }
val secondPerson = user.getOrNull(2)

Aggregation operations count, average, min, max

Again, intuitively those operations perform aggregations:

val avgScore = pupils.average { it.score }
val topStudent = pupils.max { it.score }
val channagingStudent = pupils.min { it.score }

Conditional oprations all, none, count, any

val numberOfTopStudents = pupils.count { it.score > 4.5 }
val allPassed = pupils.all { it.score > 2.0 }
val hasNeedleInHaystack = heap.any { it.object == NEEDLE }
val allGood = results.none { it.error != null }

List to Map transformation associate*, groupBy

Both operations produce a Map and they are different on how keys are collided. While assciate* simply overwrites existing value with associated key, groupBy adds value to the list of values:

val usersById = users.associate { it.id to it } // result type: Map<UserId, User>
val usersById = users.associateBy { it.id } // same output
val pupilsByScore = pupils.groupBy { it.score } // result type Map<Int, List<Pupil>>

Many more

There a way more functional operations over collections are available in Kotlin stdlib such as fold, reduce, minus(-), plus(+), contains(in) etc:

// result - list of the both users
val allUsers = fbUsers + twitterUsers 

// result - elements of allUserIds which are not in bannedUsersIds
val activeUserIds = allUserIds - bannedUsersIds 

// result - the longest length of the name
val longestName = names.reduce { longest, item -> if (longest.length < item.length) item else longest }

// result - same as above, the longest length of the name
val longestLength = names.map(String::length).fold(0, ::max))

// result - if Wally was there
val isWallyLovesKotlin = "Wally" in kotlinLovers

Those extension functions are very intuitive and widely used, essentially can cover most of the everyday tasks.

Conclusion

Kotlin collection functions provide a lot of flexibility to express your ideas and business logic in very concise, clear and functional way

Hopefully you found this article useful for you, please check out other posts by #kotlin-showoff hashtag

For folks who got lost on the word "extension functions" - it's a way to attach a function or property to the instances of the existing classes. For example, val d = 10.twice()It's very much like a classic Java Util classes with method twice(int) but done in a very clean way. Visually it looks like you're calling a member of the class, but in reality, the compiler calls your function passing receiver as an argument.

T.let

let allows passing given reciever into the parameter of the lambda, returns result from it. Essentially it's an map operator on the single value

val imageData = db.getUserById(userId)
    ?.let { it.getProfilePicture().url }
    ?.let { fetchData(it) }

How to use?

It's very useful when it comes to the conditional on nullable object, think of functional replacement for if (user != null) user.ban():

user?.let { it.ban() }
// or even
user?.let(::ban)

Often we use expressions in the string interpolation, .let can be very handy:

println("Hello ${db.getUser(id)?.let { it.name } ?: "NONAME"}")

T.apply

apply calls given lambda in the context of receiver, similar to the with found in JavaScript and Groovy.

User().apply {
    name = "user name"
    password = "qwerty"
}

How to use?

I found it's a way to patch encapsulate configuration/finish object initialisation. It helps to perform number of operations within lambda block which are logically related to the operation such as factory initialisation or object creation. apply returns the receiver object(object it was called on)

So instead of

val awsS3Client = AwsS3Client()
val credentials = AwsCredentialsFactory("key", "secret")
credentials.setForceHttps(true)
awsS3Client.credentials = credentials
awsS3Client.bucket = "my_bucket"

We can have nicely organized initialization block:

val awsS3Client = AwsS3Client().apply {
    credentials = AwsCredentialsFactory("key", "secret").apply {
        setForceHttps(true)
    }
    bucket = "my_bucket"
}

Nice and clean, without messy noise and scope pollution!

T.also

It behaves exactly as .let with one exception - with return result. .also takes receiver and passes it as an argument for the given lambda, returning the same receiver

val bannedUser = db.getUserById(userId)
   .also { println("Got user $it") }
   .ban()

How to use?

From my experience it can be used for debugging - as demonstrated above. Also, it can be used a replacement for the .apply, one can say it's more clear - based on the example for .apply:

val awsS3Client = AwsS3Client().also {
    it.credentials = AwsCredentialsFactory("key", "secret").apply {
        it.setForceHttps(true)
    }
    it.bucket = "my_bucket"
}

T.run / with()

These have very similar behaviour - they both change the context of the function but unlike .apply the result of the function would be something lambda returned

val userId = User().run {
    name = "username"
    password = "foobar"
    db.save(this).id
}

val userId = with(User()) {
    name = "username"
    password = "foobar"
    db.save(this).id
}

These two have identical behaviour - in both cases object is initialised, saved and generated id is returned - the result of the last line expression

How to use?

Well, I didn't find it used often in my code, but the example above may give you some idea

Combo

Some examples from the real projects

// filter out images with faces, print debug info, annotate 
// image with labels and filter images by stop words
val images = allImages
    // filter pics with faces if necessary
    ?.let { if (allowFaces) it else withoutFaces(word, it) }
    ?.also { log.info("findImageForWord: got ${it.size} pics after face filtering") }
    // image labelling
    ?.let { findLabels(word, it) }
    // exclude stop list words
    ?.filterNot { it.normalizedLabels.any { it in stopList } }


// Prepare video upload request for the YouTube API:
val video = Video().also {
    it.snippet = VideoSnippet().also {
        it.set("categoryId", "27")
        it.set("description", description)
        it.set("title", title)
        it.set("tags", tags)
    }
    it.status = status
}

I hope you found this article useful for you. Check out other posts about functional constructions to get the most out of kotlin

Essentially, elvis operator lvalue ?: rexpression is returning left value if it's not null or executes rexpression otherwise. The crazy thing about kotlin is most of the constructions are expressions and that gives another way to express business logic.

Returning alternative value

In the simplest case we can return alternative value if left value is null, for example

val userList = cache.get(userId) ?: fetch(userId)

Literally means: get value of cache.get(userId) if it's not null or fetch(userId)

In Java it can be expressed as

List<User> userList = cache.get(userId);
if (userList == null) userList = fetch(userId);

Also, it's possible to chain elvis operators

val userList = memoryCache.get(userId) 
     ?: diskCache.get(userId)
     ?: fetch(userId)

Looks lovely and clean, isn't it?

Early return with elvis

fun displayUsers() {
    val userList = cache.get(userId) 
        ?: return
    updateUiWithNewUserList(userList)
}

In this case return if userList is null function will return immideatelly

Throw exception with elvis operator

In Java code we often need to manage an exceptional situation and allow callers to handle it themselves. Take a look on this example:

void displayUsers() {
    List<User> userList = cache.get(userId);
    if (userList == null) 
        throw new NoDataAvailableException()
    . . . 
}

Employing elvis operator in kotlin it looks more concise and logic is encapsulated within one expression:

fun displayUsers() {
    val userList = cache.get(userId) 
        ?: throw NoDataAvailableException()
    . . .
}

Looks cleaner, isn't it?

Elvis operator with in loops

In the same way as we used early return it's possible to make elvis to work with break and continue, in case if you're still using loops

fun top10Score(users: List<User>): Int {
    var totalScore = 0
    for(i in 0 until Math.min(users.size, 10)) {
        val score = users[i].gameProgress?.score 
            ?: continue
        totalScore += score
    }
    return totalScore
}

If either gameProgress or score are null loop will continue to the next element.
By the way, there is a way expressive functional way to implement the same logic:

fun top10Score(users: List<User>): Int = users
    .take(10)
    .fold(0) { acc, it -> acc + (it.gameProgress?.score ?: 0) }

It works not only for nullable types

Kotlin has numerous extension functions allowing to express flow in the concise and functional manner. We'll dive into this topic in the following articles.

But here is a spoiler for you, say it's need to throw exception in validator when user didn't provide name or it was empty. From data point of view null isn't same as empty string, empty string isn't same as a string full of spaces. But in our business logic it's practically the same since no name is provided. Here is an example of handling this situation:

val name = user.name?.takeIf(String::isNotBlank)
    ?: throw UserNameIsEmptyException()

takeIf returns receiver object if predicate is true. Even user.name is not null but consist of empty string takeIf will return null because it doesn't satisfy condition. Exception will be thrown in this case and it's guaranteed by compiler that name is not null

Conclusion

Elvis operator in kotlin is very powerful and helps to handle conditional logic naturally within the data flow

This is a first of this series of posts unioned by tag #kotlin-showoff

As from my experience it takes literally two days for average developer to switch to kotlin from java and start to write meaningful business logic

As time goes by code can use more kotlin specific constructions which make code much more readable and expressive. In this blog post I'd like to show off some of the nice functional constructions which help to make code more idiomatic.

Extracting data from the nullable types

Say, we have an class Address within UserInfo which holds information about the given user's address. UserInfo is a part of the Person. UserInfo can be nullalbe as well as Address but we want to extract city name. In java it would look like:

    Person person;
    String city;
    if (person.userInfo != null && person.userInfo.address != null && person.userInfo.address.city != null)
        city = person.userInfo.address.city;
    else city = "Unknown city";

    System.out.println("User is in " + city);

If you think it's a safe code I have a bad news for you. Savvy java developer can immediately spot the issue - between checks and assigment to the city whole bunch of things can happen on another threads and eventually we can end up with accessing null. Hello NPE!

The correct approach would be to capture values while we're performing the check:

    UserInfo userInfo = person.userInfo;
    if (userInfo != null) {
        Address address = userInfo.address;
        if (address != null) {
            city = address.city;
        }
    }
    if (city == null) 
        city = "Unknown city";

    System.out.println("User is in " + city);

Expressivity is not Java best strength. But wait, with Java 8 we can make it a bit more readable (and still safe):

    city = Optional.ofNullable(person.userInfo)
            .map(userInfo -> userInfo.address)
            .map(address -> address.city)
            .orElse("Unknown city");

    System.out.println("User is in " + city);

Looks better, isn't it? Wait for kotlin

println("User is in ${person.userInfo?.address?.city ?: "Unknown city"}")

Sorry java ¯\_(ツ)_/¯

So what exactly happens here? The chain person.userInfo?.address?.city returns either city if it's not null or null. Then using elvis operator we make whole expression to return extracted city value or string "Unknown city". Even more, we can concatenate everything in one string as an expression

You can eat your cake, and have it too

Is it safe one might wonder? Yes, it is. Look into the generated code:

public final class KotlinImplKt {
   public static final void kotlinImpl() {
      StringBuilder var10000;
      String var4;
      label14: {
         Person person = new Person();
         var10000 = (new StringBuilder()).append("User is in ");
         UserInfo var10001 = person.userInfo;
         if (var10001 != null) {
            Address var3 = var10001.address;
            if (var3 != null) {
               var4 = var3.city;
               if (var4 != null) {
                  break label14;
               }
            }
         }

         var4 = "Unknown city";
      }

      String var1 = var10000.append(var4).toString();
      boolean var2 = false;
      System.out.println(var1);
   }
}

Check out other posts in #kotlin-showoff