# Transformations

Added in 2.0.0

*** ** * ** ***

<br />

```
public final class Transformations
```

<br />

*** ** * ** ***

## Summary

| ### Public methods |
|---|---|
| `static final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/lifecycle/LiveData<@https://developer.android.com/reference/androidx/annotation/NonNull X>` | `@https://developer.android.com/reference/androidx/annotation/MainThread <X extends https://developer.android.com/reference/java/lang/Object.html> https://developer.android.com/reference/androidx/lifecycle/Transformations#(androidx.lifecycle.LiveData).distinctUntilChanged()(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/lifecycle/LiveData<@https://developer.android.com/reference/androidx/annotation/NonNull X> receiver)` Creates a new `https://developer.android.com/reference/androidx/lifecycle/LiveData` object does not emit a value until the source `this` LiveData value has been changed. |
| `static final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/lifecycle/LiveData<@https://developer.android.com/reference/androidx/annotation/NonNull Y>` | `@https://developer.android.com/reference/androidx/annotation/MainThread <X extends https://developer.android.com/reference/java/lang/Object.html, Y extends https://developer.android.com/reference/java/lang/Object.html> https://developer.android.com/reference/androidx/lifecycle/Transformations#(androidx.lifecycle.LiveData).map(kotlin.Function1)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/lifecycle/LiveData<@https://developer.android.com/reference/androidx/annotation/NonNull X> receiver, @https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull X, @https://developer.android.com/reference/androidx/annotation/NonNull Y> transform )` Returns a `https://developer.android.com/reference/androidx/lifecycle/LiveData` mapped from `this` LiveData by applying `https://developer.android.com/reference/androidx/lifecycle/package-summary#(androidx.lifecycle.LiveData).map(kotlin.Function1)` to each value set on `this` LiveData. |
| `static final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/lifecycle/LiveData<@https://developer.android.com/reference/androidx/annotation/NonNull Y>` | `@https://developer.android.com/reference/androidx/annotation/MainThread <X extends https://developer.android.com/reference/java/lang/Object.html, Y extends https://developer.android.com/reference/java/lang/Object.html> https://developer.android.com/reference/androidx/lifecycle/Transformations#(androidx.lifecycle.LiveData).switchMap(kotlin.Function1)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/lifecycle/LiveData<@https://developer.android.com/reference/androidx/annotation/NonNull X> receiver, @https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull X, https://developer.android.com/reference/androidx/lifecycle/LiveData<@https://developer.android.com/reference/androidx/annotation/NonNull Y>> transform )` Returns a `https://developer.android.com/reference/androidx/lifecycle/LiveData` mapped from the input `this` `LiveData` by applying `https://developer.android.com/reference/androidx/lifecycle/package-summary#(androidx.lifecycle.LiveData).switchMap(kotlin.Function1)` to each value set on `this`. |

## Public methods

### distinctUntilChanged

