"Functions Are Values" — Lambdas, References and Inline

// Fragment of story/RuleAudit.kt
class PriceRule(val name: String, val minPaise: Long, val percentOff: Int)

// Kabir's version: 'return' meant "skip this rule", as it would inside a Java lambda.
fun auditBroken(pricePaise: Long, rules: List<PriceRule>, log: MutableList<String>) {
    rules.forEach { rule ->
        if (pricePaise < rule.minPaise) return // returns from auditBroken, not from the lambda
        log += "${rule.name}: -${rule.percentOff}%"
    }
    log += "audited ${rules.size} rules"
}

// A function type is a real type: (Long) -> Long, not an interface you had to pick from java.util.function.
val festive: (Long) -> Long = { pricePaise -> pricePaise * 90 / 100 }

// A higher-order function takes (or returns) a function.
fun applyRule(pricePaise: Long, rule: (Long) -> Long): Long = rule(pricePaise)

// Returning a function: each call builds a new rule that remembers its 'percent'.
fun discountOf(percent: Int): (Long) -> Long = { it * (100 - percent) / 100 }

// Parameter names in a function type are documentation only.
fun describe(pricePaise: Long, format: (paise: Long, currency: String) -> String): String =
    format(pricePaise, "INR")

fun main() {
    println(festive(16_500)) // -> 14850
    println(applyRule(16_500, festive)) // -> 14850

    // Trailing lambda: the last function argument moves outside the parentheses.
    println(applyRule(16_500) { it - 1_000 }) // -> 15500

    // 'it' is the implicit name of a single parameter; name it when the lambda isn't tiny.
    println(applyRule(16_500) { price -> if (price > 10_000) price - 500 else price }) // -> 16000

    val clearance = discountOf(40)
    println(clearance(16_500)) // -> 9900

    // The last expression is the lambda's value. No 'return'.
    println(describe(16_550) { paise, currency -> "$currency ${paise / 100}.${paise % 100}" }) // -> INR 165.50

    // A nullable function type is called with ?.invoke()
    val optionalRule: ((Long) -> Long)? = null
    println(optionalRule?.invoke(16_500) ?: 16_500) // -> 16500
}

class Promotion(val name: String, val minPaise: Long)

fun main() {
    val rules = listOf(Promotion("BULK", 50_000), Promotion("FESTIVE", 10_000), Promotion("STAFF", 0))

    // Java would reject this: 'applicable' is not effectively final. Kotlin captures the variable itself.
    var applicable = 0
    rules.forEach { if (16_500 >= it.minPaise) applicable++ }
    println(applicable) // -> 2

    // The lambda sees the variable, not a snapshot of its value.
    var percent = 10
    val discount = { pricePaise: Long -> pricePaise * (100 - percent) / 100 }
    percent = 50
    println(discount(16_500)) // -> 8250
}

// javap -c com.shelfwise.part05.closures.ClosuresKt, main() (simplified)
// applicable++ inside the inline forEach: an ordinary local
 111: iload_1
 112: iconst_1
 113: iadd
 114: istore_1
// var percent, captured by a stored lambda: moved into a heap box
 129: new           kotlin/jvm/internal/Ref$IntRef
 140: putfield      kotlin/jvm/internal/Ref$IntRef.element:I         // percent = 10
 144: invokedynamic invoke:(Lkotlin/jvm/internal/Ref$IntRef;)Lkotlin/jvm/functions/Function1;
 153: putfield      kotlin/jvm/internal/Ref$IntRef.element:I         // percent = 50

private static final long main$lambda$1(kotlin.jvm.internal.Ref$IntRef, long);
   4: getfield      kotlin/jvm/internal/Ref$IntRef.element:I         // read at call time

data class Product(val sku: String, val name: String, val pricePaise: Long)

fun isPremium(product: Product): Boolean = product.pricePaise >= 50_000

class PriceBook(private val overrides: Map<String, Long>) {
    fun priceOf(sku: String): Long = overrides[sku] ?: 0
}

