From 754bbf7a25a8dda49b5d08ef0d0443bbf5af0e36 Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Sun, 7 Apr 2024 13:41:34 -0500 Subject: new repository --- devdocs/go/math%2Frand%2Fv2%2Findex.html | 278 +++++++++++++++++++++++++++++++ 1 file changed, 278 insertions(+) create mode 100644 devdocs/go/math%2Frand%2Fv2%2Findex.html (limited to 'devdocs/go/math%2Frand%2Fv2%2Findex.html') diff --git a/devdocs/go/math%2Frand%2Fv2%2Findex.html b/devdocs/go/math%2Frand%2Fv2%2Findex.html new file mode 100644 index 00000000..79488bd9 --- /dev/null +++ b/devdocs/go/math%2Frand%2Fv2%2Findex.html @@ -0,0 +1,278 @@ +

Package rand

Overview

Package rand implements pseudo-random number generators suitable for tasks such as simulation, but it should not be used for security-sensitive work.

+

Random numbers are generated by a Source, usually wrapped in a Rand. Both types should be used by a single goroutine at a time: sharing among multiple goroutines requires some kind of synchronization.

+

Top-level functions, such as Float64 and Int, are safe for concurrent use by multiple goroutines.

+

This package's outputs might be easily predictable regardless of how it's seeded. For random numbers suitable for security-sensitive work, see the crypto/rand package.

Example +

Code:

+answers := []string{
+    "It is certain",
+    "It is decidedly so",
+    "Without a doubt",
+    "Yes definitely",
+    "You may rely on it",
+    "As I see it yes",
+    "Most likely",
+    "Outlook good",
+    "Yes",
+    "Signs point to yes",
+    "Reply hazy try again",
+    "Ask again later",
+    "Better not tell you now",
+    "Cannot predict now",
+    "Concentrate and ask again",
+    "Don't count on it",
+    "My reply is no",
+    "My sources say no",
+    "Outlook not so good",
+    "Very doubtful",
+}
+fmt.Println("Magic 8-Ball says:", answers[rand.IntN(len(answers))])
+

Example (Rand) +

This example shows the use of each of the methods on a *Rand. The use of the global functions is the same, without the receiver.

Code:

// Create and seed the generator.
+// Typically a non-fixed seed should be used, such as Uint64(), Uint64().
+// Using a fixed seed will produce the same output on every run.
+r := rand.New(rand.NewPCG(1, 2))
+
+// The tabwriter here helps us generate aligned output.
+w := tabwriter.NewWriter(os.Stdout, 1, 1, 1, ' ', 0)
+defer w.Flush()
+show := func(name string, v1, v2, v3 any) {
+    fmt.Fprintf(w, "%s\t%v\t%v\t%v\n", name, v1, v2, v3)
+}
+
+// Float32 and Float64 values are in [0, 1).
+show("Float32", r.Float32(), r.Float32(), r.Float32())
+show("Float64", r.Float64(), r.Float64(), r.Float64())
+
+// ExpFloat64 values have an average of 1 but decay exponentially.
+show("ExpFloat64", r.ExpFloat64(), r.ExpFloat64(), r.ExpFloat64())
+
+// NormFloat64 values have an average of 0 and a standard deviation of 1.
+show("NormFloat64", r.NormFloat64(), r.NormFloat64(), r.NormFloat64())
+
+// Int32, Int64, and Uint32 generate values of the given width.
+// The Int method (not shown) is like either Int32 or Int64
+// depending on the size of 'int'.
+show("Int32", r.Int32(), r.Int32(), r.Int32())
+show("Int64", r.Int64(), r.Int64(), r.Int64())
+show("Uint32", r.Uint32(), r.Uint32(), r.Uint32())
+
+// IntN, Int32N, and Int64N limit their output to be < n.
+// They do so more carefully than using r.Int()%n.
+show("IntN(10)", r.IntN(10), r.IntN(10), r.IntN(10))
+show("Int32N(10)", r.Int32N(10), r.Int32N(10), r.Int32N(10))
+show("Int64N(10)", r.Int64N(10), r.Int64N(10), r.Int64N(10))
+
+// Perm generates a random permutation of the numbers [0, n).
+show("Perm", r.Perm(5), r.Perm(5), r.Perm(5))
+

Output:

