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 6b0cb3f1edd7e331ed3db2639376950121017a1e..d5e801b2c8939519126461c695de640e95f86680 100644 (file)
--- a/src/math/big/float.go
+++ b/src/math/big/float.go
@@ -43,7 +43,7 @@ const debugFloat = false // enable for debugging
 // 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 @@ const debugFloat = false // enable for debugging
 // 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 47a288ab44d87db42e754bf6e3078cab1f89ad6a..dab9a5cc0f7e689c6c75ebf0814268d3f8493ed2 100644 (file)
--- a/src/math/big/int.go
+++ b/src/math/big/int.go
@@ -15,6 +15,13 @@ import (
 
 // 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 46d58fcf365d29c501a0340538989caec9c9bedc..5d0800ca936b2952016f60b90bcd760a674d6c6a 100644 (file)
--- a/src/math/big/rat.go
+++ b/src/math/big/rat.go
@@ -13,6 +13,13 @@ import (
 
 // 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.