update

abstract fun update(transform: Transformer<out @Nullable Provider<out Map<out K, out V>>, out Any>)(source)

Applies an eager transformation to the current value of the property "in place", without explicitly obtaining it. The provided transformer is applied to the provider of the current value, and the returned provider is used as a new value. The provider of the value can be used to derive the new value, but doesn't have to. Returning null from the transformer unsets the property. For example, the current value of a string map property can be filtered to retain only vowel keys:

    def property = objects.mapProperty(String, String).value(a: "a", b: "b")

    property.update { it.map { value -> value.subMap("a", "e", "i", "o", "u") } }

    println(property.get()) // [a: "a"]
Note that simply writing property.set(property.map { ... } doesn't work and will cause an exception because of a circular reference evaluation at runtime.

Further changes to the value of the property, such as calls to set, are not transformed, and override the update instead. Because of this, this method inherently depends on the order of property changes, and therefore must be used sparingly.

If the value of the property is specified via a provider, then the current value provider tracks that provider. For example, changes to the upstream property are visible:

    def upstream = objects.mapProperty(String, String).value(a: "a", b: "b")
    def property = objects.mapProperty(String, String).value(upstream)

    property.update { it.map { value -> value.subMap("a", "e", "i", "o", "u") } }
    upstream.value(e: "e", f: "f")

    println(property.get()) // [e: "e"]
The provided transformation runs eagerly, so it can capture any objects without introducing memory leaks and without breaking configuration caching. However, transformations applied to the current value provider (like map) are subject to the usual constraints.

If the property has no explicit value set, then the current value comes from the convention. Changes to convention of this property do not affect the current value provider in this case, though upstream changes are still visible if the convention was set to a provider. If there is no convention too, then the current value is a provider without a value. The updated value becomes the explicit value of the property.

Parameters

transform

the transformation to apply to the current value. May return null, which unsets the property.