diff options
Diffstat (limited to 'devdocs/go/math%2Frand%2Findex.html')
| -rw-r--r-- | devdocs/go/math%2Frand%2Findex.html | 240 |
1 files changed, 240 insertions, 0 deletions
diff --git a/devdocs/go/math%2Frand%2Findex.html b/devdocs/go/math%2Frand%2Findex.html new file mode 100644 index 00000000..17d714f2 --- /dev/null +++ b/devdocs/go/math%2Frand%2Findex.html @@ -0,0 +1,240 @@ +<h1> Package rand </h1> <ul id="short-nav"> +<li><code>import "math/rand"</code></li> +<li><a href="#pkg-overview" class="overviewLink">Overview</a></li> +<li><a href="#pkg-index" class="indexLink">Index</a></li> +<li><a href="#pkg-examples" class="examplesLink">Examples</a></li> +<li><a href="#pkg-subdirectories">Subdirectories</a></li> +</ul> <h2 id="pkg-overview">Overview </h2> <p>Package rand implements pseudo-random number generators suitable for tasks such as simulation, but it should not be used for security-sensitive work. </p> +<p>Random numbers are generated by a <a href="#Source">Source</a>, usually wrapped in a <a href="#Rand">Rand</a>. Both types should be used by a single goroutine at a time: sharing among multiple goroutines requires some kind of synchronization. </p> +<p>Top-level functions, such as <a href="#Float64">Float64</a> and <a href="#Int">Int</a>, are safe for concurrent use by multiple goroutines. </p> +<p>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. </p> <h4 id="example_"> <span class="text">Example</span> +</h4> <p>Code:</p> <pre class="code" data-language="go"> +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))]) +</pre> <h4 id="example__rand"> <span class="text">Example (Rand)</span> +</h4> <p>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. </p> <p>Code:</p> <pre class="code" data-language="go">// 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. +r := rand.New(rand.NewSource(99)) + +// 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()) + +// Int31, Int63, and Uint32 generate values of the given width. +// The Int method (not shown) is like either Int31 or Int63 +// depending on the size of 'int'. +show("Int31", r.Int31(), r.Int31(), r.Int31()) +show("Int63", r.Int63(), r.Int63(), r.Int63()) +show("Uint32", r.Uint32(), r.Uint32(), r.Uint32()) + +// Intn, Int31n, and Int63n 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("Int31n(10)", r.Int31n(10), r.Int31n(10), r.Int31n(10)) +show("Int63n(10)", r.Int63n(10), r.Int63n(10), r.Int63n(10)) + +// Perm generates a random permutation of the numbers [0, n). +show("Perm", r.Perm(5), r.Perm(5), r.Perm(5)) +</pre> <p>Output:</p> <pre class="output" data-language="go">Float32 0.2635776 0.6358173 0.6718283 +Float64 0.628605430454327 0.4504798828572669 0.9562755949377957 +ExpFloat64 0.3362240648200941 1.4256072328483647 0.24354758816173044 +NormFloat64 0.17233959114940064 1.577014951434847 0.04259129641113857 +Int31 1501292890 1486668269 182840835 +Int63 3546343826724305832 5724354148158589552 5239846799706671610 +Uint32 2760229429 296659907 1922395059 +Intn(10) 1 2 5 +Int31n(10) 4 7 8 +Int63n(10) 7 6 3 +Perm [1 4 2 3 0] [4 2 1 3 0] [1 2 4 0 3] +</pre> <h2 id="pkg-index">Index </h2> <ul id="manual-nav"> +<li><a href="#ExpFloat64">func ExpFloat64() float64</a></li> +<li><a href="#Float32">func Float32() float32</a></li> +<li><a href="#Float64">func Float64() float64</a></li> +<li><a href="#Int">func Int() int</a></li> +<li><a href="#Int31">func Int31() int32</a></li> +<li><a href="#Int31n">func Int31n(n int32) int32</a></li> +<li><a href="#Int63">func Int63() int64</a></li> +<li><a href="#Int63n">func Int63n(n int64) int64</a></li> +<li><a href="#Intn">func Intn(n int) int</a></li> +<li><a href="#NormFloat64">func NormFloat64() float64</a></li> +<li><a href="#Perm">func Perm(n int) []int</a></li> +<li><a href="#Read">func Read(p []byte) (n int, err error)</a></li> +<li><a href="#Seed">func Seed(seed int64)</a></li> +<li><a href="#Shuffle">func Shuffle(n int, swap func(i, j int))</a></li> +<li><a href="#Uint32">func Uint32() uint32</a></li> +<li><a href="#Uint64">func Uint64() uint64</a></li> +<li><a href="#Rand">type Rand</a></li> +<li> <a href="#New">func New(src Source) *Rand</a> +</li> +<li> <a href="#Rand.ExpFloat64">func (r *Rand) ExpFloat64() float64</a> +</li> +<li> <a href="#Rand.Float32">func (r *Rand) Float32() float32</a> +</li> +<li> <a href="#Rand.Float64">func (r *Rand) Float64() float64</a> +</li> +<li> <a href="#Rand.Int">func (r *Rand) Int() int</a> +</li> +<li> <a href="#Rand.Int31">func (r *Rand) Int31() int32</a> +</li> +<li> <a href="#Rand.Int31n">func (r *Rand) Int31n(n int32) int32</a> +</li> +<li> <a href="#Rand.Int63">func (r *Rand) Int63() int64</a> +</li> +<li> <a href="#Rand.Int63n">func (r *Rand) Int63n(n int64) int64</a> +</li> +<li> <a href="#Rand.Intn">func (r *Rand) Intn(n int) int</a> +</li> +<li> <a href="#Rand.NormFloat64">func (r *Rand) NormFloat64() float64</a> +</li> +<li> <a href="#Rand.Perm">func (r *Rand) Perm(n int) []int</a> +</li> +<li> <a href="#Rand.Read">func (r *Rand) Read(p []byte) (n int, err error)</a> +</li> +<li> <a href="#Rand.Seed">func (r *Rand) Seed(seed int64)</a> +</li> +<li> <a href="#Rand.Shuffle">func (r *Rand) Shuffle(n int, swap func(i, j int))</a> +</li> +<li> <a href="#Rand.Uint32">func (r *Rand) Uint32() uint32</a> +</li> +<li> <a href="#Rand.Uint64">func (r *Rand) Uint64() uint64</a> +</li> +<li><a href="#Source">type Source</a></li> +<li> <a href="#NewSource">func NewSource(seed int64) Source</a> +</li> +<li><a href="#Source64">type Source64</a></li> +<li><a href="#Zipf">type Zipf</a></li> +<li> <a href="#NewZipf">func NewZipf(r *Rand, s float64, v float64, imax uint64) *Zipf</a> +</li> +<li> <a href="#Zipf.Uint64">func (z *Zipf) Uint64() uint64</a> +</li> +</ul> <div id="pkg-examples"> <h3>Examples</h3> <dl> <dd><a class="exampleLink" href="#example_">Package</a></dd> <dd><a class="exampleLink" href="#example_Intn">Intn</a></dd> <dd><a class="exampleLink" href="#example_Perm">Perm</a></dd> <dd><a class="exampleLink" href="#example_Shuffle">Shuffle</a></dd> <dd><a class="exampleLink" href="#example_Shuffle_slicesInUnison">Shuffle (SlicesInUnison)</a></dd> <dd><a class="exampleLink" href="#example__rand">Package (Rand)</a></dd> </dl> </div> <h3>Package files</h3> <p> <span>exp.go</span> <span>normal.go</span> <span>rand.go</span> <span>rng.go</span> <span>zipf.go</span> </p> <h2 id="ExpFloat64">func <span>ExpFloat64</span> </h2> <pre data-language="go">func ExpFloat64() float64</pre> <p>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 <a href="#Source">Source</a>. To produce a distribution with a different rate parameter, callers can adjust the output using: </p> +<pre data-language="go">sample = ExpFloat64() / desiredRateParameter +</pre> <h2 id="Float32">func <span>Float32</span> </h2> <pre data-language="go">func Float32() float32</pre> <p>Float32 returns, as a float32, a pseudo-random number in the half-open interval [0.0,1.0) from the default <a href="#Source">Source</a>. </p> +<h2 id="Float64">func <span>Float64</span> </h2> <pre data-language="go">func Float64() float64</pre> <p>Float64 returns, as a float64, a pseudo-random number in the half-open interval [0.0,1.0) from the default <a href="#Source">Source</a>. </p> +<h2 id="Int">func <span>Int</span> </h2> <pre data-language="go">func Int() int</pre> <p>Int returns a non-negative pseudo-random int from the default <a href="#Source">Source</a>. </p> +<h2 id="Int31">func <span>Int31</span> </h2> <pre data-language="go">func Int31() int32</pre> <p>Int31 returns a non-negative pseudo-random 31-bit integer as an int32 from the default <a href="#Source">Source</a>. </p> +<h2 id="Int31n">func <span>Int31n</span> </h2> <pre data-language="go">func Int31n(n int32) int32</pre> <p>Int31n returns, as an int32, a non-negative pseudo-random number in the half-open interval [0,n) from the default <a href="#Source">Source</a>. It panics if n <= 0. </p> +<h2 id="Int63">func <span>Int63</span> </h2> <pre data-language="go">func Int63() int64</pre> <p>Int63 returns a non-negative pseudo-random 63-bit integer as an int64 from the default <a href="#Source">Source</a>. </p> +<h2 id="Int63n">func <span>Int63n</span> </h2> <pre data-language="go">func Int63n(n int64) int64</pre> <p>Int63n returns, as an int64, a non-negative pseudo-random number in the half-open interval [0,n) from the default <a href="#Source">Source</a>. It panics if n <= 0. </p> +<h2 id="Intn">func <span>Intn</span> </h2> <pre data-language="go">func Intn(n int) int</pre> <p>Intn returns, as an int, a non-negative pseudo-random number in the half-open interval [0,n) from the default <a href="#Source">Source</a>. It panics if n <= 0. </p> <h4 id="example_Intn"> <span class="text">Example</span> +</h4> <p>Code:</p> <pre class="code" data-language="go"> +fmt.Println(rand.Intn(100)) +fmt.Println(rand.Intn(100)) +fmt.Println(rand.Intn(100)) +</pre> <h2 id="NormFloat64">func <span>NormFloat64</span> </h2> <pre data-language="go">func NormFloat64() float64</pre> <p>NormFloat64 returns a normally distributed float64 in the range [-<span>math.MaxFloat64</span>, +[math.MaxFloat64]] with standard normal distribution (mean = 0, stddev = 1) from the default <a href="#Source">Source</a>. To produce a different normal distribution, callers can adjust the output using: </p> +<pre data-language="go">sample = NormFloat64() * desiredStdDev + desiredMean +</pre> <h2 id="Perm">func <span>Perm</span> </h2> <pre data-language="go">func Perm(n int) []int</pre> <p>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 <a href="#Source">Source</a>. </p> <h4 id="example_Perm"> <span class="text">Example</span> +</h4> <p>Code:</p> <pre class="code" data-language="go">for _, value := range rand.Perm(3) { + fmt.Println(value) +} + +</pre> <p>Output:</p> <pre class="output" data-language="go">1 +2 +0 +</pre> <h2 id="Read">func <span>Read</span> <span title="Added in Go 1.6">1.6</span> </h2> <pre data-language="go">func Read(p []byte) (n int, err error)</pre> <p>Read generates len(p) random bytes from the default <a href="#Source">Source</a> and writes them into p. It always returns len(p) and a nil error. Read, unlike the <a href="#Rand.Read">Rand.Read</a> method, is safe for concurrent use. </p> +<p>Deprecated: For almost all use cases, <span>crypto/rand.Read</span> is more appropriate. </p> +<h2 id="Seed">func <span>Seed</span> </h2> <pre data-language="go">func Seed(seed int64)</pre> <p>Seed uses the provided seed value to initialize the default Source to a deterministic state. Seed values that have the same remainder when divided by 2³¹-1 generate the same pseudo-random sequence. Seed, unlike the <a href="#Rand.Seed">Rand.Seed</a> method, is safe for concurrent use. </p> +<p>If Seed is not called, the generator is seeded randomly at program startup. </p> +<p>Prior to Go 1.20, the generator was seeded like Seed(1) at program startup. To force the old behavior, call Seed(1) at program startup. Alternately, set GODEBUG=randautoseed=0 in the environment before making any calls to functions in this package. </p> +<p>Deprecated: As of Go 1.20 there is no reason to call Seed with a random value. Programs that call Seed with a known value to get a specific sequence of results should use New(NewSource(seed)) to obtain a local random generator. </p> +<h2 id="Shuffle">func <span>Shuffle</span> <span title="Added in Go 1.10">1.10</span> </h2> <pre data-language="go">func Shuffle(n int, swap func(i, j int))</pre> <p>Shuffle pseudo-randomizes the order of elements using the default <a href="#Source">Source</a>. n is the number of elements. Shuffle panics if n < 0. swap swaps the elements with indexes i and j. </p> <h4 id="example_Shuffle"> <span class="text">Example</span> +</h4> <p>Code:</p> <pre class="code" data-language="go"> +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) +</pre> <h4 id="example_Shuffle_slicesInUnison"> <span class="text">Example (SlicesInUnison)</span> +</h4> <p>Code:</p> <pre class="code" data-language="go"> +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]) +} +</pre> <h2 id="Uint32">func <span>Uint32</span> </h2> <pre data-language="go">func Uint32() uint32</pre> <p>Uint32 returns a pseudo-random 32-bit value as a uint32 from the default <a href="#Source">Source</a>. </p> +<h2 id="Uint64">func <span>Uint64</span> <span title="Added in Go 1.8">1.8</span> </h2> <pre data-language="go">func Uint64() uint64</pre> <p>Uint64 returns a pseudo-random 64-bit value as a uint64 from the default <a href="#Source">Source</a>. </p> +<h2 id="Rand">type <span>Rand</span> </h2> <p>A Rand is a source of random numbers. </p> +<pre data-language="go">type Rand struct { + // contains filtered or unexported fields +} +</pre> <h3 id="New">func <span>New</span> </h3> <pre data-language="go">func New(src Source) *Rand</pre> <p>New returns a new <a href="#Rand">Rand</a> that uses random values from src to generate other random values. </p> +<h3 id="Rand.ExpFloat64">func (*Rand) <span>ExpFloat64</span> </h3> <pre data-language="go">func (r *Rand) ExpFloat64() float64</pre> <p>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: </p> +<pre data-language="go">sample = ExpFloat64() / desiredRateParameter +</pre> <h3 id="Rand.Float32">func (*Rand) <span>Float32</span> </h3> <pre data-language="go">func (r *Rand) Float32() float32</pre> <p>Float32 returns, as a float32, a pseudo-random number in the half-open interval [0.0,1.0). </p> +<h3 id="Rand.Float64">func (*Rand) <span>Float64</span> </h3> <pre data-language="go">func (r *Rand) Float64() float64</pre> <p>Float64 returns, as a float64, a pseudo-random number in the half-open interval [0.0,1.0). </p> +<h3 id="Rand.Int">func (*Rand) <span>Int</span> </h3> <pre data-language="go">func (r *Rand) Int() int</pre> <p>Int returns a non-negative pseudo-random int. </p> +<h3 id="Rand.Int31">func (*Rand) <span>Int31</span> </h3> <pre data-language="go">func (r *Rand) Int31() int32</pre> <p>Int31 returns a non-negative pseudo-random 31-bit integer as an int32. </p> +<h3 id="Rand.Int31n">func (*Rand) <span>Int31n</span> </h3> <pre data-language="go">func (r *Rand) Int31n(n int32) int32</pre> <p>Int31n returns, as an int32, a non-negative pseudo-random number in the half-open interval [0,n). It panics if n <= 0. </p> +<h3 id="Rand.Int63">func (*Rand) <span>Int63</span> </h3> <pre data-language="go">func (r *Rand) Int63() int64</pre> <p>Int63 returns a non-negative pseudo-random 63-bit integer as an int64. </p> +<h3 id="Rand.Int63n">func (*Rand) <span>Int63n</span> </h3> <pre data-language="go">func (r *Rand) Int63n(n int64) int64</pre> <p>Int63n returns, as an int64, a non-negative pseudo-random number in the half-open interval [0,n). It panics if n <= 0. </p> +<h3 id="Rand.Intn">func (*Rand) <span>Intn</span> </h3> <pre data-language="go">func (r *Rand) Intn(n int) int</pre> <p>Intn returns, as an int, a non-negative pseudo-random number in the half-open interval [0,n). It panics if n <= 0. </p> +<h3 id="Rand.NormFloat64">func (*Rand) <span>NormFloat64</span> </h3> <pre data-language="go">func (r *Rand) NormFloat64() float64</pre> <p>NormFloat64 returns a normally distributed float64 in the range -<span>math.MaxFloat64</span> through +[math.MaxFloat64] inclusive, with standard normal distribution (mean = 0, stddev = 1). To produce a different normal distribution, callers can adjust the output using: </p> +<pre data-language="go">sample = NormFloat64() * desiredStdDev + desiredMean +</pre> <h3 id="Rand.Perm">func (*Rand) <span>Perm</span> </h3> <pre data-language="go">func (r *Rand) Perm(n int) []int</pre> <p>Perm returns, as a slice of n ints, a pseudo-random permutation of the integers in the half-open interval [0,n). </p> +<h3 id="Rand.Read">func (*Rand) <span>Read</span> <span title="Added in Go 1.6">1.6</span> </h3> <pre data-language="go">func (r *Rand) Read(p []byte) (n int, err error)</pre> <p>Read generates len(p) random bytes and writes them into p. It always returns len(p) and a nil error. Read should not be called concurrently with any other Rand method. </p> +<h3 id="Rand.Seed">func (*Rand) <span>Seed</span> </h3> <pre data-language="go">func (r *Rand) Seed(seed int64)</pre> <p>Seed uses the provided seed value to initialize the generator to a deterministic state. Seed should not be called concurrently with any other <a href="#Rand">Rand</a> method. </p> +<h3 id="Rand.Shuffle">func (*Rand) <span>Shuffle</span> <span title="Added in Go 1.10">1.10</span> </h3> <pre data-language="go">func (r *Rand) Shuffle(n int, swap func(i, j int))</pre> <p>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. </p> +<h3 id="Rand.Uint32">func (*Rand) <span>Uint32</span> </h3> <pre data-language="go">func (r *Rand) Uint32() uint32</pre> <p>Uint32 returns a pseudo-random 32-bit value as a uint32. </p> +<h3 id="Rand.Uint64">func (*Rand) <span>Uint64</span> <span title="Added in Go 1.8">1.8</span> </h3> <pre data-language="go">func (r *Rand) Uint64() uint64</pre> <p>Uint64 returns a pseudo-random 64-bit value as a uint64. </p> +<h2 id="Source">type <span>Source</span> </h2> <p>A Source represents a source of uniformly-distributed pseudo-random int64 values in the range [0, 1<<63). </p> +<p>A Source is not safe for concurrent use by multiple goroutines. </p> +<pre data-language="go">type Source interface { + Int63() int64 + Seed(seed int64) +}</pre> <h3 id="NewSource">func <span>NewSource</span> </h3> <pre data-language="go">func NewSource(seed int64) Source</pre> <p>NewSource returns a new pseudo-random <a href="#Source">Source</a> seeded with the given value. Unlike the default <a href="#Source">Source</a> used by top-level functions, this source is not safe for concurrent use by multiple goroutines. The returned <a href="#Source">Source</a> implements <a href="#Source64">Source64</a>. </p> +<h2 id="Source64">type <span>Source64</span> <span title="Added in Go 1.8">1.8</span> </h2> <p>A Source64 is a <a href="#Source">Source</a> that can also generate uniformly-distributed pseudo-random uint64 values in the range [0, 1<<64) directly. If a <a href="#Rand">Rand</a> r's underlying <a href="#Source">Source</a> s implements Source64, then r.Uint64 returns the result of one call to s.Uint64 instead of making two calls to s.Int63. </p> +<pre data-language="go">type Source64 interface { + Source + Uint64() uint64 +}</pre> <h2 id="Zipf">type <span>Zipf</span> </h2> <p>A Zipf generates Zipf distributed variates. </p> +<pre data-language="go">type Zipf struct { + // contains filtered or unexported fields +} +</pre> <h3 id="NewZipf">func <span>NewZipf</span> </h3> <pre data-language="go">func NewZipf(r *Rand, s float64, v float64, imax uint64) *Zipf</pre> <p>NewZipf returns a <a href="#Zipf">Zipf</a> 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. </p> +<h3 id="Zipf.Uint64">func (*Zipf) <span>Uint64</span> </h3> <pre data-language="go">func (z *Zipf) Uint64() uint64</pre> <p>Uint64 returns a value drawn from the <a href="#Zipf">Zipf</a> distribution described by the <a href="#Zipf">Zipf</a> object. </p> +<h2 id="pkg-subdirectories">Subdirectories</h2> <div class="pkg-dir"> <table> <tr> <th class="pkg-name">Name</th> <th class="pkg-synopsis">Synopsis</th> </tr> <tr> <td colspan="2"><a href="../index">..</a></td> </tr> <tr> <td class="pkg-name"> <a href="v2/index">v2</a> </td> <td class="pkg-synopsis"> Package rand implements pseudo-random number generators suitable for tasks such as simulation, but it should not be used for security-sensitive work. </td> </tr> </table> </div><div class="_attribution"> + <p class="_attribution-p"> + © Google, Inc.<br>Licensed under the Creative Commons Attribution License 3.0.<br> + <a href="http://golang.org/pkg/math/rand/" class="_attribution-link">http://golang.org/pkg/math/rand/</a> + </p> +</div> |