1. About rng

rng is an implementation of several well-known pseudo-random number generators which have far better characteristics than Java's built-in generator. rng can be used for simulations, games (dice rolling, shuffling of playing cards etc.) or for any other application where security is not paramount. Specifically, it should never be used for cryptographically secure applications.

2. Features

Within rng you'll find the following generators (in alphabetical order):

• Complementary multiply with carry (CMWC)
• Mersenne Twister 19937
• R250
• R250/521
• Xorshift Plus

All implemented generators share the same interface which makes them totally interchangeable - if you start using one of them but then want to switch to another, you'll have to change only one line of code.

3. Installation

The easiest and recommended way to install rng is via your favorite build tool (i.e. Maven or Gradle):

<dependency>
    <groupId>org.thejavaguy</groupId>
    <artifactId>rng</artifactId>
    <version>0.2.0</version>
</dependency>

compile group: 'org.thejavaguy', name: 'rng', version: '0.2.0'

If you want to build the jar files (with code, javadoc and sources) yourself, you can do that easily:

$ git clone [email protected]:TheJavaGuy/rng.git
$ cd rng/
$ mvn clean package -Prng
$ ls -alF target | grep rng

4. Usage examples

Using any of the generators is super easy. You just need to create a generator object and then request a random number in the range you need.

4.1 Instantiating a generator

Before obtaining pseudo-random numbers, you have to create a generator object:

PRNG.Smart generator = new MersenneTwister.Smart(new MersenneTwister());

In a similar way you would instantiate an object for some other generator, e.g.

PRNG.Smart generator = new XorshiftPlus.Smart(new XorshiftPlus());

4.2 Generating an integer in given range

This is probably the most common operation with the generator. To generate an integer you always have to specify a range (i.e. lower and upper bound of a number):

IntRange sixSidedDie = new IntRange(1, 6);
int dots = generator.nextInt(sixSidedDie);

This may look a bit verbose, but actually makes your code's intention very explicit. IntRange class is constant (immutable) so you can share its instances freely.

4.3 Generating a double in range [0,1)

double number = generator.nextDouble();

4.4 Generating various primitive values

It's super easy to generate boolean, byte, short and char values too:

boolean coinToss = generator.nextBoolean();
byte colorIndex = generator.nextByte();
short tetrisScore = generator.nextShort();
char letter = generator.nextChar();

5. How to contribute

Additional generators can be easily added. There is only one requirement: every generator must implement the PRNG interface. This interface has only one method int nextInt(); which must return integer in the whole range, i.e. [Integer.MIN_VALUE, Integer.MAX_VALUE]. And that's it! All the heavy lifting afterwards is done automatically by the PRNG.Smart class. If you know how to implement some other generator or believe there's a bug somewhere, please fork the project, change/add what you want and make a pull request.

6. License

rng is licensed under GPLv3 license.

7. Credits for previous work

I would like to say a big thank you to the following people - authors of generators implemented in rng project:

• Complementary multiply with carry (CMWC) George Marsaglia
• Mersenne Twister 19937 Makoto Matsumoto and Takuji Nishimura
• R250 Scott Kirkpatrick and Erich Stoll
• R250/521 Scott Kirkpatrick and Erich Stoll
• Xorshift Plus George Marsaglia

8. How to contact author

If you have a question or issue with rng itself please use Issues link. If you want to talk about anything else, I'm @_The_Java_Guy_ on Twitter.