0
# URL Encoding
1

2
URL encoding utilities and form data handling for query parameters, path components, and request bodies with proper charset support and RFC compliance.
3

4
## Capabilities
5

6
### URL Component Encoding
7

8
Functions for encoding different parts of URLs with appropriate encoding rules.
9

10
```kotlin { .api }
11
/**
12
 * Encode URL parameter value
13
 * @param value value to encode
14
 * @param spaceToPlus whether to encode spaces as '+' instead of '%20'
15
 * @return encoded parameter value
16
 */
17
fun encodeURLParameter(value: String, spaceToPlus: Boolean = false): String
18

19
/**
20
 * Encode URL path component
21
 * @param value path component to encode
22
 * @param alreadyEncoded whether value is already partially encoded
23
 * @param encodeSlash whether to encode '/' characters
24
 * @return encoded path component
25
 */
26
fun encodeURLPath(
27
    value: String, 
28
    alreadyEncoded: Boolean = false, 
29
    encodeSlash: Boolean = false
30
): String
31

32
/**
33
 * Encode path part of URL
34
 * @param value path part to encode
35
 * @return encoded path part
36
 */
37
fun encodeURLPathPart(value: String): String
38

39
/**
40
 * Encode URL query component
41
 * @param value query component to encode
42
 * @param encodeFull whether to encode all reserved characters
43
 * @param spaceToPlus whether to encode spaces as '+'
44
 * @param charset character set for encoding
45
 * @return encoded query component
46
 */
47
fun encodeURLQueryComponent(
48
    value: String,
49
    encodeFull: Boolean = true,
50
    spaceToPlus: Boolean = true,
51
    charset: Charset = Charsets.UTF_8
52
): String
53

54
/**
55
 * Encode value for OAuth (RFC 5849)
56
 * @param value value to encode
57
 * @return OAuth-encoded value
58
 */
59
fun encodeOAuth(value: String): String
60
```
61

62
### URL Component Decoding
63

64
Functions for decoding URL-encoded components.
65

66
```kotlin { .api }
67
/**
68
 * Decode URL-encoded part
69
 * @param value encoded value
70
 * @param start start index in value
71
 * @param end end index in value
72
 * @param charset character set for decoding
73
 * @return decoded value
74
 */
75
fun decodeURLPart(
76
    value: String,
77
    start: Int = 0,
78
    end: Int = value.length,
79
    charset: Charset = Charsets.UTF_8
80
): String
81

82
/**
83
 * Decode URL query component
84
 * @param value encoded query component
85
 * @param start start index in value
86
 * @param end end index in value
87
 * @param plusIsSpace whether '+' should be decoded as space
88
 * @param charset character set for decoding
89
 * @return decoded query component
90
 */
91
fun decodeURLQueryComponent(
92
    value: String,
93
    start: Int = 0,
94
    end: Int = value.length,
95
    plusIsSpace: Boolean = true,
96
    charset: Charset = Charsets.UTF_8
97
): String
98
```
99

100
### Form URL Encoding
101

102
Functions for encoding and decoding application/x-www-form-urlencoded data.
103

104
```kotlin { .api }
105
/**
106
 * Encode parameters as form URL encoded string
107
 * @param parameters parameters to encode
108
 * @return form URL encoded string
109
 */
110
fun formUrlEncode(parameters: Parameters): String
111

112
/**
113
 * Encode parameter pairs as form URL encoded string
114
 * @param parameters parameter name-value pairs
115
 * @return form URL encoded string
116
 */
117
fun formUrlEncode(parameters: List<Pair<String, String>>): String
118

119
/**
120
 * Encode parameters to appendable destination
121
 * @param parameters parameters to encode
122
 * @param out destination to append to
123
 */
124
fun formUrlEncodeTo(parameters: Parameters, out: Appendable)
125

126
/**
127
 * Encode parameter pairs to appendable destination
128
 * @param parameters parameter name-value pairs
129
 * @param out destination to append to
130
 */
131
fun formUrlEncodeTo(parameters: List<Pair<String, String>>, out: Appendable)
132

133
/**
134
 * Parse form URL encoded string into parameters
135
 * @param data form URL encoded data
136
 * @param charset character set for decoding
137
 * @param limit maximum number of parameters to parse
138
 * @return Parameters instance
139
 */
140
fun parseUrlEncodedParameters(
141
    data: String,
142
    charset: Charset = Charsets.UTF_8,
143
    limit: Int = 1000
144
): Parameters
145
```
146

147
### Query String Parsing
148

149
Functions for parsing URL query strings.
150

151
```kotlin { .api }
152
/**
153
 * Parse query string into parameters
154
 * @param query query string (without '?')
155
 * @param start start index in query string
156
 * @param end end index in query string
157
 * @param decode whether to decode parameter names and values
158
 * @return Parameters instance
159
 */
160
fun parseQueryString(
161
    query: String,
162
    start: Int = 0,
163
    end: Int = query.length,
164
    decode: Boolean = true
165
): Parameters
166
```
167

168
### URL Decoded Parameters Builder
169

170
Builder for parameters with automatic URL decoding support.
171

172
```kotlin { .api }
173
/**
174
 * Parameters builder with URL decoding support
175
 */
176
class UrlDecodedParametersBuilder(
177
    private val charset: Charset = Charsets.UTF_8
178
) : StringValuesBuilderImpl() {
179
    
180
    override fun build(): Parameters
181
}
182
```
183

184
**Usage Examples:**
185

