0
# URL Handling
1

2
HTTP URL parsing, building, and manipulation with full RFC compliance.
3

4
## HttpUrl
5

6
Immutable URL with builder pattern for construction and modification.
7

8
```kotlin { .api }
9
class HttpUrl private constructor() {
10
    val scheme: String
11
    val username: String
12
    val password: String
13
    val host: String
14
    val port: Int
15
    val pathSize: Int
16
    val pathSegments: List<String>
17
    val querySize: Int
18
    val queryParameterNames: Set<String>
19
    val fragment: String?
20
    val isHttps: Boolean
21
    
22
    fun pathSegment(index: Int): String
23
    fun queryParameter(name: String): String?
24
    fun queryParameterValue(index: Int): String?
25
    fun queryParameterName(index: Int): String
26
    fun queryParameterValues(name: String): List<String>
27
    fun encodedQuery(): String?
28
    fun query(): String?
29
    fun encodedFragment(): String?
30
    fun encodedPath(): String
31
    fun encodedUsername(): String
32
    fun encodedPassword(): String
33
    fun pathSegments(): List<String>
34
    fun redact(): HttpUrl
35
    fun resolve(link: String): HttpUrl?
36
    fun newBuilder(): Builder
37
    fun newBuilder(link: String): Builder?
38
    fun toUrl(): URL
39
    fun toUri(): URI
40
    
41
    class Builder {
42
        fun scheme(scheme: String): Builder
43
        fun username(username: String): Builder
44
        fun encodedUsername(encodedUsername: String): Builder
45
        fun password(password: String): Builder
46
        fun encodedPassword(encodedPassword: String): Builder
47
        fun host(host: String): Builder
48
        fun port(port: Int): Builder
49
        fun addPathSegment(pathSegment: String): Builder
50
        fun addPathSegments(pathSegments: String): Builder
51
        fun addEncodedPathSegment(encodedPathSegment: String): Builder
52
        fun addEncodedPathSegments(encodedPathSegments: String): Builder
53
        fun setPathSegment(index: Int, pathSegment: String): Builder
54
        fun setEncodedPathSegment(index: Int, encodedPathSegment: String): Builder
55
        fun removePathSegment(index: Int): Builder
56
        fun encodedPath(encodedPath: String): Builder
57
        fun query(query: String?): Builder
58
        fun encodedQuery(encodedQuery: String?): Builder
59
        fun addQueryParameter(name: String, value: String?): Builder
60
        fun addEncodedQueryParameter(encodedName: String, encodedValue: String?): Builder
61
        fun setQueryParameter(name: String, value: String?): Builder
62
        fun setEncodedQueryParameter(encodedName: String, encodedValue: String?): Builder
63
        fun removeAllQueryParameters(name: String): Builder
64
        fun removeAllEncodedQueryParameters(encodedName: String): Builder
65
        fun fragment(fragment: String?): Builder
66
        fun encodedFragment(encodedFragment: String?): Builder
67
        fun build(): HttpUrl
68
    }
69
    
70
    companion object {
71
        fun parse(url: String): HttpUrl?
72
        fun get(url: String): HttpUrl
73
        fun get(url: URL): HttpUrl
74
        fun get(uri: URI): HttpUrl
75
    }
76
}
77
```
78

79
### URL Building Examples
80

81
```kotlin
82
// Parse existing URL
83
val url = "https://api.example.com/users?page=1".toHttpUrl()
84

85
// Build URL programmatically  
86
val apiUrl = HttpUrl.Builder()
87
    .scheme("https")
88
    .host("api.example.com")
89
    .addPathSegment("users")
90
    .addPathSegment("123")
91
    .addQueryParameter("include", "profile")
92
    .addQueryParameter("format", "json")
93
    .build()
94

95
// Modify existing URL
96
val modifiedUrl = url.newBuilder()
97
    .addQueryParameter("limit", "50")
98
    .addPathSegment("details")
99
    .build()
100
```