source

README

Random Number Generators Collection

This repository contains a collection of random number generators (RNGs) implemented in Go, designed to cater to a wide range of applications, from cryptographic operations to testing environments. Each RNG in the collection offers distinct features and performance characteristics, making it suitable for various use cases, including those requiring cryptographic security.

Generators

Crypto

• Description: Utilizes Go's crypto/rand package to provide cryptographically secure random numbers, suitable for security-sensitive applications.
• Usage:

  source := NewCryptoSource()
  number := source.Uint64()
  

JSF (Jenkins Small Fast)

• Description: An implementation of the Jenkins Small Fast hash function for efficient pseudo-random number generation, balancing speed and randomness quality for general use.
• Usage:

  source := NewJSFSource(seed)
  number := source.Uint64()
  

SFC (Simple Fast Counter)

• Description: Based on the Simple Fast Counter algorithm, this source offers rapid number generation with satisfactory randomness properties, ideal for simulations and non-cryptographic applications.
• Usage:

  source := NewSFCSource(seed)
  number := source.Uint64()
  

Dumb

• Description: A deterministic generator designed primarily for testing, providing predictable output for scenarios where consistent results are more beneficial than high-quality randomness.
• Usage:

  source := NewDumb(seed)
  number := source.Uint64()
  

Installation

To use these RNGs in your Go project, import the package as follows:

import "github.com/yourusername/randsource"

Replace yourusername with your GitHub username or organization name where the repository is hosted.

Usage

After importing the package, initialize the desired RNG with or without a seed (as applicable) and use the Uint64 method to generate random numbers. See the usage examples under each generator's description for more details.

Benchmarks

Performance benchmarks for each RNG are provided to help you choose the right generator for your application. These benchmarks cover various aspects, including speed and randomness quality.

For detailed benchmark results, see the Benchmarks file.

Contributing

We welcome contributions and suggestions! Please open an issue or submit a pull request with your improvements.

Documentation

Index

• type Crypto
  • func NewCrypto() *Crypto
  • func (s *Crypto) Uint64() uint64
• type Dumb
  • func NewDumb(seed uint64) *Dumb
  • func (d *Dumb) Seed(seed uint64)
  • func (d *Dumb) Uint64() uint64
• type JSF
  • func NewJSF(seed uint64) *JSF
  • func (jsf *JSF) Seed(seed uint64)
  • func (jsf *JSF) Uint64() uint64
• type SFC
  • func NewSFC(seed uint64) *SFC
  • func (s *SFC) Seed(seed uint64)
  • func (s *SFC) Uint64() uint64

Types

type Crypto

type Crypto struct {
	// contains filtered or unexported fields
}

func NewCrypto

func NewCrypto() *Crypto

NewCrypto creates a new instance of Crypto.

func (*Crypto) Uint64

func (s *Crypto) Uint64() uint64

Uint64 generates a pseudo-random 64-bit value using crypto/rand, served from a buffered block of data.

type Dumb

type Dumb struct {
	// contains filtered or unexported fields
}

Dumb is a simplistic generator for predictable testing.

func NewDumb

func NewDumb(seed uint64) *Dumb

NewDumb initializes a Dumb generator. If the seed is 0, initializes with the current timestamp.

func (*Dumb) Seed

func (d *Dumb) Seed(seed uint64)

Seed sets the generator's state. If the seed is 0, it uses the current timestamp as the seed.

func (*Dumb) Uint64

func (d *Dumb) Uint64() uint64

Uint64 returns the next number in the sequence, incrementing the state.

type JSF

type JSF struct {
	// contains filtered or unexported fields
}

func NewJSF

func NewJSF(seed uint64) *JSF

NewJSF creates and returns a new JSF pseudo-random number generator.

func (*JSF) Seed

func (jsf *JSF) Seed(seed uint64)

Seed sets the seed of the JSF with an improved seeding mechanism.

func (*JSF) Uint64

func (jsf *JSF) Uint64() uint64

Uint64 generates a pseudo-random 64-bit value using the improved JSF algorithm.

type SFC

type SFC struct {
	// contains filtered or unexported fields
}

func NewSFC

func NewSFC(seed uint64) *SFC

NewSFC creates and returns a new SFC pseudo-random number generator seeded with a given seed.

func (*SFC) Seed

func (s *SFC) Seed(seed uint64)

Seed sets the seed of the SFC. This implementation can be enhanced to provide a more distributed seeding process across the state variables.

func (*SFC) Uint64

func (s *SFC) Uint64() uint64

Uint64 generates a pseudo-random 64-bit value using the SFC algorithm.