Questions about golang's rand package

I've been using and reading about the Golang rand package but I can't find a resource that actually explains what it's doing in a way I can understand.

First, what is really happening when you "seed"? If you are then asking for a random number in a range (for example using rand.Intn(7)), it seems like that should be enough to tell Go what you're looking for, but it's not. What does rand.Seed() contribute?

Here is an example that you can play with here:

func main() {
  rand.Seed(time.Now().UnixNano())
  fmt.Println(rand.Intn(7))
}

I was thinking maybe the "Source" is all possible numbers you could pull from and then something like rand.Intn() gives you a random number from a subset of the Source. So seeding is just defining the Source. But if I try getting a random number from a range outside of the initial seed, it stills works, so that doesn't seem to be right, unless it just excludes the part of the range that doesn't exist. See this example:

func main() {
  rand.Seed(6)
  fmt.Println(rand.Intn(7))
}

And what about this line in the documentation that says:

> If Seed is not called, the generator is seeded randomly at program startup.

That doesn't seem to happen because if you don't call rand.Seed() and try to use rand.Intn(), you just get the same thing over and over, similar to if you use a constant with rand.Seed().

Second, the documentation for rand.Intn() says it "panics if n <= 0". I've tested this using the above link and it's not true, it will return 0 without panicking. I actually want to include 0 so this is good but it's not lining up with what the docs say. Is there another, proper way to include 0 when specifying a range? I couldn't find one.

Third, the documentation talks about a "default Source" here. Is that just something that exists without us having to do anything? And then if I want a specific Source I use rand.New() to create one? Why would I want a specific one?

Go's documentation is considered very good and well thought out so I think I must just be missing something here, appreciate anyone's insight!

The math/rand random number generator is a "pseudo" random number generator. Conceptually, it looks like this:

var last int

func nextRandom() int { 
   last:= computeRandom(last)
   return last
}

So it is a deterministic function that generates a sequence of values based on the previous value. Given an initial value of last, consecutive calls to nextRandom will generate the same sequence of values.

Seed sets the last value, so by setting the last value to some number, say, current time, you get a different sequence of numbers.

As of this writing (v1.19), the random number generator is not seeded with a random number at program startup. This seems to have changed at v1.20.

Intn panics when n<=0: https://cs.opensource.google/go/go/+/refs/tags/go1.20.2:src/math/rand/rand.go;l=178

The default source is a package level Source instance used by all exported functions:

var globalRand = New(new(lockedSource))

func Int63() int64 { return globalRand.Int63() }
...

> What does rand.Seed() contribute?

Seeding a pseudo random number generator means providing input that sets it state. A pseudo random number generator then creates randomness from that state. If you seed the PRNG multiple times then the later seed values get mixed in.

> I was thinking maybe the "Source" is all possible numbers you could pull from and then something like rand.Intn() gives you a random number from a subset of the Source.

The Source is really a limited RNG in the sense that it only produces bits (or, in this case, integer values in the range [0, 2^63), which of course simply corresponds with 63 bits. That can then be used to perform other jobs, such as generating numbers in other ranges, or maybe to shuffle a list, etc.

> That doesn't seem to happen because if you don't call rand.Seed() and try to use rand.Intn(), you just get the same thing over and over, similar to if you use a constant with rand.Seed().

This seems to be a recent change. So I guess your runtime and documentation are not for the same API version.

> Second, the documentation for rand.Intn() says it "panics if n <= 0". I've tested this using the above link and it's not true, it will return 0 without panicking.

Sounds like a bug to me. If n is indeed 0 or lower than 0 then it should panic.

> I actually want to include 0 so this is good but it's not lining up with what the docs say. Is there another, proper way to include 0 when specifying a range? I couldn't find one.

Not sure what you mean here. If you'd specify 0 then you get the range [0, 0) which doesn't make any sense, as 0 is first included as start value, and then excluded as end value. You'd expect [0, 1) also to be problematic as just returning 0 is not very random (I'd still allow for the function as API designer, but yeah, it's a degenerate case).

rand.Intn() generates a range [0, n). Whatever n is going to be, 0 is going to be included in the possible output.

> Third, the documentation talks about a "default Source" here. Is that just something that exists without us having to do anything? And then if I want a specific Source I use rand.New() to create one? Why would I want a specific one?

Well, maybe you want to create a very specific run of test values that doesn't change, e.g. for testing purposes.