# BackStackMatcher

Artifact: [androidx.navigation3:navigation3-runtime](https://developer.android.com/jetpack/androidx/releases/navigation3) [View Source](https://cs.android.com/search?q=file:androidx/navigation3/runtime/deeplink/BackStackMatcher.kt+class:androidx.navigation3.runtime.deeplink.BackStackMatcher) Added in [1.2.0](https://developer.android.com/jetpack/androidx/releases/navigation3#1.2.0) Common/AllAndroid/JVM
- Cmn

  ```
  class BackStackMatcher<T : K, K : Any> : DeepLinkMatcher<T, BackStackMatchResult<T, K>>
  ```

|---|---|---|
| [kotlin.Any](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html) |||
| ↳ | [androidx.navigation3.runtime.deeplink.DeepLinkMatcher](https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher)\<T, [BackStackMatchResult](https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/BackStackMatchResult)\<T, K\>\> ||
|   | ↳ | [androidx.navigation3.runtime.deeplink.BackStackMatcher](https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/BackStackMatcher) |

*** ** * ** ***

A `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher` that builds a back stack when match succeeds.

Must be created by calling `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/package-summary#(androidx.navigation3.runtime.deeplink.DeepLinkMatcher).withBackStack(kotlin.Function1)` on a `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher`. The receiving `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher` will become the nested `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/BackStackMatcher#matcher()`.

Wraps the provided `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/BackStackMatcher#matcher()` and matches it with a `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkRequest`. When a match succeeds, returns a `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/BackStackMatchResult` containing the original `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher.MatchResult` and the back stack built with the back stack builder.

`https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/BackStackMatcher` the type of the navigation key associated with this matcher, must be of type `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/BackStackMatcher`

`https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/BackStackMatcher` the element type of the back stack `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html`

```kotlin
import androidx.navigation3.runtime.NavKey
import androidx.navigation3.runtime.deeplink.BackStackMatchResult
import androidx.navigation3.runtime.deeplink.DeepLinkMatcher
import androidx.navigation3.runtime.deeplink.DeepLinkRequest
import androidx.navigation3.runtime.deeplink.DeepLinkUri
import androidx.navigation3.runtime.deeplink.UriDeepLinkMatcher
import androidx.navigation3.runtime.deeplink.withBackStack

val matcher =
    UriDeepLinkMatcher(
            uriPattern = DeepLinkUri("https://www.nav3deeplinksample.com/userlist"),
            serializer = serializer<UserListKey>(),
        )
        .withBackStack { matchResult -> listOf(HomeKey, matchResult.key) }

// handling a request
val request = DeepLinkRequest(uri = DeepLinkUri("https://www.nav3deeplinksample.com/userlist/"))
// returns a BackStackMatchResult containing the matched key and the constructed back stack
val matchResult: BackStackMatchResult<UserListKey, NavKey>? = matcher.match(request)
// listOf(HomeKey, UserListKey)
val backStack: List<NavKey>? = matchResult?.backStack
val key: UserListKey? = matchResult?.key
```

```kotlin
import androidx.navigation3.runtime.NavKey
import androidx.navigation3.runtime.deeplink.BackStackMatchResult
import androidx.navigation3.runtime.deeplink.DeepLinkMatcher
import androidx.navigation3.runtime.deeplink.DeepLinkRequest
import androidx.navigation3.runtime.deeplink.DeepLinkUri
import androidx.navigation3.runtime.deeplink.UriDeepLinkMatcher
import androidx.navigation3.runtime.deeplink.withBackStack

val matcher =
    UriDeepLinkMatcher(
            uriPattern = DeepLinkUri("https://www.nav3deeplinksample.com/articles/{id}"),
            serializer = serializer<Article>(),
        )
        .withBackStack { matchResult ->
            val article = matchResult.key
            val parent =
                if (article.id >= 10) ArticleSection("Shipping") else ArticleSection("Returns")
            listOf(parent, article)
        }

// handling a request
val request =
    DeepLinkRequest(uri = DeepLinkUri("https://www.nav3deeplinksample.com/articles/12"))

// returns a BackStackMatchResult containing the Article key and parent key based on article id
val matchResult: BackStackMatchResult<Article, NavKey>? = matcher.match(request)
// listOf(parent, article)
val backStack: List<NavKey>? = matchResult?.backStack
val key: Article? = matchResult?.key
```

## Summary

| ### Protected functions |
|---|---|---|
| `open https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/BackStackMatchResult<T, K>?` | `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/BackStackMatcher#matchRequest(androidx.navigation3.runtime.deeplink.DeepLinkRequest)(request: https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkRequest)` Matches a `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkRequest` to a `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher`. | Cmn |

### Inherited functions

From [androidx.navigation3.runtime.deeplink.DeepLinkMatcher](https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher) `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/BackStackMatchResult<T, K>?` `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher#match(androidx.navigation3.runtime.deeplink.DeepLinkRequest)(request: https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkRequest)`

Matches a `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkRequest` to a `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher`.
Cmn

## Protected functions

### matchRequest

Cmn

```
protected open fun matchRequest(request: DeepLinkRequest): BackStackMatchResult<T, K>?
```

Matches a `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkRequest` to a `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher`.

The core function that is called within the matching process after all `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher#filters()` are applied. Subclasses should override this to implement matching logic beyond matching `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher#filters()`.

Returns `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher.MatchResult` if it is a match, and returns null otherwise.

| Parameters |
|---|---|
| `request: https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkRequest` | the `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkRequest` to match against |