Artifact: [androidx.lifecycle:lifecycle-livedata](https://developer.android.com/jetpack/androidx/releases/lifecycle) [View Source](https://cs.android.com/search?q=file:androidx/lifecycle/Transformations.kt+function:distinctUntilChanged) Added in [2.1.0](https://developer.android.com/jetpack/androidx/releases/lifecycle#2.1.0)

```
@MainThread
public static final @NonNull LiveData<@NonNull X> <X extends Object> distinctUntilChanged(@NonNull LiveData<@NonNull X> receiver)
```

Creates a new `https://developer.android.com/reference/androidx/lifecycle/LiveData` object does not emit a value until the source `this` LiveData value has been changed. The value is considered changed if `equals()` yields `false`.

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/lifecycle/LiveData<@https://developer.android.com/reference/androidx/annotation/NonNull X>` | a new `https://developer.android.com/reference/androidx/lifecycle/LiveData` of type `X` |

### map

Artifact: [androidx.lifecycle:lifecycle-livedata](https://developer.android.com/jetpack/androidx/releases/lifecycle) [View Source](https://cs.android.com/search?q=file:androidx/lifecycle/Transformations.kt+function:map)

```
@MainThread
public static final @NonNull LiveData<@NonNull Y> <X extends Object, Y extends Object> map(
    @NonNull LiveData<@NonNull X> receiver,
    @NonNull Function1<@NonNull X, @NonNull Y> transform
)
```

Returns a `https://developer.android.com/reference/androidx/lifecycle/LiveData` mapped from `this` LiveData by applying `https://developer.android.com/reference/androidx/lifecycle/package-summary#(androidx.lifecycle.LiveData).map(kotlin.Function1)` to each value set on `this` LiveData.

This method is analogous to `https://reactivex.io/RxJava/2.x/javadoc/io/reactivex/Observable.html#map-io.reactivex.functions.Function&lt;? super T,? extends R&gt;-`.

`https://developer.android.com/reference/androidx/lifecycle/package-summary#(androidx.lifecycle.LiveData).map(kotlin.Function1)` 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`.

```
val userLD : LiveData<User> = ...;
val userFullNameLD: LiveData<String> = userLD.map { user -> user.firstName + user.lastName }
```

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull X, @https://developer.android.com/reference/androidx/annotation/NonNull Y> transform` | a function to apply to each value set on `source` in order to set it on the output `LiveData` |

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/lifecycle/LiveData<@https://developer.android.com/reference/androidx/annotation/NonNull Y>` | a LiveData mapped from `source` to type `<Y>` by applying `mapFunction` to each value set. |

### switchMap

Artifact: [androidx.lifecycle:lifecycle-livedata](https://developer.android.com/jetpack/androidx/releases/lifecycle) [View Source](https://cs.android.com/search?q=file:androidx/lifecycle/Transformations.kt+function:switchMap)

```
@MainThread
public static final @NonNull LiveData<@NonNull Y> <X extends Object, Y extends Object> switchMap(
    @NonNull LiveData<@NonNull X> receiver,
    @NonNull Function1<@NonNull X, LiveData<@NonNull Y>> transform
)
```

Returns a `https://developer.android.com/reference/androidx/lifecycle/LiveData` mapped from the input `this` `LiveData` by applying `https://developer.android.com/reference/androidx/lifecycle/package-summary#(androidx.lifecycle.LiveData).switchMap(kotlin.Function1)` to each value set on `this`.

The returned \`LiveData\` delegates to the most recent \`LiveData\` created by \[transform\] with the most recent value set to \`this\`, without changing the reference. In this way \[transform\] 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 `https://reactivex.io/RxJava/2.x/javadoc/io/reactivex/Observable.html#switchMap-io.reactivex.functions.Function&lt;? super T,? extends io.reactivex.ObservableSource&lt;? extends R&gt;&gt;-`.

`https://developer.android.com/reference/androidx/lifecycle/package-summary#(androidx.lifecycle.LiveData).switchMap(kotlin.Function1)` 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 `https://developer.android.com/reference/androidx/lifecycle/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: AndroidViewModel {
    val nameQueryLiveData : MutableLiveData<String> = ...

    fun usersWithNameLiveData(): LiveData<List<String>> = nameQueryLiveData.switchMap {
        name -> myDataSource.usersWithNameLiveData(name)
    }

    fun setNameQuery(val name: String) {
        this.nameQueryLiveData.value = name;
    }
}
```

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull X, https://developer.android.com/reference/androidx/lifecycle/LiveData<@https://developer.android.com/reference/androidx/annotation/NonNull Y>> transform` | a function to apply to each value set on `source` to create a new delegate `LiveData` for the returned one |

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/lifecycle/LiveData<@https://developer.android.com/reference/androidx/annotation/NonNull Y>` | a LiveData mapped from `source` to type `<Y>` by delegating to the LiveData returned by applying `switchMapFunction` to each value set |