Crate rhai_rand

rhai-rand - Rhai Functions for Random Number Generation

rhai-rand is a Rhai package to provide random number generation using the rand crate.

Usage

Cargo.toml

[dependencies]
rhai-rand = "0.1"

Rhai script

// Create random boolean
let decision = rand_bool();

if decision {
    // Create random number
    let random_value = rand();
    print(`Random number = ${random_value}`);
} else {
    print("Fixed number = 42");
}

// Create array
let a = [1, 2, 3, 4, 5];

// Shuffle it!
a.shuffle();

// Now the array is shuffled randomly!
print(a);

// Sample a random value from the array
print(a.sample());

// Or sample multiple values
print(a.sample(3));

Rust source

use rhai::Engine;
use rhai::packages::Package;

use rhai_rand::RandomPackage;

// Create Rhai scripting engine
let mut engine = Engine::new();

// Create random number package and add the package into the engine
engine.register_global_module(RandomPackage::new().as_shared_module());

// Print 10 random numbers, each of which between 0-100!
for _ in 0..10 {
    let value = engine.eval::<i64>("rand(0..=100)")?;

    println!("Random number = {}", value);
}

Features

• default — Default features: float and array.

• metadata — Includes functions metadata: parameter names/types, return type, doc-comments etc.

• float (enabled by default) — Provides random floating-point number generation.

• array (enabled by default) — Provides methods for Rhai arrays.

• decimal — Provides random decimal number generation.

API

The following functions are defined in this package:

rand

rand() -> i64

Generate a random integer number.

Example

let number = rand();

print(`I'll give you a random number: ${number}`);

rand(range: Range<i64>) -> i64

Generate a random integer number within an exclusive range.

Example

let number = rand(18..39);

print(`I'll give you a random number between 18 and 38: ${number}`);

rand(range: RangeInclusive<i64>) -> i64

Generate a random integer number within an inclusive range.

Example

let number = rand(18..=38);

print(`I'll give you a random number between 18 and 38: ${number}`);

rand(start: i64, end: i64) -> i64

Generate a random integer number within an inclusive range.

Example

let number = rand(18, 38);

print(`I'll give you a random number between 18 and 38: ${number}`);

rand_bool

rand_bool() -> bool

Generate a random boolean value.

Example

let decision = rand_bool();

if decision {
    print("You hit the Jackpot!")
}

rand_bool(probability: f64) -> bool

Generate a random boolean value with a probability of being true. Requires the float feature.

probability must be between 0.0 and 1.0 (inclusive).

Example

let decision = rand_bool(0.01);  // 1% probability

if decision {
    print("You hit the Jackpot!")
}

rand_decimal

rand_decimal() -> Decimal

Generate a random decimal number. Requires the decimal feature.

Example

let number = rand_decimal();

print(`I'll give you a random decimal number: ${number}`);

rand_decimal(start: Decimal, end: Decimal) -> Decimal

Generate a random decimal number within a range. Requires the decimal feature.

Example

let number = rand(18.to_decimal(), 38.to_decimal());

print(`I'll give you a random number between 18 and 38: ${number}`);

rand_float

rand_float() -> f64

Generate a random floating-point number between 0.0 and 1.0 (exclusive). Requires the float feature.

1.0 is excluded from the possibilities.

Example

let number = rand_float();

print(`I'll give you a random number between 0 and 1: ${number}`);

rand_float(start: f64, end: f64) -> f64

Generate a random floating-point number within an exclusive range. Requires the float feature.

Example

let number = rand_float(123.456, 789.678);

print(`I'll give you a random number between 123.456 and 789.678: ${number}`);

sample

sample(array: Array) -> Dynamic

Copy a random element from the array and return it. Requires the array feature.

Example

let x = [1, 2, 3, 4, 5];

let number = x.sample();

print(`I'll give you a random number between 1 and 5: ${number}`);

sample(array: Array, amount: i64) -> Array

Copy a non-repeating random sample of elements from the array and return it. Requires the array feature.

Elements in the return array are likely not in the same order as in the original array.

• If amount ≤ 0, the empty array is returned.
• If amount ≥ length of array, the entire array is returned, but shuffled.

Example

let x = [1, 2, 3, 4, 5];

let samples = x.sample(3);

print(`I'll give you 3 random numbers between 1 and 5: ${samples}`);

shuffle(array: Array)

Shuffle the elements in the array. Requires the array feature.

Example

let x = [1, 2, 3, 4, 5];

x.shuffle();    // shuffle the elements inside the array

Structs

• RandomPackage
  Package for random number generation, sampling and shuffling.