Kotlin Null Safety: Complete Guide to Nullable Types and Safe Calls

// Non-nullable: cannot ever hold null
var name: String = "Ada"
// Error: Null can not be a value of a non-null type String
// name = null

// Nullable: may hold null
var nickname: String? = "Addy"
nickname = null          // fine

// Direct access on a nullable type is rejected
// Error: Only safe (?.) or non-null asserted (!!.) calls are allowed
// println(nickname.length)

// A non-nullable type is not assignable from a nullable one
val maybe: String? = "hello"
// Error: Type mismatch
// val definite: String = maybe

// The reverse is always safe
val definite: String = "hello"
val widened: String? = definite   // fine

data class Address(val city: String?, val postcode: String?)
data class Customer(val name: String, val address: Address?)
data class Order(val id: Int, val customer: Customer?)

val order: Order? = loadOrder()

// Safe call: null if the receiver is null
val length: Int? = order?.customer?.name?.length

// The whole chain short-circuits on the first null —
// no nested if statements required
val city: String? = order?.customer?.address?.city

// Elvis: provide a default
val cityOrDefault: String = order?.customer?.address?.city ?: "Unknown"

// Elvis with an early return — a very common guard pattern
fun shipLabel(order: Order?): String {
    val customer = order?.customer ?: return "No customer"
    val city = customer.address?.city ?: return "No address"
    return "${customer.name}, $city"
}

// Elvis with throw for genuinely invalid state
fun requireCity(order: Order): String =
    order.customer?.address?.city
        ?: throw IllegalStateException("Order ${order.id} has no city")

// Safe call on a collection operation
val names: List<String> = order?.customer?.let { listOf(it.name) } ?: emptyList()

fun describe(value: String?) {
    if (value != null) {
        // Smart cast to String — direct access is allowed here
        println(value.length)
        println(value.uppercase())
    }
}

// Works with early return too
fun describeOrBail(value: String?) {
    if (value == null) return
    println(value.length)        // smart cast for the rest of the function
}

// Smart casts apply to type checks as well
fun area(shape: Any): Double = when (shape) {
    is Circle -> Math.PI * shape.radius * shape.radius  // smart cast
    is Rect   -> shape.width * shape.height
    else      -> 0.0
}

// A var property CANNOT be smart cast: another thread, or a custom
// getter, could change it between the check and the use.
class Holder {
    var value: String? = null

    fun broken() {
        if (value != null) {
            // Error: Smart cast to 'String' is impossible,
            // because 'value' is a mutable property
            // println(value.length)

            // Fix: copy into a local val
            val local = value
            if (local != null) println(local.length)
        }
    }
}

val email: String? = user.email

// let — run a block only if non-null; `it` is the non-null value
email?.let { addr ->
    sendWelcome(addr)        // addr: String, not String?
}

// Transform and fall back in one expression
val domain: String = email?.let { it.substringAfter('@') } ?: "unknown"

// also — side effect, returns the original value (good for logging)
val saved = user.also { log.info("saving ${it.id}") }.let(repo::save)

// run — like let but with `this` as the receiver
val summary = user.run { "$name <$email>" }

// takeIf — null unless the predicate holds; pairs well with Elvis
val validEmail = email?.takeIf { it.contains('@') } ?: return

// apply — configure and return the receiver
val request = Request().apply {
    url = "https://api.example.com"
    timeout = 30
}

val name: String? = null

// Throws NullPointerException — this is !! doing exactly what it says
// val length = name!!.length

// Almost always there is a better option:
val safe1 = name?.length ?: 0
val safe2 = name ?: error("name was required but missing")

// If you must assert, assert once and explain why
val config = loadConfig()
    ?: error("config must be initialised before first use")

class Service {
    // Promises: non-null, but assigned after construction
    private lateinit var client: HttpClient

    fun init() {
        client = HttpClient()
    }

    fun call() {
        // UninitializedPropertyAccessException if init() has not run
        client.get("/health")
    }

    fun callSafely() {
        if (::client.isInitialized) {
            client.get("/health")
        }
    }
}

// Often a lazy delegate is better: initialised on first access,
// thread-safe by default, and genuinely non-null.
class BetterService {
    private val client: HttpClient by lazy { HttpClient() }
}

// Java: public String getName() { return null; }

// Kotlin sees String! — a platform type, checks relaxed
val name = javaObject.name     // inferred as String!

// Compiles, then throws at runtime if Java returned null
// println(name.length)

// Fix: declare the nullability you actually expect
val safe: String? = javaObject.name
println(safe?.length ?: 0)

// On the Java side, annotate so Kotlin can see the intent:
//   @Nullable String getName()   -> String?
//   @NotNull  String getName()   -> String