Package icyllis.modernui.lifecycle

# Class Transformations

java.lang.Object
icyllis.modernui.lifecycle.Transformations

public final class Transformations extends Object
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.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static <X> LiveData<X>`
  `distinctUntilChanged(LiveData<X> source)`
  Creates a new `LiveData` object that does not emit a value until the source LiveData value has been changed.
  `static <X, Y> LiveData<Y>`
  `map(LiveData<X> source, Function<? super X,? extends Y> mapFunction)`
  Returns a `LiveData` mapped from the input `source` `LiveData` by applying `mapFunction` to each value set on `source`.
  `static <X, Y> LiveData<Y>`
  `switchMap(LiveData<X> source, Function<? super X,? extends LiveData<? extends Y>> switchMapFunction)`
  Returns a `LiveData` mapped from the input `source` `LiveData` by applying `switchMapFunction` to each value set on `source`.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Method Details

  - ### map

    @UiThread @Nonnull public static <X, Y> LiveData<Y> map(@Nonnull LiveData<X> source, @Nonnull Function<? super X,? extends Y> mapFunction)
    Returns a `LiveData` mapped from the input `source` `LiveData` by applying `mapFunction` to each value set on `source`.

    This method is analogous to

    invalid reference

        io.reactivex.rxjava3.core.Observable#map

    .

    `transform` will be executed on the UI 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);

    Type Parameters:
      `X` - the generic type parameter of `source`
      `Y` - the generic type parameter of the returned `LiveData`
    Parameters:
      `source` - the `LiveData` to map from
      `mapFunction` - a function to apply to each value set on `source` in order to set it on the output `LiveData`
    Returns:
      a LiveData mapped from `source` to type `<Y>` by applying `mapFunction` to each value set.

  - ### switchMap

    @UiThread @Nonnull public static <X, Y> LiveData<Y> switchMap(@Nonnull LiveData<X> source, @Nonnull Function<? super X,? extends LiveData<? extends Y>> switchMapFunction)
    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

    invalid reference

        io.reactivex.rxjava3.core.Observable#switchMap

    .

    `switchMapFunction` will be executed on the UI 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 re-querying 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 ViewModel {
             MutableLiveData<String> nameQueryLiveData = ...

             LiveData<List<String>> getUsersWithNameLiveData() {
                 return Transformations.switchMap(
                     nameQueryLiveData, myDataSource::getUsersWithNameLiveData);
             }

             void setNameQuery(String name) {
                 this.nameQueryLiveData.setValue(name);
             }
         }

    Type Parameters:
      `X` - the generic type parameter of `source`
      `Y` - the generic type parameter of the returned `LiveData`
    Parameters:
      `source` - the `LiveData` to map from
      `switchMapFunction` - a function to apply to each value set on `source` to create a new delegate `LiveData` for the returned one
    Returns:
      a LiveData mapped from `source` to type `<Y>` by delegating to the LiveData returned by applying `switchMapFunction` to each value set

  - ### distinctUntilChanged

    @UiThread @Nonnull public static <X> LiveData<X> distinctUntilChanged(@Nonnull LiveData<X> source)
    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 `Object.equals(Object)` yields `false`.
    Type Parameters:
      `X` - the generic type parameter of `source`
    Parameters:
      `source` - the input `LiveData`
    Returns:
      a new `LiveData` of type `X`