Float32     0.95955694          0.8076733            0.8135684
+Float64     0.4297927436037299  0.797802349388613    0.3883664855410056
+ExpFloat64  0.43463410545541104 0.5513632046504593   0.7426404617374481
+NormFloat64 -0.9303318111676635 -0.04750789419852852 0.22248301107582735
+Int32       2020777787          260808523            851126509
+Int64       5231057920893523323 4257872588489500903  158397175702351138
+Uint32      314478343           1418758728           208955345
+IntN(10)    6                   2                    0
+Int32N(10)  3                   7                    7
+Int64N(10)  8                   9                    4
+Perm        [0 3 1 4 2]         [4 1 2 0 3]          [4 3 2 0 1]
+

Index

Examples

Package
IntN
N
Perm
Shuffle
Shuffle (SlicesInUnison)
Package (Rand)

Package files

chacha8.go exp.go normal.go pcg.go rand.go zipf.go

func ExpFloat64 1.22 

func ExpFloat64() float64

ExpFloat64 returns an exponentially distributed float64 in the range (0, +math.MaxFloat64] with an exponential distribution whose rate parameter (lambda) is 1 and whose mean is 1/lambda (1) from the default Source. To produce a distribution with a different rate parameter, callers can adjust the output using:

+
sample = ExpFloat64() / desiredRateParameter
+

func Float32 1.22 

func Float32() float32

Float32 returns, as a float32, a pseudo-random number in the half-open interval [0.0,1.0) from the default Source.

+

func Float64 1.22 

func Float64() float64

Float64 returns, as a float64, a pseudo-random number in the half-open interval [0.0,1.0) from the default Source.

+

func Int 1.22 

func Int() int

Int returns a non-negative pseudo-random int from the default Source.

+

func Int32 1.22 

func Int32() int32

Int32 returns a non-negative pseudo-random 31-bit integer as an int32 from the default Source.

+

func Int32N 1.22 

func Int32N(n int32) int32

Int32N returns, as an int32, a pseudo-random number in the half-open interval [0,n) from the default Source. It panics if n <= 0.

+

func Int64 1.22 

func Int64() int64

Int64 returns a non-negative pseudo-random 63-bit integer as an int64 from the default Source.

+

func Int64N 1.22 

func Int64N(n int64) int64

Int64N returns, as an int64, a pseudo-random number in the half-open interval [0,n) from the default Source. It panics if n <= 0.

+

func IntN 1.22 

func IntN(n int) int

IntN returns, as an int, a pseudo-random number in the half-open interval [0,n) from the default Source. It panics if n <= 0.

Example +

Code:

+fmt.Println(rand.IntN(100))
+fmt.Println(rand.IntN(100))
+fmt.Println(rand.IntN(100))
+

func N 

func N[Int intType](n Int) Int

N returns a pseudo-random number in the half-open interval [0,n) from the default Source. The type parameter Int can be any integer type. It panics if n <= 0.

Example +

Code:

+// Print an int64 in the half-open interval [0, 100).
+fmt.Println(rand.N(int64(100)))
+
+// Sleep for a random duration between 0 and 100 milliseconds.
+time.Sleep(rand.N(100 * time.Millisecond))
+

func NormFloat64 1.22 

func NormFloat64() float64

NormFloat64 returns a normally distributed float64 in the range [-math.MaxFloat64, +math.MaxFloat64] with standard normal distribution (mean = 0, stddev = 1) from the default Source. To produce a different normal distribution, callers can adjust the output using:

+
sample = NormFloat64() * desiredStdDev + desiredMean
+

func Perm 1.22 

func Perm(n int) []int

Perm returns, as a slice of n ints, a pseudo-random permutation of the integers in the half-open interval [0,n) from the default Source.

Example +

Code:

for _, value := range rand.Perm(3) {
+    fmt.Println(value)
+}
+
+

Output:

1
+2
+0
+

func Shuffle 1.22 

func Shuffle(n int, swap func(i, j int))

Shuffle pseudo-randomizes the order of elements using the default Source. n is the number of elements. Shuffle panics if n < 0. swap swaps the elements with indexes i and j.

Example +

Code:

+words := strings.Fields("ink runs from the corners of my mouth")
+rand.Shuffle(len(words), func(i, j int) {
+    words[i], words[j] = words[j], words[i]
+})
+fmt.Println(words)
+

