rand/v2

10 分钟阅读

原文：https://pkg.go.dev/math/rand/v2@go1.23.0

注意
从go1.22.0开始才可以使用该包。

Overview

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

rand 包实现了适合于模拟等任务的伪随机数生成器，但不应在对安全性敏感的工作中使用。

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.

随机数由 Source 生成，通常会被包装在 Rand 中。这两种类型应该由单个 goroutine 使用：在多个 goroutine 之间共享需要某种同步机制。

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

顶级函数，例如 Float64 和 Int，是线程安全的，可以被多个 goroutine 并发使用。

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.

此包的输出可能很容易预测，无论其种子如何设置。对于适合安全敏感工作的随机数，请参见 crypto/rand 包。

Example

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.

此示例展示了如何使用 *Rand 上的每个方法。使用全局函数的方式相同，没有接收者。

// 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.
// 创建并设置生成器的种子。
// 通常应使用非固定的种子，例如 Uint64(), Uint64()。
// 使用固定种子会在每次运行时产生相同的输出。
r := rand.New(rand.NewPCG(1, 2))

// The tabwriter here helps us generate aligned output.
// Float32 和 Float64 的值在 [0, 1) 范围内。
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).
// Float32 和 Float64 的值在 [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.
// ExpFloat64 值的平均值为 1，但呈指数衰减。
show("ExpFloat64", r.ExpFloat64(), r.ExpFloat64(), r.ExpFloat64())

// NormFloat64 values have an average of 0 and a standard deviation of 1.
// NormFloat64 值的平均值为 0，标准差为 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'.
// Int32、Int64 和 Uint32 生成给定宽度的值。
// Int 方法（未显示）类似于 Int32 或 Int64，
// 取决于 '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.
// IntN、Int32N 和 Int64N 将它们的输出限制为 < n。
// 它们比使用 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).
// Perm 生成 [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]

常量

This section is empty.

变量

This section is empty.

函数

func ExpFloat64

1
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:

ExpFloat64 返回一个范围在 (0, +math.MaxFloat64] 内的指数分布 float64，具有指数分布的速率参数（lambda）为 1，均值为 1/lambda（1），来自默认的 Source。要生成具有不同速率参数的分布，调用者可以使用以下方法调整输出：

sample = ExpFloat64() / desiredRateParameter

func Float32

1
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.

Float32 返回一个范围在 [0.0,1.0) 内的伪随机数，以 float32 类型，来自默认的 Source。

func Float64

1
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.

Float64 返回一个范围在 [0.0,1.0) 内的伪随机数，以 float64 类型，来自默认的 Source。

func Int

1
func Int() int

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

Int 返回一个非负的伪随机 int，来自默认的 Source。

func Int32

1
func Int32() int32

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

Int32 返回一个非负的伪随机 31 位整数，以 int32 类型，来自默认的 Source。

func Int32N

1
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.

Int32N 返回一个范围在 [0,n) 内的伪随机数，以 int32 类型，来自默认的 Source。如果 n <= 0，会引发恐慌。

func Int64

1
func Int64() int64

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

Int64 返回一个非负的伪随机 63 位整数，以 int64 类型，来自默认的 Source。

func Int64N

1
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.

Int64N 返回一个范围在 [0,n) 内的伪随机数，以 int64 类型，来自默认的 Source。如果 n <= 0，会引发恐慌。

func IntN

1
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.

IntN 返回一个伪随机数，该数位于半开区间 [0, n) 内。若 n <= 0，则会引发恐慌。

Example IntN

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

Output:

func N

1
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.

N 返回一个伪随机数，该数位于半开区间 [0, n) 内。类型参数 Int 可以是任何整数类型。若 n <= 0，则会引发恐慌。

Example N

1
2
3
4
5
6
7
8
9
// Print an int64 in the half-open interval [0, 100).
// 打印一个位于半开区间 [0, 100) 内的 int64。
fmt.Println(rand.N(int64(100)))

// Sleep for a random duration between 0 and 100 milliseconds.
// 睡眠一个在 0 到 100 毫秒之间的随机时间。
time.Sleep(rand.N(100 * time.Millisecond))

Output:

func NormFloat64

1
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:

NormFloat64 返回一个标准正态分布的 float64，范围在 [-math.MaxFloat64, +math.MaxFloat64] 之间，标准正态分布（均值 = 0，标准差 = 1）。要生成不同的正态分布，调用者可以调整输出值：

sample = NormFloat64() * desiredStdDev + desiredMean

func Perm

1
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.

