add and , rename to

Author: jfmontanaro

ci/expect_scripts/random.exp

@@ -7,9 +7,15 @@ set timeout 7
 
 source ./ci/expect_scripts/shared-code.exp
 
-spawn $env(EXAMPLES_DIR)random-seed
+spawn $env(EXAMPLES_DIR)random
 
-expect -re "Seed is: \\d+" {
+set expected_output [normalize_output "
+Random U64 is: \\\d+
+Random U32 is: \\\d+
+Random bytes are: \\\[\\\d+, \\\d+, \\\d+, \\\d+\\\]
+"]
+
+expect -re $expected_output {
     expect eof {
         check_exit_and_segfault
     }

crates/roc_host/src/lib.rs

@@ -349,7 +349,9 @@ pub fn init() {
         roc_fx_temp_dir as _,
         roc_fx_get_locale as _,
         roc_fx_get_locales as _,
-        roc_fx_random_seed as _,
+        roc_fx_random_u64 as _,
+        roc_fx_random_u32 as _,
+        roc_fx_random_bytes as _,
         roc_fx_sqlite_bind as _,
         roc_fx_sqlite_column_value as _,
         roc_fx_sqlite_columns as _,
@@ -811,8 +813,18 @@ pub extern "C" fn roc_fx_get_locales() -> RocList<RocStr> {
 }
 
 #[no_mangle]
-pub extern "C" fn roc_fx_random_seed() -> RocResult<u64, IOErr> {
-    roc_random::seed()
+pub extern "C" fn roc_fx_random_u64() -> RocResult<u64, IOErr> {
+    roc_random::random_u64()
+}
+
+#[no_mangle]
+pub extern "C" fn roc_fx_random_u32() -> RocResult<u32, IOErr> {
+    roc_random::random_u32()
+}
+
+#[no_mangle]
+pub extern "C" fn roc_fx_random_bytes(count: u64) -> RocResult<RocList<u8>, IOErr> {
+    roc_random::random_bytes(count)
 }
 
 #[no_mangle]

crates/roc_random/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "roc_random"
-description = "Common functionality for Roc to interface with rand"
+description = "Common functionality for Roc to interface with getrandom"
 authors.workspace = true
 edition.workspace = true
 license.workspace = true

crates/roc_random/src/lib.rs

@@ -1,10 +1,26 @@
-use roc_std::RocResult;
+use roc_std::{RocList, RocResult};
 use roc_io_error::IOErr;
 
 
-pub fn seed() -> RocResult<u64, IOErr> {
+pub fn random_u64() -> RocResult<u64, IOErr> {
     getrandom::u64()
         .map_err(|e| std::io::Error::from(e))
         .map_err(|e| IOErr::from(e))
         .into()
 }
+
+pub fn random_u32() -> RocResult<u32, IOErr> {
+    getrandom::u32()
+        .map_err(|e| std::io::Error::from(e))
+        .map_err(|e| IOErr::from(e))
+        .into()
+}
+
+pub fn random_bytes(count: u64) -> RocResult<RocList<u8>, IOErr> {
+    let mut buf = RocList::from_iter((0..count).map(|_| 0u8));
+    getrandom::fill(buf.as_mut_slice())
+        .map(|_| buf)
+        .map_err(|e| std::io::Error::from(e))
+        .map_err(|e| IOErr::from(e))
+        .into()
+}

examples/random-seed.roc

@@ -0,0 +1,20 @@
+app [main!] { pf: platform "../platform/main.roc" }
+
+# To run this example: check the README.md in this folder
+
+# Demo of basic-cli Random functions
+
+import pf.Stdout
+import pf.Random
+import pf.Arg exposing [Arg]
+
+main! : List Arg => Result {} _
+main! = |_args|
+    random_u64 = Random.random_u64!({})?
+    Stdout.line!("Random U64 is: ${Inspect.to_str(random_u64)}")?
+
+    random_u32 = Random.random_u32!({})?
+    Stdout.line!("Random U32 is: ${Inspect.to_str(random_u32)}")?
+
+    random_bytes = Random.random_bytes!(4)?
+    Stdout.line!("Random bytes are: ${Inspect.to_str(random_bytes)}")

examples/random.roc

@@ -33,7 +33,9 @@ hosted [
     hard_link!,
     path_type!,
     posix_time!,
-    random_seed!,
+    random_u64!,
+    random_u32!,
+    random_bytes!,
     send_request!,
     set_cwd!,
     sleep_millis!,
@@ -148,4 +150,6 @@ env_var! : Str => Result Str {}
 exe_path! : {} => Result (List U8) {}
 set_cwd! : List U8 => Result {} {}
 
-random_seed! : {} => Result U64 InternalIOErr.IOErrFromHost
+random_u64! : {} => Result U64 InternalIOErr.IOErrFromHost
+random_u32! : {} => Result U32 InternalIOErr.IOErrFromHost
+random_bytes! : U64 => Result (List U8) InternalIOErr.IOErrFromHost

platform/Host.roc

@@ -1,6 +1,8 @@
 module [
     IOErr,
-    seed!,
+    random_u64!,
+    random_u32!,
+    random_bytes!,
 ]
 
 import InternalIOErr
@@ -13,8 +15,45 @@ import Host
 IOErr : InternalIOErr.IOErr
 
 ## Generate a random U64 using the system's source of randomness.
-## This uses the Rust crate `getrandom`.
-seed! : {} => Result U64 [RandomErr IOErr]
-seed! = |{}|
-    Host.random_seed!({})
+##
+## This uses Rust's [getrandom](https://crates.io/crates/getrandom) crate to produce
+## a single random 64-bit integer. Note that this is a direct interface to the
+## system's source of randomness, meaning that each call introduces a significant
+## amount of overhead. If you need to generate a lot of random numbers, consider
+## calling this function once to generate a single "seed", then using a library
+## such as [roc-random](https://github.com/lukewilliamboswell/roc-random) to generate
+## additional random numbers.
+##
+## > Note that 64 bits is NOT considered sufficient randomness for cryptographic
+## applications such as encryption keys. Prefer using `random_bytes()` to generate
+## larger random values for security-sensitive applications.
+random_u64! : {} => Result U64 [RandomErr IOErr]
+random_u64! = |{}|
+    Host.random_u64!({})
+    |> Result.map_err(|err| RandomErr(InternalIOErr.handle_err(err)))
+
+## Generate a random U32 using the system's source of randomness.
+##
+## This uses Rust's [getrandom](https://crates.io/crates/getrandom) crate to produce
+## a single random 32-bit integer. Note that this is a direct interface to the
+## system's source of randomness, meaning that each call introduces a significant
+## amount of overhead. If you need to generate a lot of random numbers, consider
+## calling this function once to generate a single "seed", then using a library
+## such as [roc-random](https://github.com/lukewilliamboswell/roc-random) to generate
+## additional random numbers.
+##
+## > Note that 32 bits is NOT considered sufficient randomness for cryptographic
+## applications such as encryption keys. Prefer using `random_bytes()` to generate
+## larger random values for security-sensitive applications.
+random_u32! : {} => Result U32 [RandomErr IOErr]
+random_u32! = |{}|
+    Host.random_u32!({})
+    |> Result.map_err(|err| RandomErr(InternalIOErr.handle_err(err)))
+
+## Generate an arbitrary number of bytes using the system's source of randomness.
+## For additional details on the specific source of randomness used on various
+## platforms, see the Rust crate [getrandom](https://docs.rs/getrandom/0.3.3/getrandom/index.html).
+random_bytes! : U64 => Result (List U8) [RandomErr IOErr]
+random_bytes! = |count|
+    Host.random_bytes!(count)
     |> Result.map_err(|err| RandomErr(InternalIOErr.handle_err(err)))