Add random.sampleBuffer

changelog.md

@@ -124,6 +124,10 @@ with other backends. see #9125. Use `-d:nimLegacyJsRound` for previous behavior.
   (instead of skipping them sometimes as it was before).
 - Added optional `followSymlinks` argument to `setFilePermissions`.
 
+- Added `random.sampleBuffer` to in-place populate a `buffer` with random samples from `alphabet` arguments.
+  Can be used to generate random ASCII URL-Safe strings of specified length and chars.
+
+
 ## Language changes
 
 - `nimscript` now handles `except Exception as e`.

lib/pure/random.nim

@@ -656,4 +656,19 @@ when not defined(nimscript) and not defined(standalone):
       let now = times.getTime()
       randomize(convert(Seconds, Nanoseconds, now.toUnix) + now.nanosecond)
 
+proc sampleBuffer*[T](r: var Rand, buffer: var openArray[T]; alphabet: set[T]) {.inline, since: (1, 5).} =
+  ## Populates `buffer` with random samples from `alphabet`.
+  ## Can be used to generate random ASCII URL-Safe strings of specified length and chars.
+  # Inspired but not copied from Python 3.10 "secrets.token_urlsafe()".
+  runnableExamples:
+    import std/[sugar, strutils]  ## sugar.dup, strutils.UrlSafeChars
+    var r = initRand(666)
+    var token = "12345678"               ## Length is 8.
+    sampleBuffer(r, token, UrlSafeChars) ## Use sugar.dup for out-place.
+    doAssert token != "12345678" and token.len == 8  ## Random ASCII URL-Safe string.
+    doAssert newString(8).dup(sampleBuffer(r, _, {'0'..'9'})).len == 8
+    doAssert newString(8).dup(sampleBuffer(r, _, UrlSafeChars)).len == 8
+  for c in buffer.mitems: c = sample(r, alphabet)
+
+
 {.pop.}

lib/pure/strutils.nim

@@ -120,6 +120,9 @@ const
     ##   doAssert "01234".find(invalid) == -1
     ##   doAssert "01A34".find(invalid) == 2
 
+  UrlSafeChars* = {'A'..'Z', 'a'..'z', '0'..'9', '-', '_'}
+    ## ASCII URL-Safe `char` alphabet representation, compatible with Base64 URL-Safe.
+
 func isAlphaAscii*(c: char): bool {.rtl, extern: "nsuIsAlphaAsciiChar".} =
   ## Checks whether or not character `c` is alphabetical.
   ##