math/big: shallow copies of Int/Rat/Float are not supported (documentation)
Fixes #28423.
Change-Id: Ie57ade565d0407a4bffaa86fb4475ff083168e79
Reviewed-on: https://go-review.googlesource.com/c/145537
Reviewed-by: Ian Lance Taylor <iant@golang.org>
diff --git a/src/math/big/float.go b/src/math/big/float.go
index 6b0cb3f..d5e801b 100644
--- a/src/math/big/float.go
+++ b/src/math/big/float.go
@@ -43,7 +43,7 @@
// precision of the argument with the largest precision value before any
// rounding takes place, and the rounding mode remains unchanged. Thus,
// uninitialized Floats provided as result arguments will have their
-// precision set to a reasonable value determined by the operands and
+// precision set to a reasonable value determined by the operands, and
// their mode is the zero value for RoundingMode (ToNearestEven).
//
// By setting the desired precision to 24 or 53 and using matching rounding
@@ -56,6 +56,12 @@
// The zero (uninitialized) value for a Float is ready to use and represents
// the number +0.0 exactly, with precision 0 and rounding mode ToNearestEven.
//
+// Operations always take pointer arguments (*Float) rather
+// than Float values, and each unique Float value requires
+// its own unique *Float pointer. To "copy" a Float value,
+// an existing (or newly allocated) Float must be set to
+// a new value using the Float.Set method; shallow copies
+// of Floats are not supported and may lead to errors.
type Float struct {
prec uint32
mode RoundingMode
diff --git a/src/math/big/int.go b/src/math/big/int.go
index 47a288a..dab9a5c 100644
--- a/src/math/big/int.go
+++ b/src/math/big/int.go
@@ -15,6 +15,13 @@
// An Int represents a signed multi-precision integer.
// The zero value for an Int represents the value 0.
+//
+// Operations always take pointer arguments (*Int) rather
+// than Int values, and each unique Int value requires
+// its own unique *Int pointer. To "copy" an Int value,
+// an existing (or newly allocated) Int must be set to
+// a new value using the Int.Set method; shallow copies
+// of Ints are not supported and may lead to errors.
type Int struct {
neg bool // sign
abs nat // absolute value of the integer
diff --git a/src/math/big/rat.go b/src/math/big/rat.go
index 46d58fc..5d0800c 100644
--- a/src/math/big/rat.go
+++ b/src/math/big/rat.go
@@ -13,6 +13,13 @@
// A Rat represents a quotient a/b of arbitrary precision.
// The zero value for a Rat represents the value 0.
+//
+// Operations always take pointer arguments (*Rat) rather
+// than Rat values, and each unique Rat value requires
+// its own unique *Rat pointer. To "copy" a Rat value,
+// an existing (or newly allocated) Rat must be set to
+// a new value using the Rat.Set method; shallow copies
+// of Rats are not supported and may lead to errors.
type Rat struct {
// To make zero values for Rat work w/o initialization,
// a zero value of b (len(b) == 0) acts like b == 1.
