Documentation / Core packages / Core random

Core random

@core/random provides bounded random Float and Int values. The package keeps randomness explicit through dependency clauses rather than adding a global language primitive.

Random helpers

@core/random gives you random number helpers. Bind it when you need random Float or Int values.

Binding

Bind the functions you need with a direct-selection clause.

@core/random random_float, random_int

value = random_float()
die_roll = random_int(1, 6)

io.line([:roll=[die_roll] value=[value]])

Available functions

  • random_float() returns a Float between 0.0 and 1.0
  • random_int(min, max) returns an Int from min to max inclusive

If min exceeds max in random_int, the bounds swap. For the full function contract, backend behaviour and deferred surfaces, see Core random advanced.

@core/random provides random number helpers. It belongs to the binding-backed Core package family with no prelude alias, so it requires an explicit dependency clause.

@core/random carries Core origin with ExternalBinding backing. See Package origins and backing for origin and backing rules.

Dependency roots

Bind individual symbols or the whole namespace:

@core/random random_float, random_int

@core/random

value = random.random_float()
die_roll = random.random_int(1, 6)

Functions

Function

Parameters

Returns

random_float()

none

Float

random_int(min, max)

Int, Int

Int

random_float() returns a Float in the range 0.0 through 1.0 exclusive.

random_int(min, max) returns an Int in the inclusive range from min to max. If min exceeds max, the bounds swap.

Both functions stay infallible at the Moth level. They do not return through Error!.

Access and return contracts

All parameters use shared access. No function requires mutable access. Both functions return fresh values.

Backend behaviour

HTML-JS lowers random_float to Math.random(). random_int lowers to a JavaScript runtime helper that handles the inclusive range and bound swapping.

HTML-Wasm lacks a Wasm lowering for these functions. See progress matrix for current target availability.

Unsupported source forms

  • Direct symbol-path clauses face rejection. Use direct selections or a namespace clause.
  • Named arguments lack support. Binding-backed calls stay positional-only.
  • The package does not expose receiver methods, opaque types, constants or Error! channels.

Deferred surfaces

Seeded random and non-JS lowerings remain deferred. See progress matrix for current status.

Related concepts