If you have experience with Java, then you probably have seen a class with multiple overloaded methods, or a class with multiple constructors that differ in a parameter count to provide better usability to users. String or Thread classes from the Java standard library are good examples of this. The problem is that, a lot of code has to be duplicated, and if you are writing a library, you'll probably want to have Java documents on each method, which again have to be duplicated.

Let's take a look at an example from the Java standard library. The String class has overloaded indexOf methods; this one accepts two integers as arguments. The first one is the Unicode character representation, and the second one is the index to start the search from:

public int indexOf(int ch, int fromIndex) {
    //omitted
}

Then, there is another overload of this method, which just calls the first one and provides a default argument for the start of a search index:

public int indexOf(int ch) {
    return indexOf(ch, 0);
}

Thanks to default parameter values, if this function was defined in Kotlin, no overloads would be needed. When defining a function parameter, you can also assign it a default value. This is how it would look in Kotlin:

fun indexOf(ch: Int, fromIndex: Int = 0) {
    //omitted
}

And when calling this function, you won't have to provide arguments that don't have a default value:

indexOf(65)

Of course, you can override the default argument value with your own:

indexOf(65, 1)

Default argument values are really useful when combined with named arguments. This gives you the option to specify arguments in any order you wish and omit ones that have default values.

Default argument values can also be used in class constructors. This User class has three constructors:

class User {

    constructor(name: String) : this(name, null)

    constructor(name:String,
                phoneNumber: String?) : this(name, phoneNumber, false)

    constructor(name:String,
                phoneNumber: String?,
                isLoggedIn: Boolean) {
        //omitted
    }
}

We can simplify this and have only one constructor:

class User(name: String,
           phoneNumber: String? = null,
           isLoggedIn: Boolean = false)

Since Java doesn't have default argument values, they can only be used in functions defined in Kotlin. If you plan on exposing your code to Java, Kotlin provides the @JvmOverloads annotation, which instructs the Kotlin compiler to produce overloaded methods for each default argument value. If we had this factory function:

@JvmOverloads
fun createUser(name: String, phoneNumber: String = "", loggedIn: Boolean = false) : User {
    return User(name, phoneNumber, loggedIn)
}

The compiler would then produce the following overloads and the code would look like this in Java:

public static final User createUser(@NotNull String name)

public static final User createUser(@NotNull String name, @NotNull String phoneNumber)

public static final User createUser(@NotNull String name, @NotNull String phoneNumber, boolean loggedIn)