Advanced KeyPaths¶
The usual KPaths API is small: create a KeyPath from a Kotlin property reference, or create a WritableKeyPath by also supplying its replacement behavior. This guide covers the custom-selector patterns Kotlin cannot express as a simple property reference. For the ordinary factory decision, start with KeyPaths; for sealed cases, see CaseKeyPaths.
Define a named derived KeyPath¶
Swift can place computed properties and custom subscripts inside a key-path expression. In Kotlin, create the equivalent KeyPath with a stable custom name. That name contributes to the KeyPath’s identity, so it describes one conceptual read—not merely a display label.
data class Person(val displayName: String)
val normalizedName: KeyPath<Person, String> =
keyPath("normalizedName") { person ->
person.displayName.trim().lowercase()
}
normalizedName(Person(" Blob ")) // "blob"
listOf(Person(" Blob ")).map(normalizedName) // ["blob"]
Two independently created KeyPaths with the same root type and name compare equal. Do not reuse a name for unrelated computations. Identity and type metadata explains why the name is semantic.
Define a named WritableKeyPath¶
A computed value becomes a WritableKeyPath only when the application can state how a replacement value produces a replacement root. This is Kotlin’s equivalent of supplying the getter and setter portions of a custom Swift subscript:
data class Person(val displayName: String)
val normalizedName: WritableKeyPath<Person, String> = writableKeyPath(
name = "normalizedName",
get = { person -> person.displayName.trim().lowercase() },
set = { person, value -> person.copy(displayName = value.trim()) },
)
val revised = normalizedName.set(Person(" Blob "), " BLOB JR. ")
// Person(displayName = "BLOB JR.")
It composes exactly like a generated WritableKeyPath:
data class Account(var owner: Person)
val owner: WritableKeyPath<Account, Person> = writableKeyPath(
get = Account::owner,
set = { account, value -> account.copy(owner = value) },
)
val accountOwnerName: WritableKeyPath<Account, String> = owner.then(normalizedName)
Create indexed KeyPaths¶
The indexed factories are Kotlin’s counterpart to a Swift key path such as \[Contact][1].email. They capture the index in a KeyPath rather than closing over a mutable variable:
data class Contact(val email: String)
val secondContact: KeyPath<List<Contact>, Contact> =
keyPath(get = List<Contact>::get, at = 1)
val secondEmail: KeyPath<List<Contact>, String> =
secondContact.then(keyPath(Contact::email))
secondEmail(listOf(Contact("first@example.com"), Contact("second@example.com")))
// "second@example.com"
For a MutableList, use referenceWritableKeyPath because Kotlin’s collection API changes the existing list instance:
val secondContact: ReferenceWritableKeyPath<MutableList<Contact>, Contact> =
referenceWritableKeyPath(
get = MutableList<Contact>::get,
set = MutableList<Contact>::set,
at = 1,
)
secondContact.set(mutableListOf(Contact("a"), Contact("b")), Contact("revised"))
ListPaths, ArrayPaths, MutableListPaths, and primitive-array catalogs provide the same standard KeyPaths with named accessors. See recipes for a smaller collection-focused example and the API reference for all standard catalogs.
Create keyed Map KeyPaths¶
The map factory is the equivalent of a keyed Swift subscript. Its WritableKeyPath focus is nullable because lookup may miss; assigning null removes the key:
val showTips: WritableKeyPath<Map<String, Boolean>, Boolean?> = writableKeyPath(
get = Map<String, Boolean>::get,
key = "showTips",
)
val enabled = showTips.set(emptyMap(), true)
// mapOf("showTips" to true)
val removed = showTips.set(enabled, null)
// emptyMap()
This is a copy-based WritableKeyPath for Map. Use referenceWritableKeyPath with MutableMap<String, Boolean>::get only when mutation of a shared mutable map is intentional.
Focus the whole value¶
identityKeyPath<Root>() is the equivalent of Swift’s \.self. It is a WritableKeyPath<Root, Root> whose replacement simply becomes the new root value:
val wholePerson: WritableKeyPath<Person, Person> = identityKeyPath()
val replacement = wholePerson.set(oldPerson, newPerson)
It is useful in generic code accepting WritableKeyPath<Root, Value> that sometimes needs to focus the complete root. For a design example, see Require write-back when an operation updates part of a value.