# PagingDataTransforms

Added in 3.0.0

*** ** * ** ***


```
public final class PagingDataTransforms
```

<br />

*** ** * ** ***

## Summary

| ### Public methods |
|---|---|
| `static final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/paging/PagingData<@https://developer.android.com/reference/androidx/annotation/NonNull T>` | `<T extends https://developer.android.com/reference/java/lang/Object.html> https://developer.android.com/reference/androidx/paging/PagingDataTransforms#(androidx.paging.PagingData).filter(java.util.concurrent.Executor,kotlin.Function1)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/paging/PagingData<@https://developer.android.com/reference/androidx/annotation/NonNull T> receiver, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/concurrent/Executor.html executor, @https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull T, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/Boolean.html> predicate )` Returns a `https://developer.android.com/reference/androidx/paging/PagingData` containing only elements matching the given `https://developer.android.com/reference/androidx/paging/package-summary#(androidx.paging.PagingData).filter(java.util.concurrent.Executor,kotlin.Function1)`. |
| `static final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/paging/PagingData<@https://developer.android.com/reference/androidx/annotation/NonNull R>` | `<T extends https://developer.android.com/reference/java/lang/Object.html, R extends https://developer.android.com/reference/java/lang/Object.html> https://developer.android.com/reference/androidx/paging/PagingDataTransforms#(androidx.paging.PagingData).flatMap(java.util.concurrent.Executor,kotlin.Function1)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/paging/PagingData<@https://developer.android.com/reference/androidx/annotation/NonNull T> receiver, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/concurrent/Executor.html executor, @https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull T, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/Iterable.html<@https://developer.android.com/reference/androidx/annotation/NonNull R>> transform )` Returns a `https://developer.android.com/reference/androidx/paging/PagingData` of all elements returned from applying the given `https://developer.android.com/reference/androidx/paging/package-summary#(androidx.paging.PagingData).flatMap(java.util.concurrent.Executor,kotlin.Function1)` to each element, as it is loaded. |
| `static final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/paging/PagingData<@https://developer.android.com/reference/androidx/annotation/NonNull T>` | `<T extends https://developer.android.com/reference/java/lang/Object.html> https://developer.android.com/reference/androidx/paging/PagingDataTransforms#(androidx.paging.PagingData).insertFooterItem(androidx.paging.TerminalSeparatorType,kotlin.Any)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/paging/PagingData<@https://developer.android.com/reference/androidx/annotation/NonNull T> receiver, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/paging/TerminalSeparatorType terminalSeparatorType, @https://developer.android.com/reference/androidx/annotation/NonNull T item )` Returns a `https://developer.android.com/reference/androidx/paging/PagingData` containing each original element, with the passed footer `https://developer.android.com/reference/androidx/paging/package-summary#(androidx.paging.PagingData).insertFooterItem(androidx.paging.TerminalSeparatorType,kotlin.Any)` added to the end of the list. |
| `static final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/paging/PagingData<@https://developer.android.com/reference/androidx/annotation/NonNull T>` | `<T extends https://developer.android.com/reference/java/lang/Object.html> https://developer.android.com/reference/androidx/paging/PagingDataTransforms#(androidx.paging.PagingData).insertHeaderItem(androidx.paging.TerminalSeparatorType,kotlin.Any)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/paging/PagingData<@https://developer.android.com/reference/androidx/annotation/NonNull T> receiver, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/paging/TerminalSeparatorType terminalSeparatorType, @https://developer.android.com/reference/androidx/annotation/NonNull T item )` Returns a `https://developer.android.com/reference/androidx/paging/PagingData` containing each original element, with the passed header `https://developer.android.com/reference/androidx/paging/package-summary#(androidx.paging.PagingData).insertHeaderItem(androidx.paging.TerminalSeparatorType,kotlin.Any)` added to the start of the list. |
| `static final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/paging/PagingData<@https://developer.android.com/reference/androidx/annotation/NonNull R>` | `<R extends https://developer.android.com/reference/java/lang/Object.html, T extends R> https://developer.android.com/reference/androidx/paging/PagingDataTransforms#(androidx.paging.PagingData).insertSeparators(androidx.paging.TerminalSeparatorType,java.util.concurrent.Executor,kotlin.Function2)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/paging/PagingData<@https://developer.android.com/reference/androidx/annotation/NonNull T> receiver, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/paging/TerminalSeparatorType terminalSeparatorType, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/concurrent/Executor.html executor, @https://developer.android.com/reference/androidx/annotation/NonNull Function2<T, T, R> generator )` Returns a `https://developer.android.com/reference/androidx/paging/PagingData` containing each original element, with an optional separator generated by `https://developer.android.com/reference/androidx/paging/package-summary#(androidx.paging.PagingData).insertSeparators(androidx.paging.TerminalSeparatorType,java.util.concurrent.Executor,kotlin.Function2)`, given the elements before and after (or null, in boundary conditions). |
| `static final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/paging/PagingData<@https://developer.android.com/reference/androidx/annotation/NonNull R>` | `<T extends https://developer.android.com/reference/java/lang/Object.html, R extends https://developer.android.com/reference/java/lang/Object.html> https://developer.android.com/reference/androidx/paging/PagingDataTransforms#(androidx.paging.PagingData).map(java.util.concurrent.Executor,kotlin.Function1)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/paging/PagingData<@https://developer.android.com/reference/androidx/annotation/NonNull T> receiver, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/concurrent/Executor.html executor, @https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull T, @https://developer.android.com/reference/androidx/annotation/NonNull R> transform )` Returns a `https://developer.android.com/reference/androidx/paging/PagingData` containing the result of applying the given `https://developer.android.com/reference/androidx/paging/package-summary#(androidx.paging.PagingData).map(java.util.concurrent.Executor,kotlin.Function1)` to each element, as it is loaded. |

