Go: math/rand: possibly ambiguous use of operator "^" in documentation

[admacro]

According to the doc here https://golang.org/pkg/math/rand/#Seed

Seed values that have the same remainder when divided by 2^31-1 generate the same pseudo-random sequence.

This means seed 29 and 57 will generate the same pseudo random sequence. But I get different results. Am I missing something?

What version of Go are you using (go version)?

$ go version
go version go1.13.4 darwin/amd64

Does this issue reproduce with the latest release?

Yes

What operating system and processor architecture are you using (go env)?

go env Output

$ go env

GO111MODULE=""

GOARCH="amd64"

GOBIN=""

GOCACHE="/Users/james/Library/Caches/go-build"

GOENV="/Users/james/Library/Application Support/go/env"

GOEXE=""

GOFLAGS=""

GOHOSTARCH="amd64"

GOHOSTOS="darwin"

GONOPROXY=""

GONOSUMDB=""

GOOS="darwin"

GOPATH="/Users/james/go"

GOPRIVATE=""

GOPROXY="https://proxy.golang.org,direct"

GOROOT="/usr/local/go"

GOSUMDB="sum.golang.org"

GOTMPDIR=""

GOTOOLDIR="/usr/local/go/pkg/tool/darwin_amd64"

GCCGO="gccgo"

AR="ar"

CC="clang"

CXX="clang++"

CGO_ENABLED="1"

GOMOD=""

CGO_CFLAGS="-g -O2"

CGO_CPPFLAGS=""

CGO_CXXFLAGS="-g -O2"

CGO_FFLAGS="-g -O2"

CGO_LDFLAGS="-g -O2"

PKG_CONFIG="pkg-config"

GOGCCFLAGS="-fPIC -m64 -pthread -fno-caret-diagnostics -Qunused-arguments -fmessage-length=0 -fdebug-prefix-map=/var/folders/sp/n3hrxcgd3wgb8zb_3mt1w9kr0000gn/T/go-build316781643=/tmp/go-build -gno-record-gcc-switches -fno-common"

What did you do?

https://play.golang.org/p/AoWrOyO2rOP

What did you expect to see?

same pseudo random sequence

What did you see instead?

different results with seed 29 and 57
29: 3
57: 4

[tmthrgd]

2^31-1 is two raised to the thirty-first power minus one, not two xor thirty-one minus one. That has a value of 2147483647 and not 28 as you have in the playground link. So both 29 and 57 have different remainders.

[ALTree]

What @tmthrgd said. The doc says that all numbers of form 2147483647·n + k (with fixed k) will generate the same sequence.

Closing here, since this is working as intended.

[admacro]

Hi @tmthrgd, and @ALTree Ok, and thank you for pointing this out. I actually had thought of the possibility of ^ being power operator rather than xor, but didn't give it a try out of laziness =_=. Do you think it worthy to eliminate possible future confusion on the notion of ^ by updating the expression 2^31-1 to an unambiguous form in the doc, for example 2147483647 (2^31-1) or simply 2147483647? Or there is a general agreement on "the notion of ^ in the doc" somewhere that I missed?

[ALTree]

Or there is a general agreement on "the notion of ^ in the doc" somewhere that I missed?

I guess it depends on the context. I admit it can be confusing, since in Go ^ is the bitwise xor, but on the other hand I think that in an expression like 2^31-1 it feels natural to read the 31 as an exponent so in practise most readers won't be confused.

We could make this completely unambiguous, maybe using proper unicode superscripts. There is some precedent:

• The ProbablyPrime doc says:

  ProbablyPrime is 100% accurate for inputs less than 2⁶⁴

• The Sqrt doc says:

  the largest integer such that z² ≤ x

So we already use unicode superscripts in some places in the documentation. We could change the rand doc to

Seed values that have the same remainder when divided by 2³¹-1

That would prevent any confusion.

Re-opening as a doc issue.

[admacro]

Ah yes, unicode superscript, like in math, perfect! Haven't thought of that. :-D

[go101]

Maybe 1<<32 - 1 is not also bad.

[rsc]

Please use the Unicode superscript like in all our other docs, not <<. Thanks.

[gopherbot]

Change https://golang.org/cl/209758 mentions this issue: math/rand: update comment to avoid use of ^ for exponentiation