Transformations

Kotlin |Java

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 `LiveData` object that does not emit a value until the source LiveData value has been changed.
open static LiveData<Y>	`map(@NonNull source: LiveData<X>, @NonNull mapFunction: Function<X, Y>)` Returns a `LiveData` mapped from the input `source` `LiveData` by applying `mapFunction` to each value set on `source`.
open static LiveData<Y>	`switchMap(@NonNull source: LiveData<X>, @NonNull switchMapFunction: Function<X, LiveData<Y>!>)` Returns a `LiveData` mapped from the input `source` `LiveData` by applying `switchMapFunction` to each value set on `source`.

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