math/rand: document whether NewSource always implements Source64

[dsnet]

The concrete type returned by NewSource happens to implement Source64. However, this is not documented in any way. Is this always guaranteed?

[ulikunitz]

I looked into the source code of rng.go and since Int63() calls Uint64(), NewSource is always returning a Source64 implementation.

// Int63 returns a non-negative pseudo-random 63-bit integer as an int64.
func (rng *rngSource) Int63() int64 {
	return int64(rng.Uint64() & rngMask)
}

[dsnet]

I believe the snippet you actually wanted to reference is:

go/src/math/rand/rng.go

Lines 237 to 252 in 87e984a

	// Uint64 returns a non-negative pseudo-random 64-bit integer as an uint64.
	func (rng *rngSource) Uint64() uint64 {
	rng.tap--
	if rng.tap < 0 {
	rng.tap += rngLen
	}
	rng.feed--
	if rng.feed < 0 {
	rng.feed += rngLen
	}
	x := rng.vec[rng.feed] + rng.vec[rng.tap]
	rng.vec[rng.feed] = x
	return uint64(x)
	}

I'm aware that it current returns something that implements Source64 and has done so for many years. The question is whether this should be a documented guarantee (which I think it should be).

[ianlancetaylor]

I think we should document it.

[gopherbot]

Change https://golang.org/cl/352689 mentions this issue: math/rand: update NewSource document

[gopherbot]

Change https://go.dev/cl/425974 mentions this issue: math/rand: document that Source returned by NewSource implements Source64