fun main() {
    val products = listOf(
        Product("SHW-1001", "Toor Dal 1kg", 16_500),
        Product("SHW-2040", "Basmati 5kg", 72_000),
    )

    // Top-level function reference: Java's Foo::isPremium without needing a class.
    println(products.filter(::isPremium).map { it.name }) // -> [Basmati 5kg]

    // Property reference: Product::name is a (Product) -> String.
    println(products.map(Product::name)) // -> [Toor Dal 1kg, Basmati 5kg]

    // Bound reference: the receiver is fixed when the reference is created.
    val festiveBook = PriceBook(mapOf("SHW-1001" to 14_900))
    val festivePrice: (String) -> Long = festiveBook::priceOf
    println(festivePrice("SHW-1001")) // -> 14900

    // Constructor reference: ::Product is a (String, String, Long) -> Product.
    val make: (String, String, Long) -> Product = ::Product
    println(make("SHW-3001", "Ghee 500ml", 34_000)) // -> Product(sku=SHW-3001, name=Ghee 500ml, pricePaise=34000)

    // Unbound member reference: the receiver becomes the first parameter.
    val length: (String) -> Int = String::length
    println(length("SHW-1001")) // -> 8
}

/** A Java functional interface, as found in any Java library. */
@FunctionalInterface
public interface PriceCheck {
    boolean accepts(long pricePaise);
}

import com.shelfwise.part05.javarules.PriceCheck
import java.util.concurrent.Callable
import java.util.concurrent.Executors

// A Kotlin interface needs 'fun' to accept a lambda. That marks it as a single abstract method type.
fun interface Discount {
    fun discounted(pricePaise: Long): Long
}

interface PlainDiscount {
    fun discounted(pricePaise: Long): Long
}

fun countAccepted(prices: List<Long>, check: PriceCheck): Int = prices.count { check.accepts(it) }

fun main() {
    // SAM conversion for a Java interface: a lambda where Java expects PriceCheck.
    println(countAccepted(listOf(500, 20_000, 90_000)) { it in 1_000..50_000 }) // -> 1

    // fun interface: a lambda converts to it too.
    val festive: Discount = Discount { it * 90 / 100 }
    val none: Discount = { it } // the explicit Discount { } is optional when the type is known
    println(festive.discounted(10_000) + none.discounted(1)) // -> 9001

    // A plain Kotlin interface doesn't take a lambda; you need an object expression.
    // val plain: PlainDiscount = { it }  // error: initializer type mismatch: expected 'PlainDiscount', actual '() -> ??? (Unknown lambda return type)'.
    val plain = object : PlainDiscount {
        override fun discounted(pricePaise: Long): Long = pricePaise
    }
    println(plain.discounted(42)) // -> 42

    // JDK overloads: Kotlin and Java pick different ones for the same-looking lambda.
    val pool = Executors.newSingleThreadExecutor()
    println(pool.submit { "reindexed" }.get()) // -> null
    println(pool.submit(Callable { "reindexed" }).get()) // -> reindexed
    pool.shutdown()
}

// Fragment of inlining/Inlining.kt
// Not inline: the lambda becomes a Function1 object, and the Long travels boxed through invoke(Object).
fun applyBoxed(pricePaise: Long, rule: (Long) -> Long): Long = rule(pricePaise)

// inline: the body and the lambda are copied into the caller. No object, no boxing.
inline fun applyInline(pricePaise: Long, rule: (Long) -> Long): Long = rule(pricePaise)

fun callBoxed(): Long = applyBoxed(16_500) { it - 600 }

fun callInline(): Long = applyInline(16_500) { it - 600 }

// javap -c -p com.shelfwise.part05.inlining.InliningKt (simplified)
private static final long callBoxed$lambda$0(long);          // the lambda body

public static final long callBoxed();
   0: ldc2_w        16500l
   3: invokedynamic invoke:()Lkotlin/jvm/functions/Function1;  // Function1 instance
   8: invokestatic  applyBoxed:(JLkotlin/jvm/functions/Function1;)J
  11: lreturn

public static final long applyBoxed(long, kotlin.jvm.functions.Function1<? super java.lang.Long, java.lang.Long>);
   6: aload_2
   7: lload_0
   8: invokestatic  java/lang/Long.valueOf:(J)Ljava/lang/Long;          // box the argument
  11: invokeinterface kotlin/jvm/functions/Function1.invoke:(Ljava/lang/Object;)Ljava/lang/Object;
  16: checkcast     java/lang/Number
  19: invokevirtual java/lang/Number.longValue:()J                       // unbox the result
  22: lreturn

public static final long callInline();
   0: ldc2_w        16500l
   ...
  11: lload_3
  12: sipush        600
  15: i2l
  16: lsub
  17: nop
  18: lreturn

