Added URLEncoder section

README.md

@@ -47,7 +47,7 @@ To use with [Gradle](https://gradle.org/), include the following dependency in y
 
 ```gradle
 dependencies {
-    implementation("com.uwyn:urlencoder:1.1.0")
+    implementation("com.uwyn:urlencoder:1.2.0")
 }
 ```
 
@@ -94,3 +94,35 @@ java -jar lib/build/libs/urlencoder-*.jar "%#okékÉȢ"          # -> %25%23ok%C
 
 java -jar lib/build/libs/urlencoder-*.jar -d "a%20test%20%26" # -> a test &
 ```
+
+## Why not simply use `java.net.URLEncoder`?
+
+Apart for being quite inefficient, some URL components encoded with `URLEncoder.encode` might not be able to be properly decoded.
+
+For example, a simply search query such as:
+
+```kotlin
+var u = URLEncoder.encode("foo + bar", StandardCharsets.UTF_8);
+```
+
+would be encoded as:
+
+```
+foo+%28+bar
+```
+
+Trying to decode it with [Spring](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/web/util/UriUtils.html#decode(java.lang.String,java.lang.String)), for example:
+
+```kotlin
+UriUtils.decode(u, StandardCharsets.UTF_8));
+```
+
+would return:
+
+```
+foo+++bar
+```
+
+Unfortunately, decoding with [Uri.decode](https://developer.android.com/reference/android/net/Uri#decode(java.lang.String)) on Android, [decodeURI](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURI) in Javascript, etc. would yield the exact same result.
+
+![URLEncoder](https://live.staticflickr.com/65535/52607534147_dee4a5a390_c.jpg)

lib/build.gradle.kts

@@ -13,7 +13,7 @@ plugins {
 }
 
 group = "com.uwyn"
-version = "1.2.0"
+version = "1.2.1-SNAPSHOT"
 
 val mavenName = "UrlEncoder"
 val javaMainClass = "$group.${rootProject.name}.$mavenName"