Class Random

Namespace

Sdl3Sharp.Utilities

Assembly

Sdl3Sharp.dll

Provides methods to generate and seed pseudo-random numbers

public static class Random

Inheritance

object

Random

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Methods

Next(int)

Generates a pseudo-random integer number less than a specified positive integer

public static int Next(int n)

Parameters

n int

The number of possible outcomes. Should be positive.

Returns

int

A pseudo-random value in the range from inclusive 0 to inclusive n-1, if n is greater than 0; otherwise 0

Examples

// simulate a D6 dice throw ('+ 1' moves the output range from 0..5 to 1..6)
int d6 = Random.Next(6) + 1;

// generate a pseudo-random number in the full 32-bit integer range (int.MinValue..int.MaxValue)
// in contrast to Random.Next(int), this also generates negative values
int fullIntRange = unchecked((int)Random.NextBits());

Remarks

This method should be faster and of better quality than C's rand() % n. Odds are roughly 99.9% even for n = 1 million. Evenness is better for smaller n, and much worse as n gets bigger.

If you want to generate a pseudo-random number in the full 32-bit integer range, use NextBits() (see the examples given).

If you want reproducible output, be sure to initialize the pseudo-random number generator with a seed first (SetSeed(ulong)).

There are no guarantees as to the quality of the random sequence produced, and this should not be used for security (cryptography, passwords) or where money is on the line (loot-boxes, casinos). There are many alternatives with different characteristics available to meet more serious needs.

All calls to Next(int), NextBits(), NextFloat(), or SetSeed(ulong) (the "global" Random APIs) should be made from the same single thread.

Next(ref ulong, int)

Generates a pseudo-random integer number less than a specified positive integer

public static int Next(ref ulong state, int n)

Parameters

state ulong

The current random number generator state

n int

The number of possible outcomes. Should be positive.

Returns

int

A pseudo-random value in the range from inclusive 0 to inclusive n-1, if n is greater than 0; otherwise 0

Examples

// simulate a D6 dice throw ('+ 1' moves the output range from 0..5 to 1..6)
int d6 = Random.Next(ref state, 6) + 1;

// generate a pseudo-random number in the full 32-bit integer range (int.MinValue..int.MaxValue)
// in contrast to Random.Next(ref ulong, int), this also generates negative values
int fullIntRange = unchecked((int)Random.NextBits(ref state));

Remarks

Instead of using a shared "global" state like Next(int), you can use a "local" state here. This enables you to have multiple random number generates with different states at the same time.

This method should be faster and of better quality than C's rand() % n. Odds are roughly 99.9% even for n = 1 million. Evenness is better for smaller n, and much worse as n gets bigger.

If you want to generate a pseudo-random number in the full 32-bit integer range, use NextBits(ref ulong) (see the examples given).

There are no guarantees as to the quality of the random sequence produced, and this should not be used for security (cryptography, passwords) or where money is on the line (loot-boxes, casinos). There are many alternatives with different characteristics available to meet more serious needs.

This method is thread-safe, as long as the state used is only shared in a thread-safe manner and no parallel concurrent calls to either Next(ref ulong, int), NextBits(ref ulong), or NextFloat(ref ulong) are made.

NextBits()

Generates pseudo-random unsigned 32-bit integer

public static uint NextBits()

Returns

uint

A pseudo-random value in the range from inclusive MinValue to inclusive MaxValue

Remarks

This method generates 32 pseudo-random bits and returns them packed as an uint value.

If you want to generate a pseudo-random integer in a specified positive range, use Next(int) instead.

If you want reproducible output, be sure to initialize the pseudo-random number generator with a seed first (SetSeed(ulong)).

There are no guarantees as to the quality of the random sequence produced, and this should not be used for security (cryptography, passwords) or where money is on the line (loot-boxes, casinos). There are many alternatives with different characteristics available to meet more serious needs.

All calls to Next(int), NextBits(), NextFloat(), or SetSeed(ulong) (the "global" Random APIs) should be made from the same single thread.

NextBits(ref ulong)

Generates pseudo-random unsigned 32-bit integer

public static uint NextBits(ref ulong state)

Parameters

state ulong

The current random number generator state

Returns

uint

A pseudo-random value in the range from inclusive MinValue to inclusive MaxValue

Remarks

Instead of using a shared "global" state like NextBits(), you can use a "local" state here. This enables you to have multiple random number generates with different states at the same time.

This method generates 32 pseudo-random bits and returns them packed as an uint value.

If you want to generate a pseudo-random integer in a specified positive range, use Next(ref ulong, int) instead.

There are no guarantees as to the quality of the random sequence produced, and this should not be used for security (cryptography, passwords) or where money is on the line (loot-boxes, casinos). There are many alternatives with different characteristics available to meet more serious needs.

This method is thread-safe, as long as the state used is only shared in a thread-safe manner and no parallel concurrent calls to either Next(ref ulong, int), NextBits(ref ulong), or NextFloat(ref ulong) are made.

NextFloat()

Generates a uniform pseudo-random floating point number in the range from inclusive 0.0 to exclusive 1.0

public static float NextFloat()

Returns

float

A pseudo-random value in the range from inclusive 0.0 to exclusive 1.0

Remarks

If you want reproducible output, be sure to initialize the pseudo-random number generator with a seed first (SetSeed(ulong)).

There are no guarantees as to the quality of the random sequence produced, and this should not be used for security (cryptography, passwords) or where money is on the line (loot-boxes, casinos). There are many alternatives with different characteristics available to meet more serious needs.

All calls to Next(int), NextBits(), NextFloat(), or SetSeed(ulong) (the "global" Random APIs) should be made from the same single thread.

NextFloat(ref ulong)

Generates a uniform pseudo-random floating point number in the range from inclusive 0.0 to exclusive 1.0

public static float NextFloat(ref ulong state)

Parameters

state ulong

Returns

float

A pseudo-random value in the range from inclusive 0.0 to exclusive 1.0

Remarks

Instead of using a shared "global" state like NextFloat(), you can use a "local" state here. This enables you to have multiple random number generates with different states at the same time.

There are no guarantees as to the quality of the random sequence produced, and this should not be used for security (cryptography, passwords) or where money is on the line (loot-boxes, casinos). There are many alternatives with different characteristics available to meet more serious needs.

This method is thread-safe, as long as the state used is only shared in a thread-safe manner and no parallel concurrent calls to either Next(ref ulong, int), NextBits(ref ulong), or NextFloat(ref ulong) are made.

SetSeed(ulong)

Sets the seed of the pseudo-random number generator

public static void SetSeed(ulong seed)

Parameters

seed ulong

The value to use as a random number seed, or 0 to use PerformanceCounter instead

Remarks

Reusing the same value for the seed will cause Next(int), NextBits(), and NextFloat() to repeat the same stream of pseudo-random numbers.

All calls to Next(int), NextBits(), NextFloat(), or SetSeed(ulong) (the "global" Random APIs) should be made from the same single thread.