From 6efb6b9e381405d0fcae6cd098ab59dfc98dc8c3 Mon Sep 17 00:00:00 2001 From: Andrew Gerrand Date: Tue, 23 Jul 2013 16:07:28 +1000 Subject: [PATCH] math/rand: mention Seed in overview, add another top-level example Fixes #5937. R=golang-dev, mirtchovski, r CC=golang-dev https://golang.org/cl/11705043 --- src/pkg/math/rand/example_test.go | 32 ++++++++++++++++++++++-- src/pkg/math/rand/rand.go | 41 +++++++++++++++++++++---------- 2 files changed, 58 insertions(+), 15 deletions(-) diff --git a/src/pkg/math/rand/example_test.go b/src/pkg/math/rand/example_test.go index 4fe207d85e..f429914531 100644 --- a/src/pkg/math/rand/example_test.go +++ b/src/pkg/math/rand/example_test.go @@ -11,12 +11,40 @@ import ( "text/tabwriter" ) -// This test serves as an example but also makes sure we don't change +// These tests serve as an example but also make sure we don't change // the output of the random number generator when given a fixed seed. +func Example() { + rand.Seed(42) // Try changing this number! + 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))]) + // Output: Magic 8-Ball says: As I see it yes +} + // 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. -func Example() { +func Example_rand() { // Create and seed the generator. // Typically a non-fixed seed should be used, such as time.Now().UnixNano(). // Using a fixed seed will produce the same output on every run. diff --git a/src/pkg/math/rand/rand.go b/src/pkg/math/rand/rand.go index 94f84a85fb..608012a300 100644 --- a/src/pkg/math/rand/rand.go +++ b/src/pkg/math/rand/rand.go @@ -3,6 +3,11 @@ // license that can be found in the LICENSE file. // Package rand implements pseudo-random number generators. +// +// Random numbers are generated by a Source. Top-level functions, such as +// Float64 and Int, use a default shared Source that produces a deterministic +// sequence of values each time a program is run. Use the Seed function to +// initialize the default Source if different behavior is required for each run. package rand import "sync" @@ -113,47 +118,57 @@ func (r *Rand) Perm(n int) []int { var globalRand = New(&lockedSource{src: NewSource(1)}) -// Seed uses the provided seed value to initialize the generator to a +// Seed uses the provided seed value to initialize the default Source to a // deterministic state. If Seed is not called, the generator behaves as // if seeded by Seed(1). func Seed(seed int64) { globalRand.Seed(seed) } -// Int63 returns a non-negative pseudo-random 63-bit integer as an int64. +// Int63 returns a non-negative pseudo-random 63-bit integer as an int64 +// from the default Source. func Int63() int64 { return globalRand.Int63() } -// Uint32 returns a pseudo-random 32-bit value as a uint32. +// Uint32 returns a pseudo-random 32-bit value as a uint32 +// from the default Source. func Uint32() uint32 { return globalRand.Uint32() } -// Int31 returns a non-negative pseudo-random 31-bit integer as an int32. +// Int31 returns a non-negative pseudo-random 31-bit integer as an int32 +// from the default Source. func Int31() int32 { return globalRand.Int31() } -// Int returns a non-negative pseudo-random int. +// Int returns a non-negative pseudo-random int from the default Source. func Int() int { return globalRand.Int() } -// Int63n returns, as an int64, a non-negative pseudo-random number in [0,n). +// Int63n returns, as an int64, a non-negative pseudo-random number in [0,n) +// from the default Source. // It panics if n <= 0. func Int63n(n int64) int64 { return globalRand.Int63n(n) } -// Int31n returns, as an int32, a non-negative pseudo-random number in [0,n). +// Int31n returns, as an int32, a non-negative pseudo-random number in [0,n) +// from the default Source. // It panics if n <= 0. func Int31n(n int32) int32 { return globalRand.Int31n(n) } -// Intn returns, as an int, a non-negative pseudo-random number in [0,n). +// Intn returns, as an int, a non-negative pseudo-random number in [0,n) +// from the default Source. // It panics if n <= 0. func Intn(n int) int { return globalRand.Intn(n) } -// Float64 returns, as a float64, a pseudo-random number in [0.0,1.0). +// Float64 returns, as a float64, a pseudo-random number in [0.0,1.0) +// from the default Source. func Float64() float64 { return globalRand.Float64() } -// Float32 returns, as a float32, a pseudo-random number in [0.0,1.0). +// Float32 returns, as a float32, a pseudo-random number in [0.0,1.0) +// from the default Source. func Float32() float32 { return globalRand.Float32() } -// Perm returns, as a slice of n ints, a pseudo-random permutation of the integers [0,n). +// Perm returns, as a slice of n ints, a pseudo-random permutation of the integers [0,n) +// from the default Source. func Perm(n int) []int { return globalRand.Perm(n) } // NormFloat64 returns a normally distributed float64 in the range // [-math.MaxFloat64, +math.MaxFloat64] with -// standard normal distribution (mean = 0, stddev = 1). +// standard normal distribution (mean = 0, stddev = 1) +// from the default Source. // To produce a different normal distribution, callers can // adjust the output using: // @@ -163,7 +178,7 @@ func NormFloat64() float64 { return globalRand.NormFloat64() } // 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). +// (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: // -- 2.48.1