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

Ruby 3.2.5p208 (2024-07-26 revision 31d0f1a2e7dbfb60731d1f05b868e1d578cda493)

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 192 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 199 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 1065 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 1295 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 1094 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 1137 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 1197 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 1776 of file random.c.