Mah
DocsStdlibBlogChangelog
GitHub
Menu
DocsStdlibBlogChangelog GitHub

  • std:math
  • std:random
  • std:collections
  • std:time

  • std:path
  • std:json
  • std:csv
  • std:regex
  • std:bytes
  • std:url

  • std:async
  • std:fs
  • std:process
  • std:thread

  • std:socket
  • std:http

  • std:reflect
  • std:test

Standard library / Basics

std:random

Pseudo-random numbers: floats, whole numbers in a range, and picking, shuffling or sampling from a Vector. Every runtime uses the same generator (xoshiro256**), so a seeded program prints the same numbers on the Python VM and on mah-vm.

import random from "std:random"

let roll = random.randint(1, 6)                     # 1 to 6, both included
let coin = random.choice(["heads", "tails"])
print(roll >= 1 & roll <= 6, coin.len() >= 5)       # true true

Repeatable runs with seed

Without a seed the generator starts from the operating system’s randomness, so each run differs. Call seed(n) once at the start to make everything after it repeatable, which is what you want in tests and simulations:

import random from "std:random"

random.seed(42)
print(random.random())               # 0.08386297105988216316063699196
print(random.randint(1, 100))        # 3

Picking, shuffling, sampling

import random from "std:random"

random.seed(7)
let deck = ["A", "K", "Q", "J", "10"]
let hand = random.sample(deck, 2)          # 2 cards from different positions
print(hand.len(), hand[0] != hand[1])      # 2 true

let order = random.shuffled(deck)          # a new Vector; deck is unchanged
print(order.len(), deck[0])                # 5 A
random.shuffle(deck)                       # in place
print(deck.len())                          # 5

uniform(lo, hi) gives any Number in [lo, hi); randint(lo, hi) gives whole Numbers with both ends included, each equally likely.

Independent generators: Rng

The module-level functions share one generator. When one part of a program needs its own repeatable sequence (a level generator seeded from a level number, say) while the rest stays random, make a random.Rng:

import random from "std:random"

fn level_layout(level: Number) -> Vector<Number> {
    let rng = random.Rng.new(level)          # same level, same layout
    (0..4).map(fn(i) { rng.randint(0, 9) }).reduce()   # reduce() collects into a Vector
}
print(level_layout(3) == level_layout(3))    # false (Vectors compare by identity)
print(level_layout(3).join(",") == level_layout(3).join(","))   # true

Rng.new() with no seed starts from system randomness. An Rng has the same methods as the module: random, uniform, randint, choice, shuffle, shuffled and sample.

Errors and limits

Bad arguments, like choice([]), randint(5, 1) or sample(v, 99) on a shorter Vector, throw a RuntimeError.ArgumentError. A seed must be a whole Number below 2^64.

This generator is fast and statistically good, but it is not for cryptography: never use it for passwords, tokens or keys.

Reference

Function
seed(n)seeds the module’s generator
random()a Number in [0, 1), a multiple of 2^-53
uniform(lo, hi)a Number in [lo, hi)
randint(lo, hi)a whole Number from lo to hi, both included
choice(items)one item of a non-empty Vector
shuffle(items)puts the Vector in a random order, in place (Fisher-Yates)
shuffled(items)a new, shuffled Vector
sample(items, k)k items from different positions, in random order
Rng.new(seed = none)an independent generator with all of the above as methods
Previous std:math Next std:collections

Mah — ماه, "moon" in Persian. Built from scratch, pure Python (plus a Rust runtime).

Docs Stdlib Blog Changelog RSS GitHub