Add Base64 safe

[juancarlospaco]

• base64 adds URL-Safe Base64, implements RFC-4648 Section-7.
• Allows to use Base64 on URL and file paths.
• Documentation with links and examples. Changelog. Test.

[Clyybber]

No advantage over just replacing those chars yourself IMO.
EDIT: To clarify: Just do .replace('+', '-').replace('/', '_')

[Araq]

Can we get some benchmark numbers? It's some overhead.

[juancarlospaco]

@Clyybber
You are iterating/processing/scanning 93240504396054 chars to change the last one at run-time.
Instead of just generating it properly as the RFC-4648 says, even more on slow target like JavaScript.
🙂

[timotheecour]

is if safe: cb64safe else: cb64 guaranteed to evaluate only once (here + in other overload) ?
the template will expand as:

while ...:
  result[outputIndex] = (if safe: cb64safe else: cb64)[x and 63]

instead, I'd simply not make that assumption and pass a constant to it

EDIT: my suspicion was correct, see comment below

[timotheecour]

Can we get some benchmark numbers? It's some overhead.

• current PR has exact same speed as with .replace('+', '-').replace('/', '_')
• with modification I hinted at [1], it gives a 4X speedup

nim c -r -d:case2 -d:case_workaround -d:danger $timn_D/tests/nim/all/t10369.nim
2.581079
nim c -r -d:case2 -d:case_safe -d:danger $timn_D/tests/nim/all/t10369.nim
0.6306889999999999

when defined case2:
  import base64
  import random
  import times
  import strutils
  proc main()=
    let n = 10000000
    let m = 100
    var s = newString(n)
    for i in 0..<n:
      s[i]=cast[char](rand(uint8.high.int))
    let t = cpuTime()
    for j in 0..<m:
      when defined case_safe:
        let s2 = encode(s, safe = true)
      elif defined case_workaround:
        let s2 = encode(s, safe = false).replace('+', '-').replace('/', '_')
        doAssert s2[^1] != '\0' # prevent optimize out
      else:
        static: doAssert false
    echo cpuTime()-t
    # echo s2
  main()

[1]

modified: lib/pure/base64.nim
@ lib/pure/base64.nim:160 @ proc encode*(s: string, safe = false): string =
  ## * `decode proc<#decode,string>`_ for decoding a string
  runnableExamples:
    assert encode("Hello World") == "SGVsbG8gV29ybGQ="
- encodeInternal(s, if safe: cb64safe else: cb64)
+ if safe: encodeInternal(s, cb64safe)
+ else: encodeInternal(s, cb64)

but I'd argue that, even with that 4X speedup, this PR would still be worth it because it implements a standard and we shouldn't let users re-invent the wheel

note:

the patch needs to be applied to the other encode overload as well

[timotheecour]

nit (doesn't have to be done in this PR): single ticks now works (simpler == better)