Ruby: include/ruby/internal/intern/random.h File Reference

Ruby 3.4.9p82 (2026-03-11 revision 76cca827ab52ab1d346a728f068d5b8da3e2952b)

Functions
random.h File Reference

MT19937 backended pseudo random number generator. More...

`#include "ruby/internal/dllexport.h"`
`#include "ruby/internal/value.h"`

Go to the source code of this file.

## Functions
unsigned int | rb_genrand_int32 (void)
| Generates a 32 bit random number.
double | rb_genrand_real (void)
| Generates a double random number.
void | rb_reset_random_seed (void)
| Resets the RNG behind rb_genrand_int32()/rb_genrand_real().
VALUE | rb_random_bytes (VALUE rnd, long n)
| Generates a String of random bytes.
unsigned int | rb_random_int32 (VALUE rnd)
| Identical to rb_genrand_int32(), except it generates using the passed RNG.
double | rb_random_real (VALUE rnd)
| Identical to rb_genrand_real(), except it generates using the passed RNG.
unsigned long | rb_random_ulong_limited (VALUE rnd, unsigned long limit)
| Identical to rb_genrand_ulong_limited(), except it generates using the passed RNG.
unsigned long | rb_genrand_ulong_limited (unsigned long i)
| Generates a random number whose upper limit is i.

## Detailed Description

MT19937 backended pseudo random number generator.

Author
  Ruby developers ruby-.nosp@m.core.nosp@m.@ruby.nosp@m.-lan.nosp@m.g.org

Copyright
  This file is a part of the programming language Ruby. Permission is hereby granted, to either redistribute and/or modify this file, provided that the conditions mentioned in the file COPYING are met. Consult the file for details.

Warning
  Symbols prefixed with either RBIMPL or rbimpl are implementation details. Don't take them as canon. They could rapidly appear then vanish. The name (path) of this header file is also an implementation detail. Do not expect it to persist at the place it is now. Developers are free to move it anywhere anytime at will.

Note
  To ruby-core: remember that this header can be possibly recursively included from extension libraries written in C++. Do not expect for instance __VA_ARGS__ is always available. We assume C99 for ruby itself but we don't assume languages of extension libraries. They could be written in C++98.

See also
  Matsumoto, M., Nishimura, T., "Mersenne Twister: A 623- dimensionally equidistributed uniform pseudorandom number generator", ACM Trans. on Modeling and Computer Simulation, 8 (1): pp 3-30, 1998. https://doi.org/10.1145/272991.272995

Definition in file random.h.

## Function Documentation

## ◆ rb_genrand_int32()

unsigned int rb_genrand_int32 | ( | void |  | ) |

Generates a 32 bit random number.

Returns
  A random number.

Note
  Now that we have ractors, the RNG behind this function is per-ractor.

Definition at line 199 of file random.c.

## ◆ rb_genrand_real()

double rb_genrand_real | ( | void |  | ) |

Generates a double random number.

Returns
  A random number.

Note
  This function shares the RNG with rb_genrand_int32().

Definition at line 206 of file random.c.

## ◆ rb_genrand_ulong_limited()

unsigned long rb_genrand_ulong_limited | ( | unsigned long | i | ) |

Generates a random number whose upper limit is i.

Parameters

  [in] | i | Max possible return value.

Returns
  A random number, uniformly distributed in [0, limit] interval.

Note
  Note it can return i.

Definition at line 1094 of file random.c.

## ◆ rb_random_bytes()

VALUE rb_random_bytes | ( | VALUE | rnd,
|  | long | n )

Generates a String of random bytes.

Parameters

  [in,out] | rnd | An instance of rb_cRandom.
  [in] | n | Requested number of bytes.

Returns
  An instance of rb_cString, of binary, of n bytes length, whose contents are random bits.

Definition at line 1324 of file random.c.

Referenced by rb_random_bytes().

## ◆ rb_random_int32()

unsigned int rb_random_int32 | ( | VALUE | rnd | ) |

Identical to rb_genrand_int32(), except it generates using the passed RNG.

Parameters

  [in,out] | rnd | An instance of rb_cRandom.

Returns
  A random number.

Definition at line 1123 of file random.c.

## ◆ rb_random_real()

double rb_random_real | ( | VALUE | rnd | ) |

Identical to rb_genrand_real(), except it generates using the passed RNG.

Parameters

  [in,out] | rnd | An instance of rb_cRandom.

Returns
  A random number.

Definition at line 1166 of file random.c.

## ◆ rb_random_ulong_limited()

unsigned long rb_random_ulong_limited | ( | VALUE | rnd,
|  | unsigned long | limit )

Identical to rb_genrand_ulong_limited(), except it generates using the passed RNG.

Parameters

  [in,out] | rnd | An instance of rb_cRandom.
  [in] | limit | Max possible return value.

Returns
  A random number, distributed in [0, limit] interval.

Note
  Note it can return limit.
  Whether the return value distributes uniformly in the interval or not depends on how the argument RNG behaves; at least in case of MT19937 it does.

Definition at line 1226 of file random.c.

Referenced by rb_random_ulong_limited().

## ◆ rb_reset_random_seed()

void rb_reset_random_seed | ( | void |  | ) |

Resets the RNG behind rb_genrand_int32()/rb_genrand_real().

Postcondition
  The (now per-ractor) default RNG's internal state is cleared.

Definition at line 1805 of file random.c.