randomness

README

randomness

randomness provides a secure random integer generator, optionally retryable, and collision-free.

Install

$ go get github.com/saucelabs/randomness@vX.Y.Z

Usage

See example_test.go, and randomness_test.go file.

Documentation

Run $ make doc or check out online.

Development

Check out CONTRIBUTION.

Release

1. Update CHANGELOG accordingly.
2. Once changes from MR are merged.
3. Tag and release.

Roadmap

Check out CHANGELOG.

Documentation

Overview

Package Randomness provides a secure random integer generator, optionally retryable, and collision-free.

Examples:

See `example_test.go` or the Example section of the GoDoc documention.

Index

• Variables
• type Randomness
  • func New(min, max, maxRetry int, collisionFree bool) (*Randomness, error)
  • func (r *Randomness) Generate() (int64, error)
  • func (r *Randomness) GenerateMany(n int) ([]int64, error)
  • func (r *Randomness) MustGenerate() int64
  • func (r *Randomness) MustGenerateMany(n int) []int64

Examples

• New (Generate)
• New (Generate_collisionFree)
• New (Generate_collisionFreeError)
• New (Generate_collisionFreeMaxRetry)
• New (MustGenerate)
• New (RandomNumbers)

Variables

var (
	ErrFailedToGenerateRandomness      = customerror.NewFailedToError("to generate randomness", "", nil)
	ErrFailedToGenerateRangeSaturated  = customerror.NewFailedToError("to generate, range saturated", "", nil)
	ErrFailedToGenerateReachedMaxRetry = customerror.NewFailedToError("to generate, reached max retry", "", nil)
	ErrInvalidMax                      = customerror.NewInvalidError("params. `max` is less than 0", "", nil)
	ErrInvalidMin                      = customerror.NewInvalidError("params. `min` is less than 1", "", nil)
	ErrInvalidMinBiggerThanMax         = customerror.NewInvalidError("param. Min can't be bigger than max", "", nil)
)

Types

type Randomness

type Randomness struct {
	CollisionFree bool

	Max int
	Min int
	// contains filtered or unexported fields
}

func New

func New(min, max, maxRetry int, collisionFree bool) (*Randomness, error)

New is the Randomness factory.

Example (Generate)

Demonstrates how to generate a random number (integer).

r, err := New(1, 5, 0, false)
if err != nil {
	log.Fatalln(err)
}

n, err := r.Generate()
if err != nil {
	log.Fatalln(err)
}

fmt.Println(n < 1 && n > 5)

Output:

false

Example (Generate_collisionFree)

Demonstrates how to generate a random number (integer) - with the collision-free option, and no collision.

errMsgs := []error{}

r, err := New(1, 10, 0, true)
if err != nil {
	log.Fatalln(err)
}

for i := 0; i < 3; i++ {
	_, err := r.Generate()
	if err != nil {
		errMsgs = append(errMsgs, err)
	}
}

saturated := false

for _, err := range errMsgs {
	if errors.Is(err, ErrFailedToGenerateRangeSaturated) {
		saturated = true
	}
}

fmt.Println(saturated)

Output:

false

Example (Generate_collisionFreeError)

Demonstrates how to generate a random number (integer) - with the collision-free option, but causing collision.

errMsgs := []error{}

r, err := New(1, 3, 0, true)
if err != nil {
	log.Fatalln(err)
}

for i := 0; i < 10; i++ {
	_, err := r.Generate()
	if err != nil {
		errMsgs = append(errMsgs, err)
	}
}

saturated := false

for _, err := range errMsgs {
	if errors.Is(err, ErrFailedToGenerateRangeSaturated) {
		saturated = true
	}
}

fmt.Println(saturated)

Output:

true

Example (Generate_collisionFreeMaxRetry)

Demonstrates how to generate a random number (integer) - with the collision-free option, no collision, and with maxRetry.

errMsgs := []error{}

r, err := New(1, 10, 100, true)
if err != nil {
	log.Fatalln(err)
}

for i := 0; i < 10; i++ {
	_, err := r.Generate()
	if err != nil {
		errMsgs = append(errMsgs, err)
	}
}

saturated := false
reachedMaxRetries := false

for _, err := range errMsgs {
	if errors.Is(err, ErrFailedToGenerateRangeSaturated) {
		saturated = true
	}

	if errors.Is(err, ErrFailedToGenerateReachedMaxRetry) {
		reachedMaxRetries = true
	}
}

fmt.Println(saturated)
fmt.Println(reachedMaxRetries)

Output:

false
false

Example (MustGenerate)

Demonstrates how to generate a random number (integer).

r, err := New(18000, 50000, 0, false)
if err != nil {
	log.Fatalln(err)
}

control := false

for i := 0; i < 100000; i++ {
	n := r.MustGenerate()

	if (n < 18000 && n > 50000) == true {
		control = true
	}
}

fmt.Println(control)

Output:

false

Example (RandomNumbers)

Demonstrates how to generate N amount of random numbers.

r, err := New(18000, 50000, 100, true)
if err != nil {
	log.Fatalln(err)
}

numbers := r.MustGenerateMany(10)

fmt.Println(len(numbers) == 10)

Output:

true

func (*Randomness) Generate

func (r *Randomness) Generate() (int64, error)

Generate returns a random number.

func (*Randomness) GenerateMany

func (r *Randomness) GenerateMany(n int) ([]int64, error)

GenerateMany returns an slice of `n` numbers.

func (*Randomness) MustGenerate

func (r *Randomness) MustGenerate() int64

MustGenerate is like `RandomPortGenerator`, but will panic in case of any error.

func (*Randomness) MustGenerateMany

func (r *Randomness) MustGenerateMany(n int) []int64

MustGenerateMany is like `GenerateMany`, but will panic in case of any error.