Perm 返回一个包含 n 个整数的切片，生成从半开区间 [0, n) 内的伪随机排列。

Example Perm

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

1
2
0

func Shuffle

1
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.

Shuffle 使用默认的随机源对元素的顺序进行伪随机化。n 是元素的数量。若 n < 0，则会引发恐慌。swap 用于交换索引为 i 和 j 的元素。

Example Shuffle

1
2
3
4
5
6
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)
Output:

Example Shuffle (SlicesInUnison)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
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])
}
Output:

func Uint <- go1.23.0

1
func Uint() uint

Uint returns a pseudo-random uint from the default Source.

Uint 返回一个伪随机 uint 值。

func Uint32

1
func Uint32() uint32

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

Uint32 返回一个伪随机的 32 位值，类型为 uint32。

func Uint32N

1
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.

Uint32N 返回一个伪随机数，该数位于半开区间 [0, n) 内，类型为 uint32。若 n <= 0，则会引发恐慌。

func Uint64

1
func Uint64() uint64

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

Uint64 返回一个伪随机的 64 位值，类型为 uint64。

func Uint64N

1
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.

Uint64N 返回一个伪随机数，该数位于半开区间 [0, n) 内，类型为 uint64。若 n <= 0，则会引发恐慌。

func UintN

1
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.

UintN 返回一个伪随机数，该数位于半开区间 [0, n) 内，类型为 uint。若 n <= 0，则会引发恐慌。

类型

type ChaCha8

1
2
3
type ChaCha8 struct {
	// contains filtered or unexported fields
}

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

ChaCha8 是基于 ChaCha8 的密码学强随机数生成器。

func NewChaCha8

1
func NewChaCha8(seed [32]byte) *ChaCha8

NewChaCha8 returns a new ChaCha8 seeded with the given seed.

NewChaCha8 返回一个使用给定种子初始化的新的 ChaCha8 实例。

(*ChaCha8) MarshalBinary

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

MarshalBinary implements the encoding.BinaryMarshaler interface.

MarshalBinary 实现了 encoding.BinaryMarshaler 接口。

(*ChaCha8) Read <- go1.23.0

1
func (c *ChaCha8) Read(p []byte) (n int, err error)

Read reads exactly len(p) bytes into p. It always returns len(p) and a nil error.

Read 将 len(p) 个字节读取到 p 中。它总是返回 len(p) 和一个 nil 错误。If calls to Read and Uint64 are interleaved, the order in which bits are returned by the two is undefined, and Read may return bits generated before the last call to Uint64.

如果 Read 和 Uint64 交替调用，则它们返回的位的顺序是未定义的，Read 可能返回在上一次调用 Uint64 之前生成的位。

(*ChaCha8) Seed

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

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

Seed 将 ChaCha8 重置为与 NewChaCha8(seed) 相同的行为。

(*ChaCha8) Uint64

1
func (c *ChaCha8) Uint64() uint64

Uint64 returns a uniformly distributed random uint64 value.

Uint64 返回一个均匀分布的随机 uint64 值。

(*ChaCha8) UnmarshalBinary

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

UnmarshalBinary implements the encoding.BinaryUnmarshaler interface.

UnmarshalBinary 实现了 encoding.BinaryUnmarshaler 接口。

type PCG

1
2
3
type PCG struct {
	// contains filtered or unexported fields
}

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

PCG 是一个具有 128 位内部状态的 PCG 生成器。零值 PCG 相当于 NewPCG(0, 0)。

func NewPCG

1
func NewPCG(seed1, seed2 uint64) *PCG

NewPCG returns a new PCG seeded with the given values.

NewPCG 返回一个使用给定值初始化的新 PCG 实例。

(*PCG) MarshalBinary

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

MarshalBinary implements the encoding.BinaryMarshaler interface.

MarshalBinary 实现了 encoding.BinaryMarshaler 接口。

(*PCG) Seed

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

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

Seed 将 PCG 重置为与 NewPCG(seed1, seed2) 相同的行为。

(*PCG) Uint64

1
func (p *PCG) Uint64() uint64

Uint64 return a uniformly-distributed random uint64 value.

Uint64 返回一个均匀分布的随机 uint64 值。

(*PCG) UnmarshalBinary

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

UnmarshalBinary implements the encoding.BinaryUnmarshaler interface.

UnmarshalBinary 实现了 encoding.BinaryUnmarshaler 接口。

type Rand

1
2
3
type Rand struct {
	// contains filtered or unexported fields
}

A Rand is a source of random numbers.