Example (SlicesInUnison) +

Code:

+numbers := []byte("12345")
+letters := []byte("ABCDE")
+// Shuffle numbers, swapping corresponding entries in letters at the same time.
+rand.Shuffle(len(numbers), func(i, j int) {
+    numbers[i], numbers[j] = numbers[j], numbers[i]
+    letters[i], letters[j] = letters[j], letters[i]
+})
+for i := range numbers {
+    fmt.Printf("%c: %c\n", letters[i], numbers[i])
+}
+

func Uint32 1.22 

func Uint32() uint32

Uint32 returns a pseudo-random 32-bit value as a uint32 from the default Source.

+

func Uint32N 1.22 

func Uint32N(n uint32) uint32

Uint32N returns, as a uint32, a pseudo-random number in the half-open interval [0,n) from the default Source. It panics if n <= 0.

+

func Uint64 1.22 

func Uint64() uint64

Uint64 returns a pseudo-random 64-bit value as a uint64 from the default Source.

+

func Uint64N 1.22 

func Uint64N(n uint64) uint64

Uint64N returns, as a uint64, a pseudo-random number in the half-open interval [0,n) from the default Source. It panics if n <= 0.

+

func UintN 1.22 

func UintN(n uint) uint

UintN returns, as a uint, a pseudo-random number in the half-open interval [0,n) from the default Source. It panics if n <= 0.

+

type ChaCha8 1.22

A ChaCha8 is a ChaCha8-based cryptographically strong random number generator.

+
type ChaCha8 struct {
+    // contains filtered or unexported fields
+}
+

func NewChaCha8 1.22 

func NewChaCha8(seed [32]byte) *ChaCha8

NewChaCha8 returns a new ChaCha8 seeded with the given seed.

+

func (*ChaCha8) MarshalBinary 1.22 

func (c *ChaCha8) MarshalBinary() ([]byte, error)

MarshalBinary implements the encoding.BinaryMarshaler interface.

+

func (*ChaCha8) Seed 1.22 

func (c *ChaCha8) Seed(seed [32]byte)

Seed resets the ChaCha8 to behave the same way as NewChaCha8(seed).

+

func (*ChaCha8) Uint64 1.22 

func (c *ChaCha8) Uint64() uint64

Uint64 returns a uniformly distributed random uint64 value.

+

func (*ChaCha8) UnmarshalBinary 1.22 

func (c *ChaCha8) UnmarshalBinary(data []byte) error

UnmarshalBinary implements the encoding.BinaryUnmarshaler interface.

+

type PCG 1.22

A PCG is a PCG generator with 128 bits of internal state. A zero PCG is equivalent to NewPCG(0, 0).

+
type PCG struct {
+    // contains filtered or unexported fields
+}
+

func NewPCG 1.22 

func NewPCG(seed1, seed2 uint64) *PCG

NewPCG returns a new PCG seeded with the given values.

+

func (*PCG) MarshalBinary 1.22 

func (p *PCG) MarshalBinary() ([]byte, error)

MarshalBinary implements the encoding.BinaryMarshaler interface.

+

func (*PCG) Seed 1.22 

func (p *PCG) Seed(seed1, seed2 uint64)

Seed resets the PCG to behave the same way as NewPCG(seed1, seed2).

+

func (*PCG) Uint64 1.22 

func (p *PCG) Uint64() uint64

Uint64 return a uniformly-distributed random uint64 value.

+

func (*PCG) UnmarshalBinary 1.22 

func (p *PCG) UnmarshalBinary(data []byte) error

UnmarshalBinary implements the encoding.BinaryUnmarshaler interface.

+

type Rand 1.22

A Rand is a source of random numbers.

+
type Rand struct {
+    // contains filtered or unexported fields
+}
+

func New 1.22 

func New(src Source) *Rand

New returns a new Rand that uses random values from src to generate other random values.

+

func (*Rand) ExpFloat64 1.22 

func (r *Rand) ExpFloat64() float64

ExpFloat64 returns an exponentially distributed float64 in the range (0, +math.MaxFloat64] with an exponential distribution whose rate parameter (lambda) is 1 and whose mean is 1/lambda (1). To produce a distribution with a different rate parameter, callers can adjust the output using:

+
sample = ExpFloat64() / desiredRateParameter
+