186
```kotlin
187
import io.ktor.http.*
188
import java.nio.charset.Charset
189

190
// URL parameter encoding
191
val searchTerm = "hello world & more"
192
val encodedParam = encodeURLParameter(searchTerm, spaceToPlus = true)
193
println(encodedParam) // hello+world+%26+more
194

195
val encodedParamSpaces = encodeURLParameter(searchTerm, spaceToPlus = false)
196
println(encodedParamSpaces) // hello%20world%20%26%20more
197

198
// URL path encoding
199
val pathSegment = "user/data with spaces"
200
val encodedPath = encodeURLPath(pathSegment, encodeSlash = false)
201
println(encodedPath) // user/data%20with%20spaces
202

203
val encodedPathWithSlash = encodeURLPath(pathSegment, encodeSlash = true)
204
println(encodedPathWithSlash) // user%2Fdata%20with%20spaces
205

206
// Query component encoding
207
val queryValue = "value with special chars: &=+"
208
val encodedQuery = encodeURLQueryComponent(queryValue)
209
println(encodedQuery) // value+with+special+chars%3A+%26%3D%2B
210

211
// OAuth encoding (stricter than standard URL encoding)
212
val oauthValue = "oauth signature value"
213
val encodedOAuth = encodeOAuth(oauthValue)
214
println(encodedOAuth) // oauth%20signature%20value
215

216
// URL decoding
217
val encodedUrl = "hello%20world%26more"
218
val decodedUrl = decodeURLPart(encodedUrl)
219
println(decodedUrl) // hello world&more
220

221
val encodedQuery2 = "search=hello+world&category=tech%26science"
222
val decodedQuery = decodeURLQueryComponent("hello+world")
223
println(decodedQuery) // hello world
224

225
// Form URL encoding
226
val parameters = parameters {
227
    append("name", "John Doe")
228
    append("email", "john@example.com")
229
    append("interests", "coding")
230
    append("interests", "music")
231
}
232

233
val formEncoded = formUrlEncode(parameters)
234
println(formEncoded) // name=John+Doe&email=john%40example.com&interests=coding&interests=music
235

236
// Form encoding from pairs
237
val pairs = listOf(
238
    "username" to "user@domain.com",
239
    "password" to "secret123!",
240
    "remember" to "true"
241
)
242
val formFromPairs = formUrlEncode(pairs)
243
println(formFromPairs) // username=user%40domain.com&password=secret123%21&remember=true
244

245
// Parse form URL encoded data
246
val formData = "name=John+Doe&email=john%40example.com&age=25"
247
val parsedParams = parseUrlEncodedParameters(formData)
248
println(parsedParams["name"]) // John Doe
249
println(parsedParams["email"]) // john@example.com
250
println(parsedParams["age"]) // 25
251

252
// Query string parsing
253
val queryString = "q=kotlin+http&category=programming&page=1"
254
val queryParams = parseQueryString(queryString)
255
println(queryParams["q"]) // kotlin http
256
println(queryParams["category"]) // programming
257
println(queryParams["page"]) // 1
258

259
// Parse without decoding (raw values)
260
val rawParams = parseQueryString(queryString, decode = false)
261
println(rawParams["q"]) // kotlin+http
262

263
// Custom charset encoding/decoding
264
val japaneseText = "こんにちは"
265
val utf8Encoded = encodeURLQueryComponent(japaneseText, charset = Charsets.UTF_8)
266
val decodedJapanese = decodeURLQueryComponent(utf8Encoded, charset = Charsets.UTF_8)
267
println("Original: $japaneseText")
268
println("Encoded: $utf8Encoded")
269
println("Decoded: $decodedJapanese")
270

271
// Building URLs with proper encoding
272
val baseUrl = "https://api.example.com/search"
273
val searchQuery = "kotlin & spring boot"
274
val category = "web development"
275

276
val url = URLBuilder(baseUrl).apply {
277
    parameters.append("q", searchQuery) // Automatically encoded
278
    parameters.append("category", category)
279
    parameters.append("limit", "10")
280
}.build()
281

282
println(url.toString())
283
// https://api.example.com/search?q=kotlin+%26+spring+boot&category=web+development&limit=10
284

285
// Form data for POST requests
286
val postData = parameters {
287
    append("title", "My Blog Post")
288
    append("content", "This is the content with special chars: <>&\"")
289
    append("tags", "web")
290
    append("tags", "kotlin")
291
}
292

293
val postBody = formUrlEncode(postData)
294
// Can be used as request body with Content-Type: application/x-www-form-urlencoded
295

296
// URL-decoded parameters builder
297
val builder = UrlDecodedParametersBuilder(Charsets.UTF_8)
298
builder.append("encoded", "hello%20world")
299
val builtParams = builder.build()
300
println(builtParams["encoded"]) // hello world (automatically decoded)
301

302
// Error handling
303
try {
304
    val invalidEncoded = "invalid%GG"
305
    decodeURLPart(invalidEncoded)
306
} catch (e: URLDecodeException) {
307
    println("Failed to decode URL: ${e.message}")
308
}
309

310
// Utility functions for common patterns
311
fun buildSearchUrl(baseUrl: String, query: String, filters: Map<String, String>): String {
312
    return URLBuilder(baseUrl).apply {
313
        parameters.append("q", query)
314
        filters.forEach { (key, value) ->
315
            parameters.append(key, value)
316
        }
317
    }.buildString()
318
}
319

320
val searchUrl = buildSearchUrl(
321
    "https://example.com/search",
322
    "kotlin tutorials",
323
    mapOf("level" to "beginner", "type" to "video")
324
)
325
```
326

327
## Types
328

329
All types are defined above in their respective capability sections.
330

331
## Exceptions
332

333
```kotlin { .api }
334
/**
335
 * Exception thrown when URL decoding fails
336
 */
337
class URLDecodeException(message: String) : Exception
338
```