Rand 是一个随机数源。

func New

1
func New(src Source) *Rand

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

New 返回一个新的 Rand 实例，该实例使用 src 的随机值生成其他随机值。

(*Rand) ExpFloat64

1
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:

ExpFloat64 返回一个在 (0, +math.MaxFloat64] 范围内的指数分布 float64，指数分布的速率参数（lambda）为 1，均值为 1/lambda (1)。要生成具有不同速率参数的分布，调用者可以调整输出值：

sample = ExpFloat64() / desiredRateParameter

(*Rand) Float32

1
func (r *Rand) Float32() float32

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

Float32 返回一个在半开区间 [0.0, 1.0) 内的伪随机数，类型为 float32。

(*Rand) Float64

1
func (r *Rand) Float64() float64

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

Float64 返回一个在半开区间 [0.0, 1.0) 内的伪随机数，类型为 float64。

(*Rand) Int

1
func (r *Rand) Int() int

Int returns a non-negative pseudo-random int.

Int 返回一个非负的伪随机 int 值。

(*Rand) Int32

1
func (r *Rand) Int32() int32

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

Int32 返回一个非负的伪随机 31 位整数，类型为 int32。

(*Rand) Int32N

1
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.

Int32N 返回一个伪随机数，该数位于半开区间 [0, n) 内，类型为 int32。若 n <= 0，则会引发恐慌。

(*Rand) Int64

1
func (r *Rand) Int64() int64

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

Int64 返回一个非负的伪随机 63 位整数，类型为 int64。

(*Rand) Int64N

1
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.

Int64N 返回一个伪随机数，该数位于半开区间 [0, n) 内，类型为 int64。若 n <= 0，则会引发恐慌。

(*Rand) IntN

1
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.

IntN 返回一个非负的伪随机数，该数位于半开区间 [0, n) 内，类型为 int。若 n <= 0，则会引发恐慌。

(*Rand) NormFloat64

1
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:

NormFloat64 返回一个在 -math.MaxFloat64 到 +math.MaxFloat64 范围内的正态分布 float64，标准正态分布（均值 = 0，标准差 = 1）。要生成不同的正态分布，调用者可以调整输出值：

sample = NormFloat64() * desiredStdDev + desiredMean

(*Rand) Perm

1
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).

Perm 返回一个包含 n 个整数的切片，生成从半开区间 [0, n) 内的伪随机排列。

(*Rand) Shuffle

1
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.

Shuffle 对元素的顺序进行伪随机化。n 是元素的数量。若 n < 0，则会引发恐慌。swap 用于交换索引为 i 和 j 的元素。

(*Rand) Uint <- go1.23.0

1
func (r *Rand) Uint() uint

Uint returns a pseudo-random uint.

Uint 返回一个伪随机 uint 值。

(*Rand) Uint32

1
func (r *Rand) Uint32() uint32

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

Uint32 返回一个伪随机的 32 位值，类型为 uint32。

(*Rand) Uint32N

1
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.

Uint32N 返回一个伪随机数，该数位于半开区间 [0, n) 内，类型为 uint32。若 n == 0，则会引发恐慌。

(*Rand) Uint64

1
func (r *Rand) Uint64() uint64

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

Uint64 返回一个伪随机的 64 位值，类型为 uint64。

(*Rand) Uint64N

1
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.

Uint64N 返回一个伪随机数，该数位于半开区间 [0, n) 内，类型为 uint64。若 n == 0，则会引发恐慌。

(*Rand) UintN

1
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.

UintN 返回一个伪随机数，该数位于半开区间 [0, n) 内，类型为 uint。若 n == 0，则会引发恐慌。

type Source

1
2
3
type Source interface {
	Uint64() uint64
}

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

Source 是一个均匀分布的伪随机 uint64 值源，范围在 [0, 1«64) 内。

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

Source 不能被多个 goroutine 同时安全使用。

type Zipf

1
2
3
type Zipf struct {
	// contains filtered or unexported fields
}

A Zipf generates Zipf distributed variates.

Zipf 生成 Zipf 分布的变体。

func NewZipf

1
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.

NewZipf 返回一个 Zipf 变体生成器。生成器生成值 k ∈ [0, imax]，使得 P(k) 与 (v + k) ** (-s) 成正比。要求：s > 1 且 v >= 1。

(*Zipf) Uint64

1
func (z *Zipf) Uint64() uint64

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

Uint64 返回从 Zipf 分布中抽取的一个值。

最后修改 October 10, 2024: 更新 (a4b8f85)