Transformations
open class Transformations
kotlin.Any | |
↳ | androidx.lifecycle.Transformations |
Transformation methods for LiveData
.
These methods permit functional composition and delegation of LiveData
instances. The transformations are calculated lazily, and will run only when the returned LiveData
is observed. Lifecycle behavior is propagated from the input source
LiveData
to the returned one.
Summary
Public methods | |
---|---|
open static LiveData<X> |
distinctUntilChanged(@NonNull source: LiveData<X>) Creates a new |
open static LiveData<Y> |
Returns a |
open static LiveData<Y> |
Returns a |
Public methods
distinctUntilChanged
@MainThread @NonNull open static fun <X : Any!> distinctUntilChanged(@NonNull source: LiveData<X>): LiveData<X>
Creates a new LiveData
object that does not emit a value until the source LiveData value has been changed. The value is considered changed if equals()
yields false
.
Parameters | |
---|---|
source |
LiveData<X>: the input LiveData |
<X> |
the generic type parameter of source |
Return | |
---|---|
LiveData<X> |
a new LiveData of type X |
map
@MainThread @NonNull open static fun <X : Any!, Y : Any!> map(
@NonNull source: LiveData<X>,
@NonNull mapFunction: Function<X, Y>
): LiveData<Y>
Returns a LiveData
mapped from the input source
LiveData
by applying mapFunction
to each value set on source
.
This method is analogous to io.reactivex.Observable#map
.
transform
will be executed on the main thread.
Here is an example mapping a simple User
struct in a LiveData
to a LiveData
containing their full name as a String
.
LiveData<User> userLiveData = ...; LiveData<String> userFullNameLiveData = Transformations.map( userLiveData, user -> user.firstName + user.lastName); });
Parameters | |
---|---|
source |
LiveData<X>: the LiveData to map from |
mapFunction |
Function<X, Y>: a function to apply to each value set on source in order to set it on the output LiveData |
<X> |
the generic type parameter of source |
<Y> |
the generic type parameter of the returned LiveData |
Return | |
---|---|
LiveData<Y> |
a LiveData mapped from source to type <Y> by applying mapFunction to each value set. |
switchMap
@MainThread @NonNull open static fun <X : Any!, Y : Any!> switchMap(
@NonNull source: LiveData<X>,
@NonNull switchMapFunction: Function<X, LiveData<Y>!>
): LiveData<Y>
Returns a LiveData
mapped from the input source
LiveData
by applying switchMapFunction
to each value set on source
.
The returned LiveData
delegates to the most recent LiveData
created by calling switchMapFunction
with the most recent value set to source
, without changing the reference. In this way, switchMapFunction
can change the 'backing' LiveData
transparently to any observer registered to the LiveData
returned by switchMap()
.
Note that when the backing LiveData
is switched, no further values from the older LiveData
will be set to the output LiveData
. In this way, the method is analogous to io.reactivex.Observable#switchMap.
switchMapFunction
will be executed on the main thread.
Here is an example class that holds a typed-in name of a user String
(such as from an EditText
) in a MutableLiveData
and returns a LiveData
containing a List of User
objects for users that have that name. It populates that LiveData
by requerying a repository-pattern object each time the typed name changes.
This ViewModel
would permit the observing UI to update "live" as the user ID text changes.
class UserViewModel extends AndroidViewModel { MutableLiveData<String> nameQueryLiveData = ... LiveData<List<String>> getUsersWithNameLiveData() { return Transformations.switchMap( nameQueryLiveData, name -> myDataSource.getUsersWithNameLiveData(name)); } void setNameQuery(String name) { this.nameQueryLiveData.setValue(name); } }
Parameters | |
---|---|
source |
LiveData<X>: the LiveData to map from |
switchMapFunction |
Function<X, LiveData<Y>!>: a function to apply to each value set on source to create a new delegate LiveData for the returned one |
<X> |
the generic type parameter of source |
<Y> |
the generic type parameter of the returned LiveData |
Return | |
---|---|
LiveData<Y> |
a LiveData mapped from source to type <Y> by delegating to the LiveData returned by applying switchMapFunction to each value set |