## Public methods

### filter

Artifact: [androidx.paging:paging-common](https://developer.android.com/jetpack/androidx/releases/paging) [View Source](https://cs.android.com/search?q=file:androidx/paging/PagingDataTransforms.jvm.kt+function:filter) Added in [3.0.0](https://developer.android.com/jetpack/androidx/releases/paging#3.0.0)

```
public static final @NonNull PagingData<@NonNull T> <T extends Object> filter(
    @NonNull PagingData<@NonNull T> receiver,
    @NonNull Executor executor,
    @NonNull Function1<@NonNull T, @NonNull Boolean> predicate
)
```

Returns a `https://developer.android.com/reference/androidx/paging/PagingData` containing only elements matching the given `https://developer.android.com/reference/androidx/paging/package-summary#(androidx.paging.PagingData).filter(java.util.concurrent.Executor,kotlin.Function1)`.

| See also |
|---|---|
| `https://developer.android.com/reference/androidx/paging/package-summary#(androidx.paging.PagingData).filter(java.util.concurrent.Executor,kotlin.Function1)` |   |

### flatMap

Artifact: [androidx.paging:paging-common](https://developer.android.com/jetpack/androidx/releases/paging) [View Source](https://cs.android.com/search?q=file:androidx/paging/PagingDataTransforms.jvm.kt+function:flatMap)

```
public static final @NonNull PagingData<@NonNull R> <T extends Object, R extends Object> flatMap(
    @NonNull PagingData<@NonNull T> receiver,
    @NonNull Executor executor,
    @NonNull Function1<@NonNull T, @NonNull Iterable<@NonNull R>> transform
)
```

Returns a `https://developer.android.com/reference/androidx/paging/PagingData` of all elements returned from applying the given `https://developer.android.com/reference/androidx/paging/package-summary#(androidx.paging.PagingData).flatMap(java.util.concurrent.Executor,kotlin.Function1)` to each element, as it is loaded.

| See also |
|---|---|
| `https://developer.android.com/reference/androidx/paging/package-summary#(androidx.paging.PagingData).flatMap(java.util.concurrent.Executor,kotlin.Function1)` |   |

### insertFooterItem

Artifact: [androidx.paging:paging-common](https://developer.android.com/jetpack/androidx/releases/paging) [View Source](https://cs.android.com/search?q=file:androidx/paging/PagingDataTransforms.kt+function:insertFooterItem) Added in [3.0.0](https://developer.android.com/jetpack/androidx/releases/paging#3.0.0)

```
public static final @NonNull PagingData<@NonNull T> <T extends Object> insertFooterItem(
    @NonNull PagingData<@NonNull T> receiver,
    @NonNull TerminalSeparatorType terminalSeparatorType,
    @NonNull T item
)
```

Returns a `https://developer.android.com/reference/androidx/paging/PagingData` containing each original element, with the passed footer `https://developer.android.com/reference/androidx/paging/package-summary#(androidx.paging.PagingData).insertFooterItem(androidx.paging.TerminalSeparatorType,kotlin.Any)` added to the end of the list.

The footer `https://developer.android.com/reference/androidx/paging/package-summary#(androidx.paging.PagingData).insertFooterItem(androidx.paging.TerminalSeparatorType,kotlin.Any)` is added to a loaded page which marks the end of the data stream in the `https://developer.android.com/reference/androidx/paging/LoadType#APPEND` direction, either by returning null in `https://developer.android.com/reference/androidx/paging/PagingSource.LoadResult.Page#nextKey()`. It will be removed if the last page in the list is dropped, which can happen in the case of loaded pages exceeding `https://developer.android.com/reference/androidx/paging/PagingConfig#maxSize()`.

Note: This operation is not idempotent, calling it multiple times will continually add more footers to the end of the list, which can be useful if multiple footer items are required.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/paging/TerminalSeparatorType terminalSeparatorType` | `https://developer.android.com/reference/androidx/paging/TerminalSeparatorType` used to configure when the header and footer are added. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull T item` | The footer to add to the end of the list once it is fully loaded in the `https://developer.android.com/reference/androidx/paging/LoadType#APPEND` direction. |

| See also |
|---|---|
| `https://developer.android.com/reference/androidx/paging/package-summary#(androidx.paging.PagingData).insertHeaderItem(androidx.paging.TerminalSeparatorType,kotlin.Any)` |   |

### insertHeaderItem

Artifact: [androidx.paging:paging-common](https://developer.android.com/jetpack/androidx/releases/paging) [View Source](https://cs.android.com/search?q=file:androidx/paging/PagingDataTransforms.kt+function:insertHeaderItem) Added in [3.0.0](https://developer.android.com/jetpack/androidx/releases/paging#3.0.0)

```
public static final @NonNull PagingData<@NonNull T> <T extends Object> insertHeaderItem(
    @NonNull PagingData<@NonNull T> receiver,
    @NonNull TerminalSeparatorType terminalSeparatorType,
    @NonNull T item
)
```

Returns a `https://developer.android.com/reference/androidx/paging/PagingData` containing each original element, with the passed header `https://developer.android.com/reference/androidx/paging/package-summary#(androidx.paging.PagingData).insertHeaderItem(androidx.paging.TerminalSeparatorType,kotlin.Any)` added to the start of the list.

The header `https://developer.android.com/reference/androidx/paging/package-summary#(androidx.paging.PagingData).insertHeaderItem(androidx.paging.TerminalSeparatorType,kotlin.Any)` is added to a loaded page which marks the end of the data stream in the `https://developer.android.com/reference/androidx/paging/LoadType#PREPEND` direction by returning null in `https://developer.android.com/reference/androidx/paging/PagingSource.LoadResult.Page#prevKey()`. It will be removed if the first page in the list is dropped, which can happen in the case of loaded pages exceeding `https://developer.android.com/reference/androidx/paging/PagingConfig#maxSize()`.

Note: This operation is not idempotent, calling it multiple times will continually add more headers to the start of the list, which can be useful if multiple header items are required.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/paging/TerminalSeparatorType terminalSeparatorType` | `https://developer.android.com/reference/androidx/paging/TerminalSeparatorType` used to configure when the header and footer are added. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull T item` | The header to add to the front of the list once it is fully loaded in the `https://developer.android.com/reference/androidx/paging/LoadType#PREPEND` direction. |

| See also |
|---|---|
| `https://developer.android.com/reference/androidx/paging/package-summary#(androidx.paging.PagingData).insertFooterItem(androidx.paging.TerminalSeparatorType,kotlin.Any)` |   |

### insertSeparators

Artifact: [androidx.paging:paging-common](https://developer.android.com/jetpack/androidx/releases/paging) [View Source](https://cs.android.com/search?q=file:androidx/paging/PagingDataTransforms.jvm.kt+function:insertSeparators) Added in [3.0.0](https://developer.android.com/jetpack/androidx/releases/paging#3.0.0)

```
public static final @NonNull PagingData<@NonNull R> <R extends Object, T extends R> insertSeparators(
    @NonNull PagingData<@NonNull T> receiver,
    @NonNull TerminalSeparatorType terminalSeparatorType,
    @NonNull Executor executor,
    @NonNull Function2<T, T, R> generator
)
```

Returns a `https://developer.android.com/reference/androidx/paging/PagingData` containing each original element, with an optional separator generated by `https://developer.android.com/reference/androidx/paging/package-summary#(androidx.paging.PagingData).insertSeparators(androidx.paging.TerminalSeparatorType,java.util.concurrent.Executor,kotlin.Function2)`, given the elements before and after (or null, in boundary conditions).

Note that this transform is applied asynchronously, as pages are loaded. Potential separators between pages are only computed once both pages are loaded.

**Kotlin callers should instead use the suspending extension function variant of insertSeparators**

```
/*
 * Create letter separators in an alphabetically sorted list.
 *
 * For example, if the input is:
 *     "apple", "apricot", "banana", "carrot"
 *
 * The operator would output:
 *     "A", "apple", "apricot", "B", "banana", "C", "carrot"
*/
pagingDataStream.map(pagingData ->
        // map outer stream, so we can perform transformations on each paging generation
        PagingDataTransforms.insertSeparators(pagingData, bgExecutor,
                (@Nullable String before, @Nullable String after) -> {
                    if (after != null && (before == null
                            || before.charAt(0) != after.charAt(0))) {
                        // separator - after is first item that starts with its first
                        // letter
                        return Character.toString(
                                Character.toUpperCase(after.charAt(0)));
                    } else {
                        // no separator - either end of list, or first
                        // letters of items are the same
                        return null;
                    }
                }));

/*
 * Create letter separators in an alphabetically sorted list of Items, with UiModel
 * objects.
 *
 * For example, if the input is (each an `Item`):
 *     "apple", "apricot", "banana", "carrot"
 *
 * The operator would output a list of UiModels corresponding to:
 *     "A", "apple", "apricot", "B", "banana", "C", "carrot"
*/
pagingDataStream.map(itemPagingData -> {
    // map outer stream, so we can perform transformations on each paging generation

    // first convert items in stream to UiModel.Item
    PagingData<UiModel.ItemModel> itemModelPagingData = PagingDataTransforms.map(
            itemPagingData, bgExecutor, UiModel.ItemModel::new);

    // Now insert UiModel.Separators, which makes the PagingData of generic type UiModel
    return PagingDataTransforms.insertSeparators(
            itemModelPagingData, bgExecutor,
            (@Nullable UiModel.ItemModel before, @Nullable UiModel.ItemModel after) -> {
                if (after != null && (before == null
                        || before.item.label.charAt(0) != after.item.label.charAt(0))) {
                    // separator - after is first item that starts with its first letter
                    return new UiModel.SeparatorModel(
                            Character.toUpperCase(after.item.label.charAt(0)));
                } else {
                    // no separator - either end of list, or first
                    // letters of items are the same
                    return null;
                }
            });
});

public class UiModel {
    static class ItemModel extends UiModel {
        public Item item;
        ItemModel(Item item) {
            this.item = item;
        }
    }
    static class SeparatorModel extends UiModel {
        public char character;
        SeparatorModel(char character) {
            this.character = character;
        }
    }
}
```

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/paging/TerminalSeparatorType terminalSeparatorType` | `https://developer.android.com/reference/androidx/paging/TerminalSeparatorType` used to configure when the header and footer are added. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/concurrent/Executor.html executor` | `https://developer.android.com/reference/java/util/concurrent/Executor.html` to run the `https://developer.android.com/reference/androidx/paging/package-summary#(androidx.paging.PagingData).insertSeparators(androidx.paging.TerminalSeparatorType,java.util.concurrent.Executor,kotlin.Function2)` function in. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull Function2<T, T, R> generator` | Generator function used to construct a separator item given the item before and the item after. For terminal separators (header and footer), the arguments passed to the generator, `before` and `after`, will be `null` respectively. In cases where the fully paginated list is empty, a single separator will be added where both `before` and `after` items are `null`. |

### map

Artifact: [androidx.paging:paging-common](https://developer.android.com/jetpack/androidx/releases/paging) [View Source](https://cs.android.com/search?q=file:androidx/paging/PagingDataTransforms.jvm.kt+function:map) Added in [3.0.0](https://developer.android.com/jetpack/androidx/releases/paging#3.0.0)

```
public static final @NonNull PagingData<@NonNull R> <T extends Object, R extends Object> map(
    @NonNull PagingData<@NonNull T> receiver,
    @NonNull Executor executor,
    @NonNull Function1<@NonNull T, @NonNull R> transform
)
```

Returns a `https://developer.android.com/reference/androidx/paging/PagingData` containing the result of applying the given `https://developer.android.com/reference/androidx/paging/package-summary#(androidx.paging.PagingData).map(java.util.concurrent.Executor,kotlin.Function1)` to each element, as it is loaded.

| See also |
|---|---|
| `https://developer.android.com/reference/androidx/paging/package-summary#(androidx.paging.PagingData).map(java.util.concurrent.Executor,kotlin.Function1)` |   |