Functions

Icon

The documentation for Kotlin is now located on the new site. This page is kept for historical reasons

Functions in Kotlin are declared with the fun keyword:

fun double(x : Int) : Int { 
  return x * 2 
}

A function call goes in the traditional way:

val two = demo(1)

See also Infix calls and Operator overloading.

Single-expression functions

If a function just returns a value of a single expression, one can specify its body after '=' and with no return statement:

fun double(x : Int) : Int = x * 2

In this case, it is allowed to omit the return type annotation, and the type will be inferred from the expression on the right-hand side:

fun double(x : Int) = x * 2

`Unit`-returning functions

If a function does not return any useful value, its return type is Unit. Unit is a type with only one value — Unit.VALUE. This value does not have to be returned explicitly:

fun printHello(name : String?) : Unit { 
  if (name != null) 
    print("Hello, $name!") 
  else 
    print("Hi there!") 
  // We don't need to write 'return Unit.VALUE' or 'return', although we could 
}

Neither has the Unit return type to be specified explicitly:
If a function has a block body (in curly braces, not after '=') and returns Unit, one can omit the return type annotation:

fun printHello(name : String?) { 
//... 
}

Local functions

Kotlin supports local functions, i.e. one can define a function inside a function:

fun dfs(graph : Graph){ 
  fun dfs(current : Vertex, visited : Set<Vertex>) { 
    if (!visited.add(current)) return 
    for (v in current.neighbors) 
      dfs(v, visited) 
  } 
 
  dfs(graph.vertices[0], HashSet()) 
}

Local functions can "see" local variables of outer functions (i.e. the closure), so we can have our visited set as a local variable, not a parameter to always pass around:

fun dfs(graph : Graph){ 
  val visited = HashSet<Vertex>() 
  fun dfs(current : Vertex) { 
    if (!visited.add(current)) return 
    for (v in current.neighbors) 
      dfs(v) 
  } 
 
  dfs(graph.vertices[0]) 
}

Local functions can even return from outer functions using qualified return expressions:

fun reachable(from : Vertex, to : Vertex) : Boolean { 
  val visited = HashSet<Vertex>() 
  fun dfs(current : Vertex) { 
    // here we return from the outer function: 
    if (current == to) return@reachable true 
    // And here -- from local function: 
    if (!visited.add(current)) return 
    for (v in current.neighbors) 
      dfs(v) 
  } 
 
  dfs(from) 
  return false // if dfs() did not return true already 
}

Member functions

A member function is a function defined inside a class:

class Sample() { 
  fun foo() { print("foo") } 
}

Member functions are called with a dot:

Sample().foo() // creates a new object of Sample and calls foo() on it

See Classes and Inheritance.

Generic functions

Functions may have generic parameters which can be specified in angle brackets after the function name and before the value parameters:

fun singletonArray<T>(item : T) : Array<T> { 
  return Array<T>(1, {item}) 
}

More on generic functions can be found on the page dedicated to generics.

Varargs

The last argument of a function may be marked with vararg annotation:

fun asList<T>(vararg
 ts : T) : List<T> {
  val result = ArrayList<T>() 
  for (t in ts) // ts is an Array 
    result.add(t) 
  return result 
}

By default, vararg creates an array, but this behavior can be customized by providing arguments to the annotation:

fun asList<T>(vararg
<ArrayList<T>> ts : T) : List<T> = ts // ts is a List now!

The type argument to the vararg annotation denotes a builder type. A call to this function is compiled like this:

asList(0, 1, 2) 
// Compiles to 
val list = ArrayList<Int>(3) // 3 is the size of the structure 
list.add(0) 
list.add(1) 
list.add(2) 
asList(list.build()) // For ArrayList, build() just returns the list itself

So, the vararg builder must be a type that has

A constructor that takes one Int parameter
An add() function
A build() function
The type of the vararg parameter if the returned type of build().

Default arguments

Function parameters may have default values, which are used when a corresponding argument is omitted. This allows to reduce the number of overloads, compared to Java:

// In java.io.InputStream this function has two versions: 
fun read(b : Array<Byte>, off : Int = 0, len : Int = -1) { 
  val actualLength = if (len == -1) b.length else len 
  // ... 
}

This function may be called in three forms:

read(b, off, len) 
read(b, off) // len = -1, effectively, b.length 
read(b) // off = 0, len = -1

Named arguments

When a function has many parameters (and many of them have defaults), it is very convenient to see parameter names at the call site. Consider the following function in:

fun reformat( 
  str : String, 
  normalizeCase : Boolean = true, 
  uppercaseFirstLetter : Boolean = true, 
  divideByCamelHumps : Boolean = false, 
  wordSeparator : Character = ' ' 
) { 
  // ... 
}

The best-case call site is fine:

reformat(str)

But what if we want to change the word separator without changing the flags?

reformat(str, true, true, false, '_')

Without named arguments, a call site is hard to read. To document it, we can provide parameter names for each argument:

reformat(str, 
    normalizeCase = true, 
    uppercaseFirstLetter = true, 
    divideByCamelHumps = false, 
    wordSeparator = '_' 
  )

It is better already, but we can improve it: there's no need to specify all the arguments if some of the default values are fine for us:

