URL Encoding

/**
 * Encode URL parameter value
 * @param value value to encode
 * @param spaceToPlus whether to encode spaces as '+' instead of '%20'
 * @return encoded parameter value
 */
fun encodeURLParameter(value: String, spaceToPlus: Boolean = false): String

/**
 * Encode URL path component
 * @param value path component to encode
 * @param alreadyEncoded whether value is already partially encoded
 * @param encodeSlash whether to encode '/' characters
 * @return encoded path component
 */
fun encodeURLPath(
    value: String, 
    alreadyEncoded: Boolean = false, 
    encodeSlash: Boolean = false
): String

/**
 * Encode path part of URL
 * @param value path part to encode
 * @return encoded path part
 */
fun encodeURLPathPart(value: String): String

/**
 * Encode URL query component
 * @param value query component to encode
 * @param encodeFull whether to encode all reserved characters
 * @param spaceToPlus whether to encode spaces as '+'
 * @param charset character set for encoding
 * @return encoded query component
 */
fun encodeURLQueryComponent(
    value: String,
    encodeFull: Boolean = true,
    spaceToPlus: Boolean = true,
    charset: Charset = Charsets.UTF_8
): String

/**
 * Encode value for OAuth (RFC 5849)
 * @param value value to encode
 * @return OAuth-encoded value
 */
fun encodeOAuth(value: String): String

/**
 * Decode URL-encoded part
 * @param value encoded value
 * @param start start index in value
 * @param end end index in value
 * @param charset character set for decoding
 * @return decoded value
 */
fun decodeURLPart(
    value: String,
    start: Int = 0,
    end: Int = value.length,
    charset: Charset = Charsets.UTF_8
): String

/**
 * Decode URL query component
 * @param value encoded query component
 * @param start start index in value
 * @param end end index in value
 * @param plusIsSpace whether '+' should be decoded as space
 * @param charset character set for decoding
 * @return decoded query component
 */
fun decodeURLQueryComponent(
    value: String,
    start: Int = 0,
    end: Int = value.length,
    plusIsSpace: Boolean = true,
    charset: Charset = Charsets.UTF_8
): String

/**
 * Encode parameters as form URL encoded string
 * @param parameters parameters to encode
 * @return form URL encoded string
 */
fun formUrlEncode(parameters: Parameters): String

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

/**
 * Encode parameters to appendable destination
 * @param parameters parameters to encode
 * @param out destination to append to
 */
fun formUrlEncodeTo(parameters: Parameters, out: Appendable)

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

/**
 * Parse form URL encoded string into parameters
 * @param data form URL encoded data
 * @param charset character set for decoding
 * @param limit maximum number of parameters to parse
 * @return Parameters instance
 */
fun parseUrlEncodedParameters(
    data: String,
    charset: Charset = Charsets.UTF_8,
    limit: Int = 1000
): Parameters

/**
 * Parse query string into parameters
 * @param query query string (without '?')
 * @param start start index in query string
 * @param end end index in query string
 * @param decode whether to decode parameter names and values
 * @return Parameters instance
 */
fun parseQueryString(
    query: String,
    start: Int = 0,
    end: Int = query.length,
    decode: Boolean = true
): Parameters

/**
 * Parameters builder with URL decoding support
 */
class UrlDecodedParametersBuilder(
    private val charset: Charset = Charsets.UTF_8
) : StringValuesBuilderImpl() {
    
    override fun build(): Parameters
}

import io.ktor.http.*
import java.nio.charset.Charset

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

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

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

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

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

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

// URL decoding
val encodedUrl = "hello%20world%26more"
val decodedUrl = decodeURLPart(encodedUrl)
println(decodedUrl) // hello world&more

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

// Form URL encoding
val parameters = parameters {
    append("name", "John Doe")
    append("email", "john@example.com")
    append("interests", "coding")
    append("interests", "music")
}

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

// Form encoding from pairs
val pairs = listOf(
    "username" to "user@domain.com",
    "password" to "secret123!",
    "remember" to "true"
)
val formFromPairs = formUrlEncode(pairs)
println(formFromPairs) // username=user%40domain.com&password=secret123%21&remember=true

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

// Query string parsing
val queryString = "q=kotlin+http&category=programming&page=1"
val queryParams = parseQueryString(queryString)
println(queryParams["q"]) // kotlin http
println(queryParams["category"]) // programming
println(queryParams["page"]) // 1

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

// Custom charset encoding/decoding
val japaneseText = "こんにちは"
val utf8Encoded = encodeURLQueryComponent(japaneseText, charset = Charsets.UTF_8)
val decodedJapanese = decodeURLQueryComponent(utf8Encoded, charset = Charsets.UTF_8)
println("Original: $japaneseText")
println("Encoded: $utf8Encoded")
println("Decoded: $decodedJapanese")

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

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

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

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

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

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

// Error handling
try {
    val invalidEncoded = "invalid%GG"
    decodeURLPart(invalidEncoded)
} catch (e: URLDecodeException) {
    println("Failed to decode URL: ${e.message}")
}

// Utility functions for common patterns
fun buildSearchUrl(baseUrl: String, query: String, filters: Map<String, String>): String {
    return URLBuilder(baseUrl).apply {
        parameters.append("q", query)
        filters.forEach { (key, value) ->
            parameters.append(key, value)
        }
    }.buildString()
}

val searchUrl = buildSearchUrl(
    "https://example.com/search",
    "kotlin tutorials",
    mapOf("level" to "beginner", "type" to "video")
)

/**
 * Exception thrown when URL decoding fails
 */
class URLDecodeException(message: String) : Exception