Add initRand() with seed based on time (#16953)

1 files changed, 35 insertions, 10 deletions

diff --git a/lib/pure/random.nim b/lib/pure/random.nim
index d599727c3..f03cae56a 100644
--- a/lib/pure/random.nim
+++ b/lib/pure/random.nim
@@ -566,6 +566,7 @@ proc initRand*(seed: int64): Rand =
   ## generator's state.
   ##
   ## See also:
+  ## * `initRand proc<#initRand>`_ that uses the current time
   ## * `randomize proc<#randomize,int64>`_ that accepts a seed for the default
   ##   random number generator
   ## * `randomize proc<#randomize>`_ that initializes the default random
@@ -589,8 +590,11 @@ proc randomize*(seed: int64) {.benign.} =
   ## the same results for that seed each time.
   ##
   ## See also:
-  ## * `initRand proc<#initRand,int64>`_
+  ## * `initRand proc<#initRand,int64>`_ that initializes a Rand state
+  ##   with a given seed
   ## * `randomize proc<#randomize>`_ that uses the current time instead
+  ## * `initRand proc<#initRand>`_ that initializes a Rand state using
+  ##   the current time
   runnableExamples:
     from times import getTime, toUnix, nanosecond
 
@@ -635,25 +639,46 @@ proc shuffle*[T](x: var openArray[T]) =
 
 when not defined(nimscript) and not defined(standalone):
   import times
+  
+  proc initRand(): Rand =
+    ## Initializes a new Rand state with a seed based on the current time.
+    ##
+    ## The resulting state is independent of the default random number generator's state.
+    ##
+    ## **Note:** Does not work for NimScript or the compile-time VM.
+    ##
+    ## See also:
+    ## * `initRand proc<#initRand,int64>`_ that accepts a seed for a new Rand state
+    ## * `randomize proc<#randomize>`_ that initializes the default random
+    ##   number generator using the current time
+    ## * `randomize proc<#randomize,int64>`_ that accepts a seed for the default
+    ##   random number generator
+    when defined(js):
+      let time = int64(times.epochTime() * 1000) and 0x7fff_ffff
+      result = initRand(time)
+    else:
+      let now = times.getTime()
+      result = initRand(convert(Seconds, Nanoseconds, now.toUnix) + now.nanosecond)
+  
+  since (1, 5, 1):
+    export initRand
 
   proc randomize*() {.benign.} =
-    ## Initializes the default random number generator with a value based on
+    ## Initializes the default random number generator with a seed based on
     ## the current time.
     ##
     ## This proc only needs to be called once, and it should be called before
     ## the first usage of procs from this module that use the default random
     ## number generator.
     ##
-    ## **Note:** Does not work for NimScript.
+    ## **Note:** Does not work for NimScript or the compile-time VM.
     ##
     ## See also:
     ## * `randomize proc<#randomize,int64>`_ that accepts a seed
-    ## * `initRand proc<#initRand,int64>`_
-    when defined(js):
-      let time = int64(times.epochTime() * 1000) and 0x7fff_ffff
-      randomize(time)
-    else:
-      let now = times.getTime()
-      randomize(convert(Seconds, Nanoseconds, now.toUnix) + now.nanosecond)
+    ## * `initRand proc<#initRand>`_ that initializes a Rand state using
+    ##   the current time
+    ## * `initRand proc<#initRand,int64>`_ that initializes a Rand state
+    ##   with a given seed
+    state = initRand()
 
 {.pop.}