reformat(str, wordSeparator = '_')

Infix calls

If a member function (or an extension function) takes one parameter, it may be called in infix form, i.e. without a dot after receiver and parentheses around the arguments:

1 shl 2 
// is the same as 
1.shl(2)

An infix call must have two parameters. One is not allowed to say, e.g. print 1, because there's nothing on the left of print.

Infix calls associate to the left, i.e. 1 foo 2 bar 3 means (1 foo 2) bar 3.

For precedence, see the grammar.

Extension functions

Extension functions allow us to define a function having some type as a receiver:

fun Int.abs() : Int = if (this >= 0) this else -this

This function can be called on any Int with a dot, as if it were a member function:

print((-1).abs())

For more details, see Extension functions.

Higher-order functions

A higher-order function is a function that takes functions as parameters, or returns a function. A good example of such a function is lock() that takes a lock object and a function, acquires the lock, runs the functions and releases the lock:

fun lock<T>(lock : Lock, body : () -> T) : T { 
  lock.lock() 
  try { 
    return body() 
  } 
  finally { 
    lock.unlock(); 
  } 
}

Let's examine the code above: body has a function type: () -> T, so it's supposed to be a function that takes no parameters and returns a value of type T. It is invoked inside the try block, while protected by the lock, and its result is returned by the lock() function.

If we want to call lock(), we can pass a function literal to it as an argument:

val result = lock(lock, { sharedResource.operation() })

Function literals are described in details on this page. Here we only give a superficial description:

a function literal is always surrounded by curly braces,
its parameters (if any) are declared before -> (parameter types may be omitted),
the body goes after ->.
In our case, there are no parameters, and the expression in the curly braces is the function literal body.

There is a convention in Kotlin that makes our example look nicer:

if the last parameter of a function is itself a function, the corresponding function literal may be passed outside the parentheses:
lock (lock) {
sharedResource.operation()
}
This makes our code look more like a 'control structure'.

Another example of a higher order function would be map() (of Map/Reduce):

fun <T, R> List<T>.map(transform : (T) -> R) : List<R> { 
  val result = ArrayList<R>() 
  for (item in this) 
    result.add(transform(item)) 
  return result 
}

This function can be called as follows:

val doubled = ints.map {it -> it * 2}

One other convention helps us here:

if a function literal has only one parameter, its declaration may be omitted (along with the ->) and its name will be it:
ints map {it * 2} // Infix call + Implicit 'it'

These conventions allow us to write LINQ-like expressions:

strings filter {it.length == 5} sortBy {it} map {it.toUpperCase()}

Non-local returns are not implemented yet

Icon

See the corresponding issue.

Extension function literals

Like named extension functions, function literals may declare receiver parameters. This allows us to write things like Groovy-style builders in a type-safe way.

Learn more here and here.

Inline functions

Using higher-order functions imposes certain runtime penalties: each function is an object, and it captures a closure, i.e. those variables that are accessed in the body of the function. Memory allocations (both for function objects and classes) and virtual calls introduce runtime overhead. Plus, classes generated for lambdas bloat the bytecode on disk and PermGen at runtime.

But it appears that in many cases this kind of overhead can be eliminated by inlining the function literals. The functions shown above are good examples of this situation. I.e., the lock() function could be easily inlined at call-sites. Consider the following case:

lock(l) {foo()}

Instead of creating a function object for the parameter and generating a call, the compiler could emit the following code:

lock.lock() 
try { 
  foo() 
} 
finally { 
  lock.unlock() 
}

Isn't it what we wanted from the very beginning?

To make the compiler do this, one needs to annotate the lock() function with the inline annotation:

inline fun lock<T>(lock : Lock, body : () -> T) : T { 
  // ... 
}

Inlining may cause the generated code to grow, but if we do it in a reasonable way (do not inline big functions) it will pay off in performance, especially at "megamorphic" call-sites inside loops.

General guidelines for what functions should be marked inline:

Do not inline big functions.
The primary purpose of inline function is to inline lambdas at call sites. It is rarely a good idea to inline a function that does not take other functions as arguments.

Some functions can not be inlined. For example, if you do not call a lambda argument, but use it as a value (e.g. put it into a map).
The compiler will refuse to accept inline annotation on such functions.

By default, all functional parameters are inlined at the call site, if you want some of them to be passed as values instead, annotate these parameters with noinline:

inline fun twofun(a: () -> Int, noinline b: () -> Int) { 
    a() // only call: fine for inlined parameter 
    mylist.add(b) // add to collection, fine only for noinline parameter 
}

Inline functions are in *experimental* state

Icon

To disable inlining, use the "-inline off" command line key.

See the corresponding issue.

Oct	NOV	Dec
	23
2014	2015	2016

Single-expression functions

Unit-returning functions

Local functions

Member functions

Generic functions

Varargs

Default arguments

Named arguments

Infix calls

Extension functions

Higher-order functions

Extension function literals

Inline functions

What's next

79 Comments

Anonymous

Anonymous

Anonymous

Anonymous

Anonymous

Anonymous

Anonymous

Anonymous

Anonymous

Anonymous

Anonymous

Anonymous

Anonymous

Anonymous

Anonymous

Anonymous

`Unit`-returning functions