func (*Rand) Float32 1.22 

func (r *Rand) Float32() float32

Float32 returns, as a float32, a pseudo-random number in the half-open interval [0.0,1.0).

+

func (*Rand) Float64 1.22 

func (r *Rand) Float64() float64

Float64 returns, as a float64, a pseudo-random number in the half-open interval [0.0,1.0).

+

func (*Rand) Int 1.22 

func (r *Rand) Int() int

Int returns a non-negative pseudo-random int.

+

func (*Rand) Int32 1.22 

func (r *Rand) Int32() int32

Int32 returns a non-negative pseudo-random 31-bit integer as an int32.

+

func (*Rand) Int32N 1.22 

func (r *Rand) Int32N(n int32) int32

Int32N returns, as an int32, a non-negative pseudo-random number in the half-open interval [0,n). It panics if n <= 0.

+

func (*Rand) Int64 1.22 

func (r *Rand) Int64() int64

Int64 returns a non-negative pseudo-random 63-bit integer as an int64.

+

func (*Rand) Int64N 1.22 

func (r *Rand) Int64N(n int64) int64

Int64N returns, as an int64, a non-negative pseudo-random number in the half-open interval [0,n). It panics if n <= 0.

+

func (*Rand) IntN 1.22 

func (r *Rand) IntN(n int) int

IntN returns, as an int, a non-negative pseudo-random number in the half-open interval [0,n). It panics if n <= 0.

+

func (*Rand) NormFloat64 1.22 

func (r *Rand) NormFloat64() float64

NormFloat64 returns a normally distributed float64 in the range -math.MaxFloat64 through +math.MaxFloat64 inclusive, with standard normal distribution (mean = 0, stddev = 1). To produce a different normal distribution, callers can adjust the output using:

+
sample = NormFloat64() * desiredStdDev + desiredMean
+

func (*Rand) Perm 1.22 

func (r *Rand) Perm(n int) []int

Perm returns, as a slice of n ints, a pseudo-random permutation of the integers in the half-open interval [0,n).

+

func (*Rand) Shuffle 1.22 

func (r *Rand) Shuffle(n int, swap func(i, j int))

Shuffle pseudo-randomizes the order of elements. n is the number of elements. Shuffle panics if n < 0. swap swaps the elements with indexes i and j.

+

func (*Rand) Uint32 1.22 

func (r *Rand) Uint32() uint32

Uint32 returns a pseudo-random 32-bit value as a uint32.

+

func (*Rand) Uint32N 1.22 

func (r *Rand) Uint32N(n uint32) uint32

Uint32N returns, as a uint32, a non-negative pseudo-random number in the half-open interval [0,n). It panics if n == 0.

+

func (*Rand) Uint64 1.22 

func (r *Rand) Uint64() uint64

Uint64 returns a pseudo-random 64-bit value as a uint64.

+

func (*Rand) Uint64N 1.22 

func (r *Rand) Uint64N(n uint64) uint64

Uint64N returns, as a uint64, a non-negative pseudo-random number in the half-open interval [0,n). It panics if n == 0.

+

func (*Rand) UintN 1.22 

func (r *Rand) UintN(n uint) uint

UintN returns, as a uint, a non-negative pseudo-random number in the half-open interval [0,n). It panics if n == 0.

+

type Source 1.22

A Source is a source of uniformly-distributed pseudo-random uint64 values in the range [0, 1<<64).

+

A Source is not safe for concurrent use by multiple goroutines.

+
type Source interface {
+    Uint64() uint64
+}

type Zipf 1.22

A Zipf generates Zipf distributed variates.

+
type Zipf struct {
+    // contains filtered or unexported fields
+}
+

func NewZipf 1.22 

func NewZipf(r *Rand, s float64, v float64, imax uint64) *Zipf

NewZipf returns a Zipf variate generator. The generator generates values k ∈ [0, imax] such that P(k) is proportional to (v + k) ** (-s). Requirements: s > 1 and v >= 1.

+

func (*Zipf) Uint64 1.22 

func (z *Zipf) Uint64() uint64

Uint64 returns a value drawn from the Zipf distribution described by the Zipf object.

+

+ © Google, Inc.
Licensed under the Creative Commons Attribution License 3.0.
+ http://golang.org/pkg/math/rand/v2/ +

+
-- cgit v1.2.3