Add `safe` parameter to `base64.encodeMime` (#20559)

* Improve `encodeMime` signature

* `string` to `openArray[char or byte]`
* `safe` parameter

* Fix

* Revert "Fix"

This reverts commit a394c505c2ab751621c24fd29b17e97c01251c1f.

* Remove encodeMime's openArray overload

* Document the `safe` parameter

* Add changelog entry

1 files changed, 11 insertions, 3 deletions

diff --git a/lib/pure/base64.nim b/lib/pure/base64.nim
index 8d19feda4..795820433 100644
--- a/lib/pure/base64.nim
+++ b/lib/pure/base64.nim
@@ -161,15 +161,23 @@ proc encode*[T: byte|char](s: openArray[T], safe = false): string =
     assert encode([1'u8, 2, 3, 4, 5]) == "AQIDBAU="
   encodeImpl()
 
-proc encode*[T: SomeInteger and not byte](s: openArray[T], safe = false): string {.deprecated: "use `byte` or `char` instead".} =
+proc encode*[T: SomeInteger and not byte](s: openArray[T], safe = false): string
+  {.deprecated: "use `byte` or `char` instead".} =
   encodeImpl()
 
-proc encodeMime*(s: string, lineLen = 75.Positive, newLine = "\r\n"): string =
+proc encodeMime*(s: string, lineLen = 75.Positive, newLine = "\r\n",
+                 safe = false): string =
   ## Encodes `s` into base64 representation as lines.
   ## Used in email MIME format, use `lineLen` and `newline`.
   ##
   ## This procedure encodes a string according to MIME spec.
   ##
+  ## If `safe` is `true` then it will encode using the
+  ## URL-Safe and Filesystem-safe standard alphabet characters,
+  ## which substitutes `-` instead of `+` and `_` instead of `/`.
+  ## * https://en.wikipedia.org/wiki/Base64#URL_applications
+  ## * https://tools.ietf.org/html/rfc4648#page-7
+  ##
   ## **See also:**
   ## * `encode proc<#encode,openArray[T]>`_ for encoding an openArray
   ## * `decode proc<#decode,string>`_ for decoding a string
@@ -183,7 +191,7 @@ proc encodeMime*(s: string, lineLen = 75.Positive, newLine = "\r\n"): string =
       inc idx
 
   if s.len == 0: return
-  let e = encode(s)
+  let e = encode(s, safe)
   if e.len <= lineLen or newLine.len == 0:
     return e
   result = newString(e.len + newLine.len * ((e.len div lineLen) - int(e.len mod lineLen == 0)))