From 1da595e08aa285be4c33ca8302ee81d4baf918f9 Mon Sep 17 00:00:00 2001
From: "Erik C. Thauvin" <erik@thauvin.net>
Date: Wed, 4 Jan 2023 23:55:18 -0800
Subject: [PATCH] Added URLEncoder section

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

diff --git a/README.md b/README.md
index 5789af4..5556bf6 100644
--- a/README.md
+++ b/README.md
@@ -102,3 +102,36 @@ java -jar lib/build/libs/urlencoder-*all.jar "%#okékÉȢ"          # -> %25%23o
 
 java -jar lib/build/libs/urlencoder-*.all.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
+val u = URLEncoder.encode("foo +bar", StandardCharsets.UTF_8)
+```
+
+would be encoded as:
+
+```
+foo+%28bar
+```
+
+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)
+