<commit_before>[//]: # (title: Nullability in Java and Kotlin)
[//]: # (description: Learn how to migrate nullable constructions from Java to Kotlin. This guide covers support for nullable types in Kotlin, how Kotlin treats nullable annotations from Java, and more.)

_Nullability_ is the ability of a variable to hold a `null` value.
When a variable contains `null`, an attempt to dereference the variable leads to a `NullPointerException`.
There are many ways to write code in order to minimize the probability of receiving null pointer exceptions.

This guide covers differences between Java's and Kotlin's approaches to handling possibly nullable variables.
It will help you migrate from Java to Kotlin and write your code in authentic Kotlin style.

The first part of this guide covers the most important difference – support for nullable types in Kotlin and
how Kotlin processes [types from Java code](#platform-types). The second part, starting from
[Checking the result of a function call](#checking-the-result-of-a-function-call), examines several specific cases to explain certain differences.

[Learn more about null safety in Kotlin](null-safety.md).

## Support for nullable types

The most important difference between Kotlin's and Java's type systems is Kotlin's explicit support for [nullable types](null-safety.md).
It is a way to indicate which variables can possibly hold a `null` value.
If a variable can be `null`, it's not safe to call a method on the variable because this can cause a `NullPointerException`.
Kotlin prohibits such calls at compile time and thereby prevents lots of possible exceptions.
At runtime, objects of nullable types and objects of non-nullable types are treated the same:
A nullable type isn't a wrapper for a non-nullable type. All checks are performed at compile time.
That means there's almost no runtime overhead for working with nullable types in Kotlin.

> We say "almost" because, even though [intrinsic](https://en.wikipedia.org/wiki/Intrinsic_function) checks _are_ generated,
their overhead is minimal.
>
{type="note"}

In Java, if you don't write null checks, methods may throw a `NullPointerException`:

```java
// Java
int stringLength(String a) {
    return a.length();
}

void main() {
    stringLength(null); // Throws a `NullPointerException`
}
```
{id="get-length-of-null-java"}

This call will have the following output:

```java
java.lang.NullPointerException: Cannot invoke "String.length()" because "a" is null
    at test.java.Nullability.stringLength(Nullability.java:8)
    at test.java.Nullability.main(Nullability.java:12)
    at java.base/java.util.ArrayList.forEach(ArrayList.java:1511)
    at java.base/java.util.ArrayList.forEach(ArrayList.java:1511)
```

In Kotlin, all regular types are non-nullable by default unless you explicitly mark them as nullable.
If you don't expect `a` to be `null`, declare the `stringLength()` function as follows:

```kotlin
// Kotlin
fun stringLength(a: String) = a.length
```
{id="get-length-kotlin"}

The parameter `a` has the `String` type, which in Kotlin means it must always contain a `String` instance and it cannot contain `null`.
Nullable types in Kotlin are marked with a question mark `?`, for example, `String?`.
The situation with a `NullPointerException` at runtime is impossible if `a` is `String` because the compiler enforces
the rule that all arguments of `stringLength()` not be `null`.

An attempt to pass a `null` value to the `stringLength(a: String)` function will result in a compile-time error,
"Null can not be a value of a non-null type String":

![Passing null to a non-nullable function error](passing-null-to-function.png){width=700}

If you want to use this function with any arguments, including `null`, use a question mark after the argument type `String?`
and check inside the function body to ensure that the value of the argument is not `null`:

```kotlin
// Kotlin
fun stringLength(a: String?): Int = if (a != null) a.length else 0
```
{id="get-length-of-null-kotlin"}

After the check is passed successfully, the compiler treats the variable as if it were of the non-nullable type `String`
in the scope where the compiler performs the check.

If you don't perform this check, the code will fail to compile with the following message:
"Only [safe (?.)](null-safety.md#safe-calls) or [non-null asserted (!!.) calls](null-safety.md#the-operator) are allowed
on a [nullable receiver](extensions.md#nullable-receiver) of type String?".

You can write the same shorter – use the [safe-call operator ?. (If-not-null shorthand)](idioms.md#if-not-null-shorthand), 
which allows you to combine a null check and a method call into a single operation:

```kotlin
// Kotlin
fun stringLength(a: String?): Int = a?.length ?: 0
```
{id="get-length-of-null-shorter-kotlin"}

## Platform types

In Java, you can use annotations showing whether a variable can or cannot be `null`.
Such annotations aren't part of the standard library, but you can add them separately.
For example, you can use the JetBrains annotations `@Nullable` and `@NotNull` (from the `org.jetbrains.annotations` package)
or annotations from Eclipse (`org.eclipse.jdt.annotation`).
Kotlin can recognize such annotations when you're [calling Java code from Kotlin code](java-interop.md#nullability-annotations)
and will treat types according to their annotations.

If your Java code doesn't have these annotations, then Kotlin will treat Java types as _platform types_.
But since Kotlin doesn't have nullability information for such types, its compiler will allow all operations on them.
You will need to decide whether to perform null checks, because:

* Just as in Java, you'll get a `NullPointerException` if you try to perform an operation on `null`.
* The compiler won't highlight any redundant null checks, which it normally does when you perform a null-safe operation
on a value of a non-nullable type.

Learn more about [calling Java from Kotlin in regard to null-safety and platform types](java-interop.md#null-safety-and-platform-types).

## Checking the result of a function call

One of the most common situations where you need to check for `null` is when you obtain a result from a function call.

In the following example, there are two classes, `Order` and `Customer`. `Order` has a reference to an instance of `Customer`.
The `findOrder()` function returns an instance of the `Order` class, or `null` if it can't find the order.
The objective is to process the customer instance of the retrieved order.

Here are the classes in Java:

```java
//Java
record Order (Customer customer) {}

record Customer (String name) {}
```

In Java, call the function and do an if-not-null check on the result to proceed with the dereferencing of the required property:

```java
// Java
Order order = findOrder();

if (order != null) {
    processCustomer(order.getCustomer());
}
```
{id="process-customer-if-not-null-java"}

Converting the Java code above to Kotlin code directly results in the following:

```kotlin
// Kotlin
data class Order {
  val customer: Customer
}

data class Customer {
  val name: String
}

val order = findOrder()

// Direct conversion
if (order != null){
    processCustomer(order.customer)
}
```
{id="process-customer-if-not-null-kotlin"}

Use the [safe-call operator `?.` (If-not-null shorthand)](idioms.md#if-not-null-shorthand) 
in combination with any of the [scope functions](scope-functions.md) from the standard library.
The `let` function is usually used for this:

```kotlin
// Kotlin
val order = findOrder()

order?.let {
    processCustomer(it.customer)
}
```
{id="process-customer-with-let-kotlin"}

Here is a shorter version of the same:

```kotlin
// Kotlin
findOrder()?.customer?.let(::processCustomer)
```<commit_msg>Fix compilation error in java-to-kotlin-nullability-guide.md (#3231)<commit_after>[//]: # (title: Nullability in Java and Kotlin)
[//]: # (description: Learn how to migrate nullable constructions from Java to Kotlin. This guide covers support for nullable types in Kotlin, how Kotlin treats nullable annotations from Java, and more.)

_Nullability_ is the ability of a variable to hold a `null` value.
When a variable contains `null`, an attempt to dereference the variable leads to a `NullPointerException`.
There are many ways to write code in order to minimize the probability of receiving null pointer exceptions.

This guide covers differences between Java's and Kotlin's approaches to handling possibly nullable variables.
It will help you migrate from Java to Kotlin and write your code in authentic Kotlin style.

The first part of this guide covers the most important difference – support for nullable types in Kotlin and
how Kotlin processes [types from Java code](#platform-types). The second part, starting from
[Checking the result of a function call](#checking-the-result-of-a-function-call), examines several specific cases to explain certain differences.

[Learn more about null safety in Kotlin](null-safety.md).

## Support for nullable types

The most important difference between Kotlin's and Java's type systems is Kotlin's explicit support for [nullable types](null-safety.md).
It is a way to indicate which variables can possibly hold a `null` value.
If a variable can be `null`, it's not safe to call a method on the variable because this can cause a `NullPointerException`.
Kotlin prohibits such calls at compile time and thereby prevents lots of possible exceptions.
At runtime, objects of nullable types and objects of non-nullable types are treated the same:
A nullable type isn't a wrapper for a non-nullable type. All checks are performed at compile time.
That means there's almost no runtime overhead for working with nullable types in Kotlin.

> We say "almost" because, even though [intrinsic](https://en.wikipedia.org/wiki/Intrinsic_function) checks _are_ generated,
their overhead is minimal.
>
{type="note"}

In Java, if you don't write null checks, methods may throw a `NullPointerException`:

```java
// Java
int stringLength(String a) {
    return a.length();
}

void main() {
    stringLength(null); // Throws a `NullPointerException`
}
```
{id="get-length-of-null-java"}

This call will have the following output:

```java
java.lang.NullPointerException: Cannot invoke "String.length()" because "a" is null
    at test.java.Nullability.stringLength(Nullability.java:8)
    at test.java.Nullability.main(Nullability.java:12)
    at java.base/java.util.ArrayList.forEach(ArrayList.java:1511)
    at java.base/java.util.ArrayList.forEach(ArrayList.java:1511)
```

In Kotlin, all regular types are non-nullable by default unless you explicitly mark them as nullable.
If you don't expect `a` to be `null`, declare the `stringLength()` function as follows:

```kotlin
// Kotlin
fun stringLength(a: String) = a.length
```
{id="get-length-kotlin"}

The parameter `a` has the `String` type, which in Kotlin means it must always contain a `String` instance and it cannot contain `null`.
Nullable types in Kotlin are marked with a question mark `?`, for example, `String?`.
The situation with a `NullPointerException` at runtime is impossible if `a` is `String` because the compiler enforces
the rule that all arguments of `stringLength()` not be `null`.

An attempt to pass a `null` value to the `stringLength(a: String)` function will result in a compile-time error,
"Null can not be a value of a non-null type String":

![Passing null to a non-nullable function error](passing-null-to-function.png){width=700}

If you want to use this function with any arguments, including `null`, use a question mark after the argument type `String?`
and check inside the function body to ensure that the value of the argument is not `null`:

```kotlin
// Kotlin
fun stringLength(a: String?): Int = if (a != null) a.length else 0
```
{id="get-length-of-null-kotlin"}

After the check is passed successfully, the compiler treats the variable as if it were of the non-nullable type `String`
in the scope where the compiler performs the check.

If you don't perform this check, the code will fail to compile with the following message:
"Only [safe (?.)](null-safety.md#safe-calls) or [non-null asserted (!!.) calls](null-safety.md#the-operator) are allowed
on a [nullable receiver](extensions.md#nullable-receiver) of type String?".

You can write the same shorter – use the [safe-call operator ?. (If-not-null shorthand)](idioms.md#if-not-null-shorthand), 
which allows you to combine a null check and a method call into a single operation:

```kotlin
// Kotlin
fun stringLength(a: String?): Int = a?.length ?: 0
```
{id="get-length-of-null-shorter-kotlin"}

## Platform types

In Java, you can use annotations showing whether a variable can or cannot be `null`.
Such annotations aren't part of the standard library, but you can add them separately.
For example, you can use the JetBrains annotations `@Nullable` and `@NotNull` (from the `org.jetbrains.annotations` package)
or annotations from Eclipse (`org.eclipse.jdt.annotation`).
Kotlin can recognize such annotations when you're [calling Java code from Kotlin code](java-interop.md#nullability-annotations)
and will treat types according to their annotations.

If your Java code doesn't have these annotations, then Kotlin will treat Java types as _platform types_.
But since Kotlin doesn't have nullability information for such types, its compiler will allow all operations on them.
You will need to decide whether to perform null checks, because:

* Just as in Java, you'll get a `NullPointerException` if you try to perform an operation on `null`.
* The compiler won't highlight any redundant null checks, which it normally does when you perform a null-safe operation
on a value of a non-nullable type.

Learn more about [calling Java from Kotlin in regard to null-safety and platform types](java-interop.md#null-safety-and-platform-types).

## Checking the result of a function call

One of the most common situations where you need to check for `null` is when you obtain a result from a function call.

In the following example, there are two classes, `Order` and `Customer`. `Order` has a reference to an instance of `Customer`.
The `findOrder()` function returns an instance of the `Order` class, or `null` if it can't find the order.
The objective is to process the customer instance of the retrieved order.

Here are the classes in Java:

```java
//Java
record Order (Customer customer) {}

record Customer (String name) {}
```

In Java, call the function and do an if-not-null check on the result to proceed with the dereferencing of the required property:

```java
// Java
Order order = findOrder();

if (order != null) {
    processCustomer(order.getCustomer());
}
```
{id="process-customer-if-not-null-java"}

Converting the Java code above to Kotlin code directly results in the following:

```kotlin
// Kotlin
data class Order(val customer: Customer)

data class Customer(val name: String)

val order = findOrder()

// Direct conversion
if (order != null){
    processCustomer(order.customer)
}
```
{id="process-customer-if-not-null-kotlin"}

Use the [safe-call operator `?.` (If-not-null shorthand)](idioms.md#if-not-null-shorthand) 
in combination with any of the [scope functions](scope-functions.md) from the standard library.
The `let` function is usually used for this:

```kotlin
// Kotlin
val order = findOrder()

order?.let {
    processCustomer(it.customer)
}
```
{id="process-customer-with-let-kotlin"}

Here is a shorter version of the same:

```kotlin
// Kotlin
findOrder()?.customer?.let(::processCustomer)
```
{'fraction_non_alphanumeric': 0.0914168325094691, 'fraction_numerical': 0.0023110996982730948, 'mean_word_length': 4.691633175009134, 'pattern_counts': {'":': 2, '<': 3, '<?xml version=': 0, '>': 7, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3429213', 'n_tokens_mistral': 4408, 'n_tokens_neox': 4203, 'n_words': 2045}