math/big: better doc string for Float.Copy, add example test

Fixes #66358.

Change-Id: Ic9bde88eabfb2a446d32e1dc5ac404a51ef49f11
Reviewed-on: https://go-review.googlesource.com/c/go/+/590635
Auto-Submit: Robert Griesemer <gri@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Ian Lance Taylor <iant@google.com>
Reviewed-by: Robert Griesemer <gri@google.com>

diff --git a/src/math/big/float.go b/src/math/big/float.go
index 0a2887cb5fe1c2cd105958d2c36debd3b5ddbdf5..51d557478138d3bc85b5968676997370a55ed8a3 100644 (file)
--- a/src/math/big/float.go
+++ b/src/math/big/float.go
@@ -672,9 +672,8 @@ func (z *Float) Set(x *Float) *Float {
        return z
 }
 
-// Copy sets z to x, with the same precision, rounding mode, and
-// accuracy as x, and returns z. x is not changed even if z and
-// x are the same.
+// Copy sets z to x, with the same precision, rounding mode, and accuracy as x.
+// Copy returns z. If x and z are identical, Copy is a no-op.
 func (z *Float) Copy(x *Float) *Float {
        if debugFloat {
                x.validate()

diff --git a/src/math/big/floatexample_test.go b/src/math/big/floatexample_test.go
index 0c6668c93bc592edafc9a826a877f19af1ca35bc..cdc124802af4096a7d93d50bff45391a1746e38c 100644 (file)
--- a/src/math/big/floatexample_test.go
+++ b/src/math/big/floatexample_test.go
@@ -139,3 +139,24 @@ func ExampleRoundingMode() {
        // -2.5             -2             -3      -2            -3             -3             -2
        // -2.6             -3             -3      -2            -3             -3             -2
 }
+
+func ExampleFloat_Copy() {
+       var x, z big.Float
+
+       x.SetFloat64(1.23)
+       r := z.Copy(&x)
+       fmt.Printf("a) r = %g, z = %g, x = %g, r == z = %v\n", r, &z, &x, r == &z)
+
+       // changing z changes r since they are identical
+       z.SetInt64(42)
+       fmt.Printf("b) r = %g, z = %g, r == z = %v\n", r, &z, r == &z)
+
+       x.SetPrec(1)
+       z.Copy(&x)
+       fmt.Printf("c) z = %g, x = %g, z == x = %v\n", &z, &x, &z == &x)
+
+       // Output:
+       // a) r = 1.23, z = 1.23, x = 1.23, r == z = true
+       // b) r = 42, z = 42, r == z = true
+       // c) z = 1, x = 1, z == x = false
+}