URL Encoder for Kotlin

A simple library to encode/decode URL parameters.

This library was adapted from the RIFE2 Web Application Framework.
A pure Java version can also be found at https://github.com/gbevin/urlencoder.

For decades we've been using java.net.URLEncoder because of its improper naming. It is actually intended to encode HTML form parameters, not URLs, causing the wrong escape sequences to be used.

Additionally, java.net.URLEncoder allocates memory even when no encoding is necessary, significantly impacting performance. This library has a negligible performance impact when the specified string doesn't need to be encoded.

Android's Uri.encode also addresses the same issues.

Examples (TL;DR)

UrlEncoder.encode("a test &") // -> a%20test%20%26
UrlEncoder.encode("%#okékÉȢ smile!😁") // -> %25%23ok%C3%A9k%C3%89%C8%A2%20smile%21%F0%9F%98%81
UrlEncoder.encode("?test=a test", allow = "?=") // -> ?test=a%20test

UrlEncoder.decode("a%20test%20%26") // -> a test &
UrlEncoder.decode("%25%23ok%C3%A9k%C3%89%C8%A2%20smile%21%F0%9F%98%81") // -> %#okékÉȢ smile!😁

Gradle, Maven, etc.

To use with Gradle, include the following dependency in your build file:

repositories {
    mavenCentral()
    maven { url = uri("https://oss.sonatype.org/content/repositories/snapshots") } // only needed for SNAPSHOT
}

dependencies {
    implementation("net.thauvin.erik:urlencoder:1.0.0")
}

Instructions for using with Maven, Ivy, etc. can be found on Maven Central.

Standalone usage

UrlEncoder can be used on the command line also, both for encoding and decoding.

You have two options:

run it with Gradle
build the jar and launch it with Java

The usage is as follows:

Encode and decode URL parameters.
  -e  encode (default)
  -d  decode

Running with Gradle

./gradlew run --args="-e 'a test &'"        # -> a%20test%20%26
./gradlew run --args="%#okékÉȢ"             # -> %25%23ok%C3%A9k%C3%89%C8%A2

./gradlew run --args="-d 'a%20test%20%26'"  # -> a test &

Running with Java

First build the jar file:

./gradlew clean fatJar

Then run it:

java -jar lib/build/libs/urlencoder-*all.jar -e "a test &"       # -> a%20test%20%26
java -jar lib/build/libs/urlencoder-*all.jar "%#okékÉȢ"          # -> %25%23ok%C3%A9k%C3%89%C8%A2

java -jar lib/build/libs/urlencoder-*.all.jar -d "a%20test%20%26" # -> a test &

3.9 KiB Raw Blame History Unescape Escape