| <html devsite="true"> |
| <head> |
| <title>Transformations</title> |
| {% setvar book_path %}/reference/kotlin/androidx/_book.yaml{% endsetvar %} |
| {% include "_shared/_reference-head-tags.html" %} |
| </head> |
| <body> |
| <div id="metadata-info-block"></div> |
| <h1>Transformations</h1> |
| <p> |
| <pre>class <a href="/reference/kotlin/androidx/lifecycle/Transformations.html">Transformations</a></pre> |
| </p> |
| <hr> |
| <p>Transformation methods for <code><a href="/reference/kotlin/androidx/lifecycle/LiveData.html">LiveData</a></code>. </p> |
| <p> These methods permit functional composition and delegation of <code><a href="/reference/kotlin/androidx/lifecycle/LiveData.html">LiveData</a></code> instances. The transformations are calculated lazily, and will run only when the returned <code><a href="/reference/kotlin/androidx/lifecycle/LiveData.html">LiveData</a></code> is observed. Lifecycle behavior is propagated from the input <code>source</code><code><a href="/reference/kotlin/androidx/lifecycle/LiveData.html">LiveData</a></code> to the returned one.</p> |
| <h2>Summary</h2> |
| <div class="devsite-table-wrapper"> |
| <table class="responsive"> |
| <thead> |
| <tr> |
| <th colspan="100%"><h3>Public constructors</h3></th> |
| </tr> |
| </thead> |
| <tbody class="list"> |
| <tr> |
| <td> |
| <div><code><a href="/reference/kotlin/androidx/lifecycle/Transformations.html#Transformations()">Transformations</a>()</code></div> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| <div class="devsite-table-wrapper"> |
| <table class="responsive"> |
| <thead> |
| <tr> |
| <th colspan="100%"><h3>Public functions</h3></th> |
| </tr> |
| </thead> |
| <tbody class="list"> |
| <tr> |
| <td width="40%"><code>java-static <a href="/reference/kotlin/androidx/lifecycle/LiveData.html">LiveData</a><X!></code></td> |
| <td> |
| <div><code>@<a href="/reference/kotlin/androidx/annotation/MainThread.html">MainThread</a><br><X> <a href="/reference/kotlin/androidx/lifecycle/Transformations.html#distinctUntilChanged(androidx.lifecycle.LiveData<X>)">distinctUntilChanged</a>(source: <a href="/reference/kotlin/androidx/lifecycle/LiveData.html">LiveData</a><X!>)</code></div> |
| <p>Creates a new <code><a href="/reference/kotlin/androidx/lifecycle/LiveData.html">LiveData</a></code> object that does not emit a value until the source LiveData value has been changed.</p> |
| </td> |
| </tr> |
| <tr> |
| <td width="40%"><code>java-static <a href="/reference/kotlin/androidx/lifecycle/LiveData.html">LiveData</a><Y!></code></td> |
| <td> |
| <div><code>@<a href="/reference/kotlin/androidx/annotation/MainThread.html">MainThread</a><br><X, Y> <a href="/reference/kotlin/androidx/lifecycle/Transformations.html#map(androidx.lifecycle.LiveData<X>,androidx.arch.core.util.Function<X,Y>)">map</a>(source: <a href="/reference/kotlin/androidx/lifecycle/LiveData.html">LiveData</a><X!>, mapFunction: <a href="/reference/kotlin/androidx/arch/core/util/Function.html">Function</a><X!, Y!>)</code></div> |
| <p>Returns a <code>LiveData</code> mapped from the input <code>source</code><code>LiveData</code> by applying <code>mapFunction</code> to each value set on <code>source</code>.</p> |
| </td> |
| </tr> |
| <tr> |
| <td width="40%"><code>java-static <a href="/reference/kotlin/androidx/lifecycle/LiveData.html">LiveData</a><Y!></code></td> |
| <td> |
| <div><code>@<a href="/reference/kotlin/androidx/annotation/MainThread.html">MainThread</a><br><X, Y> <a href="/reference/kotlin/androidx/lifecycle/Transformations.html#switchMap(androidx.lifecycle.LiveData<X>,androidx.arch.core.util.Function<X,androidx.lifecycle.LiveData<Y>>)">switchMap</a>(<br> source: <a href="/reference/kotlin/androidx/lifecycle/LiveData.html">LiveData</a><X!>,<br> switchMapFunction: <a href="/reference/kotlin/androidx/arch/core/util/Function.html">Function</a><X!, <a href="/reference/kotlin/androidx/lifecycle/LiveData.html">LiveData</a><Y!>!><br>)</code></div> |
| <p>Returns a <code>LiveData</code> mapped from the input <code>source</code><code>LiveData</code> by applying <code>switchMapFunction</code> to each value set on <code>source</code>.</p> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| <h2>Public constructors</h2> |
| <div><a name="Transformations--"></a><a name="transformations"></a> |
| <h3 class="api-name" id="Transformations()">Transformations</h3> |
| <pre class="api-signature no-pretty-print"><a href="/reference/kotlin/androidx/lifecycle/Transformations.html#Transformations()">Transformations</a>()</pre> |
| </div> |
| <h2>Public functions</h2> |
| <div><a name="distinctUntilChanged-androidx.lifecycle.LiveData<X>-"></a><a name="distinctuntilchanged"></a> |
| <h3 class="api-name" id="distinctUntilChanged(androidx.lifecycle.LiveData<X>)">distinctUntilChanged</h3> |
| <pre class="api-signature no-pretty-print">@<a href="/reference/kotlin/androidx/annotation/MainThread.html">MainThread</a><br>java-static fun <X> <a href="/reference/kotlin/androidx/lifecycle/Transformations.html#distinctUntilChanged(androidx.lifecycle.LiveData<X>)">distinctUntilChanged</a>(source: <a href="/reference/kotlin/androidx/lifecycle/LiveData.html">LiveData</a><X!>): <a href="/reference/kotlin/androidx/lifecycle/LiveData.html">LiveData</a><X!></pre> |
| <p>Creates a new <code><a href="/reference/kotlin/androidx/lifecycle/LiveData.html">LiveData</a></code> object that does not emit a value until the source LiveData value has been changed. The value is considered changed if <code>equals()</code> yields <code>false</code>.</p> |
| <div class="devsite-table-wrapper"> |
| <table class="responsive"> |
| <thead> |
| <tr> |
| <th colspan="100%">Parameters</th> |
| </tr> |
| </thead> |
| <tbody class="list"> |
| <tr> |
| <td width="40%"><code><X></code></td> |
| <td> |
| <p>the generic type parameter of <code>source</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td width="40%"><code>source: <a href="/reference/kotlin/androidx/lifecycle/LiveData.html">LiveData</a><X!></code></td> |
| <td> |
| <p>the input <code><a href="/reference/kotlin/androidx/lifecycle/LiveData.html">LiveData</a></code></p> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| <div class="devsite-table-wrapper"> |
| <table class="responsive"> |
| <thead> |
| <tr> |
| <th colspan="100%">Returns</th> |
| </tr> |
| </thead> |
| <tbody class="list"> |
| <tr> |
| <td width="40%"><code><a href="/reference/kotlin/androidx/lifecycle/LiveData.html">LiveData</a><X!></code></td> |
| <td> |
| <p>a new <code><a href="/reference/kotlin/androidx/lifecycle/LiveData.html">LiveData</a></code> of type <code>X</code></p> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| </div> |
| <div><a name="map(androidx.lifecycle.LiveData<X>, androidx.arch.core.util.Function<X,Y>)"></a><a name="map-androidx.lifecycle.LiveData<X>-androidx.arch.core.util.Function<X,Y>-"></a><a name="map"></a> |
| <h3 class="api-name" id="map(androidx.lifecycle.LiveData<X>,androidx.arch.core.util.Function<X,Y>)">map</h3> |
| <pre class="api-signature no-pretty-print">@<a href="/reference/kotlin/androidx/annotation/MainThread.html">MainThread</a><br>java-static fun <X, Y> <a href="/reference/kotlin/androidx/lifecycle/Transformations.html#map(androidx.lifecycle.LiveData<X>,androidx.arch.core.util.Function<X,Y>)">map</a>(source: <a href="/reference/kotlin/androidx/lifecycle/LiveData.html">LiveData</a><X!>, mapFunction: <a href="/reference/kotlin/androidx/arch/core/util/Function.html">Function</a><X!, Y!>): <a href="/reference/kotlin/androidx/lifecycle/LiveData.html">LiveData</a><Y!></pre> |
| <p>Returns a <code>LiveData</code> mapped from the input <code>source</code><code>LiveData</code> by applying <code>mapFunction</code> to each value set on <code>source</code>. </p> |
| <p> This method is analogous to <code><a href="/reference/kotlin/io/reactivex/Observable.html#map(io.reactivex.functions.Function<? super T,? extends R>)">map</a></code>. </p> |
| <p><code>transform</code> will be executed on the main thread. </p> |
| <p> Here is an example mapping a simple <code>User</code> struct in a <code>LiveData</code> to a <code>LiveData</code> containing their full name as a <code>String</code>. </p> |
| <pre class="prettyprint">LiveData<User> userLiveData = ...; |
| LiveData<String> userFullNameLiveData = |
| Transformations.map( |
| userLiveData, |
| user -> user.firstName + user.lastName); |
| }); |
| </pre> |
| <div class="devsite-table-wrapper"> |
| <table class="responsive"> |
| <thead> |
| <tr> |
| <th colspan="100%">Parameters</th> |
| </tr> |
| </thead> |
| <tbody class="list"> |
| <tr> |
| <td width="40%"><code><X></code></td> |
| <td> |
| <p>the generic type parameter of <code>source</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td width="40%"><code><Y></code></td> |
| <td> |
| <p>the generic type parameter of the returned <code>LiveData</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td width="40%"><code>source: <a href="/reference/kotlin/androidx/lifecycle/LiveData.html">LiveData</a><X!></code></td> |
| <td> |
| <p>the <code>LiveData</code> to map from</p> |
| </td> |
| </tr> |
| <tr> |
| <td width="40%"><code>mapFunction: <a href="/reference/kotlin/androidx/arch/core/util/Function.html">Function</a><X!, Y!></code></td> |
| <td> |
| <p>a function to apply to each value set on <code>source</code> in order to set it on the output <code>LiveData</code></p> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| <div class="devsite-table-wrapper"> |
| <table class="responsive"> |
| <thead> |
| <tr> |
| <th colspan="100%">Returns</th> |
| </tr> |
| </thead> |
| <tbody class="list"> |
| <tr> |
| <td width="40%"><code><a href="/reference/kotlin/androidx/lifecycle/LiveData.html">LiveData</a><Y!></code></td> |
| <td> |
| <p>a LiveData mapped from <code>source</code> to type <code><Y></code> by applying <code>mapFunction</code> to each value set.</p> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| </div> |
| <div><a name="switchMap(androidx.lifecycle.LiveData<X>, androidx.arch.core.util.Function<X,androidx.lifecycle.LiveData<Y>>)"></a><a name="switchMap-androidx.lifecycle.LiveData<X>-androidx.arch.core.util.Function<X,androidx.lifecycle.LiveData<Y>>-"></a><a name="switchmap"></a> |
| <h3 class="api-name" id="switchMap(androidx.lifecycle.LiveData<X>,androidx.arch.core.util.Function<X,androidx.lifecycle.LiveData<Y>>)">switchMap</h3> |
| <pre class="api-signature no-pretty-print">@<a href="/reference/kotlin/androidx/annotation/MainThread.html">MainThread</a><br>java-static fun <X, Y> <a href="/reference/kotlin/androidx/lifecycle/Transformations.html#switchMap(androidx.lifecycle.LiveData<X>,androidx.arch.core.util.Function<X,androidx.lifecycle.LiveData<Y>>)">switchMap</a>(<br> source: <a href="/reference/kotlin/androidx/lifecycle/LiveData.html">LiveData</a><X!>,<br> switchMapFunction: <a href="/reference/kotlin/androidx/arch/core/util/Function.html">Function</a><X!, <a href="/reference/kotlin/androidx/lifecycle/LiveData.html">LiveData</a><Y!>!><br>): <a href="/reference/kotlin/androidx/lifecycle/LiveData.html">LiveData</a><Y!></pre> |
| <p>Returns a <code>LiveData</code> mapped from the input <code>source</code><code>LiveData</code> by applying <code>switchMapFunction</code> to each value set on <code>source</code>. </p> |
| <p> The returned <code>LiveData</code> delegates to the most recent <code>LiveData</code> created by calling <code>switchMapFunction</code> with the most recent value set to <code>source</code>, without changing the reference. In this way, <code>switchMapFunction</code> can change the 'backing' <code>LiveData</code> transparently to any observer registered to the <code>LiveData</code> returned by <code>switchMap()</code>. </p> |
| <p> Note that when the backing <code>LiveData</code> is switched, no further values from the older <code>LiveData</code> will be set to the output <code>LiveData</code>. In this way, the method is analogous to switchMap. </p> |
| <p><code>switchMapFunction</code> will be executed on the main thread. </p> |
| <p> Here is an example class that holds a typed-in name of a user <code>String</code> (such as from an <code>EditText</code>) in a <code><a href="/reference/kotlin/androidx/lifecycle/MutableLiveData.html">MutableLiveData</a></code> and returns a <code>LiveData</code> containing a List of <code>User</code> objects for users that have that name. It populates that <code>LiveData</code> by requerying a repository-pattern object each time the typed name changes. </p> |
| <p> This <code>ViewModel</code> would permit the observing UI to update "live" as the user ID text changes. </p> |
| <pre class="prettyprint">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); |
| } |
| } |
| </pre> |
| <div class="devsite-table-wrapper"> |
| <table class="responsive"> |
| <thead> |
| <tr> |
| <th colspan="100%">Parameters</th> |
| </tr> |
| </thead> |
| <tbody class="list"> |
| <tr> |
| <td width="40%"><code><X></code></td> |
| <td> |
| <p>the generic type parameter of <code>source</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td width="40%"><code><Y></code></td> |
| <td> |
| <p>the generic type parameter of the returned <code>LiveData</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td width="40%"><code>source: <a href="/reference/kotlin/androidx/lifecycle/LiveData.html">LiveData</a><X!></code></td> |
| <td> |
| <p>the <code>LiveData</code> to map from</p> |
| </td> |
| </tr> |
| <tr> |
| <td width="40%"><code>switchMapFunction: <a href="/reference/kotlin/androidx/arch/core/util/Function.html">Function</a><X!, <a href="/reference/kotlin/androidx/lifecycle/LiveData.html">LiveData</a><Y!>!></code></td> |
| <td> |
| <p>a function to apply to each value set on <code>source</code> to create a new delegate <code>LiveData</code> for the returned one</p> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| <div class="devsite-table-wrapper"> |
| <table class="responsive"> |
| <thead> |
| <tr> |
| <th colspan="100%">Returns</th> |
| </tr> |
| </thead> |
| <tbody class="list"> |
| <tr> |
| <td width="40%"><code><a href="/reference/kotlin/androidx/lifecycle/LiveData.html">LiveData</a><Y!></code></td> |
| <td> |
| <p>a LiveData mapped from <code>source</code> to type <code><Y></code> by delegating to the LiveData returned by applying <code>switchMapFunction</code> to each value set</p> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| </div> |
| </body> |
| </html> |