// Fragment of inlining/Inlining.kt
// The typical inline helper: behaviour around a block, with no allocation per call.
inline fun <T> audited(log: MutableList<String>, label: String, block: () -> T): T {
    log += "start $label"
    val result = block()
    log += "end $label = $result"
    return result
}

// noinline: 'describe' is stored for later, so it must stay a real object.
inline fun register(registry: MutableList<() -> String>, enabled: () -> Boolean, noinline describe: () -> String) {
    if (enabled()) registry += describe
}
// Without noinline:
// inline fun registerAll(registry: MutableList<() -> String>, describe: () -> String) { registry += describe }
//   error: illegal usage of inline parameter 'describe: () -> String'. Add 'noinline' modifier to the parameter declaration.

// crossinline: 'action' runs inside another object, so it must not 'return' from the caller.
inline fun deferred(crossinline action: () -> Unit): Runnable = Runnable { action() }
// Without crossinline:
// inline fun deferredAll(action: () -> Unit): Runnable = Runnable { action() }
//   error: cannot inline 'action: () -> Unit' here: it might contain non-local returns. Add 'crossinline' modifier to parameter declaration 'action: () -> Unit'.

// forEach is inline, so this 'return' leaves firstPremium, not just the lambda.
fun firstPremium(prices: List<Long>): Long? {
    prices.forEach { if (it >= 50_000) return it }
    return null
}

// An anonymous function: 'return' leaves the anonymous function itself, like a Java lambda.
fun countAffordable(prices: List<Long>, budgetPaise: Long): Int {
    var count = 0
    prices.forEach(fun(price) {
        if (price > budgetPaise) return
        count++
    })
    return count
}

// Not inline: the lambda may be stored and called later, so a bare 'return' has no caller to leave.
fun eachLater(prices: List<Long>, action: (Long) -> Unit) {
    for (price in prices) action(price)
}

fun printNonZero(prices: List<Long>) {
    eachLater(prices) { if (it == 0L) return@eachLater else println("price $it") }
    // eachLater(prices) { if (it == 0L) return }  // error: 'return' is prohibited here.
    // Sequence operations are not inline either, because they run later:
    // prices.asSequence().map { if (it == 0L) return else it }.toList()  // error: 'return' is prohibited here.
}

// Non-local break and continue (Stable since 2.2.0) work inside inline lambdas too.
fun firstStockedShelf(shelves: List<List<Int>>): Int {
    var found = -1
    for ((index, shelf) in shelves.withIndex()) {
        shelf.forEach { units ->
            if (units < 0) continue // a faulty sensor: skip the rest of this shelf
            if (units > 0) {
                found = index
                break // stop scanning shelves altogether
            }
        }
    }
    return found
}

fun main() {
    println(firstPremium(listOf(16_500, 72_000, 99_000))) // -> 72000
    println(countAffordable(listOf(16_500, 72_000, 9_900), budgetPaise = 20_000)) // -> 2
    printNonZero(listOf(0, 16_500))
    // -> price 16500
    println(firstStockedShelf(listOf(listOf(0, 0), listOf(-1, 5), listOf(0, 3)))) // -> 2
}

class Category(val name: String, val parent: Category? = null)

// The recursive call is the last thing the function does, so the compiler turns it into a loop.
tailrec fun root(category: Category): Category {
    val parent = category.parent ?: return category
    return root(parent)
}

// An accumulator moves the work before the call, which is what makes it a tail call.
tailrec fun path(category: Category?, acc: String = ""): String =
    if (category == null) acc
    else path(category.parent, if (acc.isEmpty()) category.name else "${category.name} > $acc")

// Not a tail call: the '1 +' runs after the recursive call returns. The compiler warns and keeps the recursion.
// tailrec fun depth(category: Category): Int = if (category.parent == null) 0 else 1 + depth(category.parent)
//   warning: a function is marked as tail-recursive but no tail calls are found.

fun main() {
    val dal = Category("Dal", Category("Staples", Category("Grocery")))
    println(root(dal).name) // -> Grocery
    println(path(dal)) // -> Grocery > Staples > Dal

    // 100,000 levels deep: plain recursion would need 100,000 stack frames.
    var deep = Category("level-0")
    for (i in 1..100_000) deep = Category("level-$i", deep)
    println(root(deep).name) // -> level-0
}

