From 783a044cab6515bb05c049fe95fb41c98abb9770 Mon Sep 17 00:00:00 2001
From: "Erik C. Thauvin" <erik@thauvin.net>
Date: Thu, 5 Jan 2023 00:10:37 -0800
Subject: [PATCH] Added URLEncoder section

---
 README.md | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/README.md b/README.md
index c396fa6..2e7679d 100644
--- a/README.md
+++ b/README.md
@@ -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)