# UriDeepLinkMatcher

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/UriDeepLinkMatcher.kt+class:androidx.navigation3.runtime.deeplink.UriDeepLinkMatcher) Added in [1.2.0](https://developer.android.com/jetpack/androidx/releases/navigation3#1.2.0) Common/AllAndroid/JVM
- Cmn

  ```
  open class UriDeepLinkMatcher<T : Any> : DeepLinkMatcher<T, UriMatchResult<T>>
  ```

|---|---|---|
| [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, [UriMatchResult](https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/UriMatchResult)\<T\>\> ||
|   | ↳ | [androidx.navigation3.runtime.deeplink.UriDeepLinkMatcher](https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/UriDeepLinkMatcher) |

*** ** * ** ***

A `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher` implementation that matches based on `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkUri`. Returns a `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/UriMatchResult` upon a successful match.

If the matcher constructed with this overload matches a `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkRequest`, the provided `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/UriDeepLinkMatcher#(androidx.navigation3.runtime.deeplink.DeepLinkUri,kotlinx.serialization.KSerializer,kotlin.collections.List)` will be used to instantiate the deep link target's navigation key.

`https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/UriDeepLinkMatcher` The type of the navigation key associated with this deep link.

**Supported Path patterns and extracted argument examples**

1. Exact Path

   - Pattern: `www.example.com/users`

   - Arguments: `https://www.example.com/users`

   - Extracted values: Extracts no arguments.

2. Single placeholder

   - Pattern: `www.example.com/users/{id}`

   - Arguments: Extracts argument `["id"]`.

   - Request: `https://www.example.com/users/123`

   - Extracted values: Maps "id" to "123".

3. Multiple placeholders

   - Pattern: `www.example.com/users/{first}-{last}`

   - Arguments: Extracts arguments "first", "last".

   - Request: `https://www.example.com/users/john-doe`

   - Extracted values: Maps "first" to "john" and "last" to "doe".

4. Wildcard

   - Pattern: `www.example.com/users/.*`

   - Arguments: Extracts no arguments.

   - Request: `www.example.com/users/123/456`

   - Extracted values: None extracted.

5. Mixed literal and placeholder

   - Pattern: `www.example.com/users/user_{id}`

   - Arguments: Extracts argument "id".

   - Request: `https://www.example.com/users/user_123`

   - Extracted values: Maps "id" to "123".

6. Empty String

   - Pattern: `www.example.com/users/{id}/profile`

   - Arguments: Extracts argument "id".

   - Request: `www.example.com/users//profile`

   - Extracted values: Maps "id" to "".

**Supported Query Pattern Types and Examples**

1. Named Parameter

   - Pattern: `?name={name}`

   - Arguments: Extracts argument "name".

   - Request: `?name=john`

   - Extracted values: Maps "name" to "john".

2. Unnamed Parameter

   - Pattern: `?{rawQuery}`

   - Arguments: Extracts argument "rawQuery".

   - Request: `?anything&else`

   - Extracted values: Maps "rawQuery" to "anything", "else".

3. Partial Literal Matching

   - Pattern: `?type=user_{id}`

   - Arguments: Extracts argument "id".

   - Request: `?type=user_123`

   - Extracted values: Maps "id" to "123".

4. Multiple Placeholders in One Parameter

   - Pattern: `?name={first}_{last}`

   - Arguments: Extracts arguments "first", "last".

   - Request: `?name=john_doe`

   - Extracted values: Maps "first" to "john" and "last" to "doe".

5. Collection Parameters

   - Pattern: `?list={list}`

   - Arguments: Extracts argument "list".

   - Request: `?list=10&list=20`

   - Extracted values: Maps "list" to "10", "20".

6. Wildcard Matching

   - Pattern: `?type=user_.*`

   - Arguments: Extracts argument "type".

   - Request: `?type=user_admin`

   - Extracted values: Maps "type" to "admin".

7. Mixed Named and Unnamed Parameters

   - Pattern: `?user={name}&{other}`

   - Arguments: Extracts arguments "name", "other".

   - Request: `?user=john&something`

   - Extracted values: Maps "name" to "john" and "other" to "something".

**Unsupported Query Pattern Types and Examples**

1. Repeated Parameter Names in Pattern

   - Pattern: `www.example.com?name={first}&name={last}`

2. Extra Parameters

   - Pattern: `?name={name}`

   - Arguments: Extracts arguments "name".

   - Request: `?name=john&city=someCity`

   - Extracted values: Maps "name" to "john". // city is ignored

3. Multiple Unnamed Parameters in Pattern

   - Pattern: `?{arg1}&{arg2}`

**Supported Fragment Pattern Types and Examples**

1. Static Fragment

   - Pattern: `#section1`

   - Arguments: None

   - Request: `#section1`

   - Extracted values: None extracted.

2. Single Placeholder

   - Pattern: `#section_{id}`

   - Arguments: Extracts argument "id".

   - Request: `#section_123`

   - Extracted values: Maps "id" to "123".

3. Wildcard

   - Pattern: `#section_.*`

   - Arguments: Extracts no arguments

   - Request: `#section_123`

   - Extracted values: None extracted.

**Note on empty query values** If the provided value in the query is an empty string, for example

```kotlin
val request = "...?name=&age="
```

It is handled depending on whether the argument type is a String

- Strings: Treated as a literal empty string ""

- Non-Strings (Primitive or Non-Primitive): Treated as no provided value. Falls back to default value if there is one. Otherwise, this is considered as a missing required value and matching would fail.

**Note on Non-Primitive Arguments** `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/UriDeepLinkMatcher` that contain non-primitive argument type, such as the Profile class below:

```kotlin
data class User(val name: String, val age: Int)
data class Profile(user: User, id: Int): NavKey
```

is supported by default if the matching `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkRequest` contains a flattened map of arguments:

```kotlin
val deeplinkUri = DeepLinkUri("www.nav3example.com/profile?name=john&age=25&id=1234")
```

The flattened map of arguments must NOT contain repeated param names with different types. For example the duplicated name "id" where the User id is a String and the Profile id is an Int can lead to unpredictable mismatches during matching:

```kotlin
data class User(val id: String, val name: String)
data class Profile(user: User, id: Int): NavKey
```

If duplicate names have the same type, they will be populated with the same value.

## Summary

| ### Public constructors |
|---|---|
| `<T : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html> https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/UriDeepLinkMatcher#UriDeepLinkMatcher(androidx.navigation3.runtime.deeplink.DeepLinkUri,kotlinx.serialization.KSerializer,kotlin.collections.List)( uriPattern: https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkUri, serializer: https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-k-serializer/index.html<T>, filters: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher.Filter> )` | Cmn |

| ### Protected functions |
|---|---|---|
| `open https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/UriMatchResult<T>?` | `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/UriDeepLinkMatcher#matchArguments(kotlin.collections.Map,kotlin.collections.Map,kotlin.collections.Map)( pathArgs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-map/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html>>, queryArgs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-map/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html>>, fragmentArgs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-map/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html>> )` Matches the argument values extracted from `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkRequest#uri()` and instantiates a `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/UriDeepLinkMatcher` instance with the provided `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/UriDeepLinkMatcher#serializer()` and extracted values. | Cmn |
| `open https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/UriMatchResult<T>?` | `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/UriDeepLinkMatcher#matchRequest(androidx.navigation3.runtime.deeplink.DeepLinkRequest)(request: https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkRequest)` Matches this matcher against a `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkRequest`. | Cmn |
| `open https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/UriMatchResult<T>?` | `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/UriDeepLinkMatcher#matchUri(androidx.navigation3.runtime.deeplink.DeepLinkUri)(uri: https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkUri)` Matches this `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/UriDeepLinkMatcher` against a `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkRequest#uri()`. | 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/UriMatchResult<T>?` `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

## Public constructors

### UriDeepLinkMatcher

Cmn

```
<T : Any> UriDeepLinkMatcher(
    uriPattern: DeepLinkUri,
    serializer: KSerializer<T>,
    filters: List<DeepLinkMatcher.Filter> = emptyList()
)
```

| Parameters |
|---|---|
| `uriPattern: https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkUri` | The `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkUri` containing the uri pattern that this matcher supports. |
| `serializer: https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-k-serializer/index.html<T>` | The serializer to instantiate an instance of `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/UriDeepLinkMatcher` |
| `filters: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher.Filter> = emptyList()` | an optional list of filters to filter a `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkRequest` when matching |

## Protected functions

### matchArguments

Cmn

```
protected open fun matchArguments(
    pathArgs: Map<String, List<String>> = emptyMap(),
    queryArgs: Map<String, List<String>> = emptyMap(),
    fragmentArgs: Map<String, List<String>> = emptyMap()
): UriMatchResult<T>?
```

Matches the argument values extracted from `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkRequest#uri()` and instantiates a `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/UriDeepLinkMatcher` instance with the provided `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/UriDeepLinkMatcher#serializer()` and extracted values.

| Parameters |
|---|---|
| `pathArgs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-map/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html>> = emptyMap()` | The extracted path arguments. Empty if no values were extracted. |
| `queryArgs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-map/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html>> = emptyMap()` | The extracted query arguments. Empty if the uri contains no query or no values were extracted. |
| `fragmentArgs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-map/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html>> = emptyMap()` | The extracted fragment arguments. Empty if the uri contains no fragment or no values were extracted. |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/UriMatchResult<T>?` | A `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/UriMatchResult` containing the navigation key `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/UriDeepLinkMatcher` and extracted arguments if matched, null otherwise. |

### matchRequest

Cmn

```
protected open fun matchRequest(request: DeepLinkRequest): UriMatchResult<T>?
```

Matches this matcher against a `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkRequest`.

Match succeeds if:

- request passes all the provided `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher#filters()`

- can successfully instantiate a `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/UriDeepLinkMatcher` instance with the `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/UriDeepLinkMatcher#serializer()` based on the provided arguments extracted from the request

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

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/UriMatchResult<T>?` | A `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/UriMatchResult` containing the navigation key `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/UriDeepLinkMatcher` and extracted arguments if matched, null otherwise. |

### matchUri

Cmn

```
protected open fun matchUri(uri: DeepLinkUri): UriMatchResult<T>?
```

Matches this `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/UriDeepLinkMatcher` against a `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkRequest#uri()`.

It checks for scheme, authority, and path segment count. If they match, proceeds to extract all argument values from the `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkRequest#uri()`.

| Parameters |
|---|---|
| `uri: https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkUri` | The requested `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkUri` to match with. |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/UriMatchResult<T>?` | A `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/UriMatchResult` containing the navigation key `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/UriDeepLinkMatcher` and extracted arguments if matched, null otherwise. |