public static final Category root(Category);
   6: aload_0
   7: invokevirtual Category.getParent:()LCategory;
  10: dup
  11: ifnonnull     17
  14: pop
  15: aload_0
  16: areturn
  17: astore_1
  18: aload_1
  19: astore_0                // category = parent
  20: goto          6         // and go round again: no recursive call

class LabelBuilder {
    private val lines = mutableListOf<String>()

    fun line(text: String) {
        lines += text
    }

    fun build(): String = lines.joinToString(" | ")
}

// LabelBuilder.() -> Unit: a lambda with a receiver. Inside it, 'this' is the builder.
fun label(content: LabelBuilder.() -> Unit): String {
    val builder = LabelBuilder()
    builder.content() // call the lambda as if it were a member of 'builder'
    return builder.build()
}

fun main() {
    println(label {
        line("Toor Dal 1kg")
        line("₹159.00")
    }) // -> Toor Dal 1kg | ₹159.00

    // The standard library uses the same trick: buildString's lambda has a StringBuilder receiver.
    println(buildString {
        append("SHW-")
        append(1001)
    }) // -> SHW-1001
}

// Fragment of rules/PricingRules.kt
data class Line(val sku: String, val category: String, val pricePaise: Long, val quantity: Int)

// Step 1: a rule is a fun interface, so a lambda, a function reference or an object can be one.
fun interface PriceRule {
    fun price(line: Line): Long // the new unit price
}

// Fragment of rules/PricingRules.kt
// Step 2: rule factories. Each returns a lambda that captures its configuration.
fun percentOff(percent: Int, appliesTo: (Line) -> Boolean = { true }): PriceRule =
    PriceRule { line -> if (appliesTo(line)) line.pricePaise * (100 - percent) / 100 else line.pricePaise }

fun buyMorePayLess(minQuantity: Int, percent: Int): PriceRule =
    percentOff(percent) { it.quantity >= minQuantity }

// Fragment of rules/PricingRules.kt
// Step 3: an ordinary function that will become a rule through a reference.
fun roundToRupee(line: Line): Long = line.pricePaise / 100 * 100

// Fragment of rules/PricingRules.kt
// Step 4: composition. A higher-order function that takes rules and returns a rule.
fun chain(rules: List<PriceRule>): PriceRule = PriceRule { line ->
    var price = line.pricePaise
    for (rule in rules) price = rule.price(line.copy(pricePaise = price))
    price
}

// Fragment of rules/PricingRules.kt
// Step 5: an inline helper that reports each amount to an audit callback; the block never becomes an object.
inline fun auditing(audit: (String) -> Unit, sku: String, block: () -> Long): Long {
    val amount = block()
    audit("$sku -> $amount")
    return amount
}

fun priceBasket(lines: List<Line>, rule: PriceRule, audit: (String) -> Unit): Long {
    var total = 0L
    for (line in lines) {
        if (line.quantity == 0) continue // nothing to price, nothing to audit
        total += auditing(audit, line.sku) { rule.price(line) * line.quantity }
    }
    return total
}

// Fragment of rules/PricingRules.kt
fun main() {
    val festiveGrocery = chain(
        listOf(
            percentOff(10) { it.category == "staples" },
            buyMorePayLess(minQuantity = 3, percent = 5),
            PriceRule(::roundToRupee),
        ),
    )
    val basket = listOf(
        Line("SHW-1001", "staples", 16_550, 3),
        Line("SHW-1002", "snacks", 3_050, 1),
        Line("SHW-1003", "staples", 9_990, 0),
    )

    val log = mutableListOf<String>()
    println(priceBasket(basket, festiveGrocery, log::add)) // -> 45300
    log.forEach(::println)
    // -> SHW-1001 -> 42300
    // -> SHW-1002 -> 3000
}

// The Java pricing team's side: Java lambdas against the Kotlin API.
public final class LegacyRules {
    // A Kotlin fun interface: an ordinary functional interface to javac.
    public static final PriceRule STAFF_PRICE = line -> line.getPricePaise() * 80 / 100;

    public static void main(String[] args) {
        List<Line> lines = List.of(new Line("SHW-1001", "staples", 16_550, 1));
        // A Kotlin (String) -> Unit is a Function1<String, Unit>: the lambda must return Unit.INSTANCE.
        long total = PricingRulesKt.priceBasket(lines, STAFF_PRICE, message -> {
            System.out.println("audit " + message);
            return Unit.INSTANCE;
        });
        System.out.println(total);
        // -> audit SHW-1001 -> 13240
        // -> 13240
    }
}