math/big: more documentation
Good enough for now.
Fixes #11241.
Change-Id: Ieb50809f104d20bcbe14daecac503f72486bec92
Reviewed-on: https://go-review.googlesource.com/15111
Reviewed-by: Alan Donovan <adonovan@google.com>
diff --git a/src/math/big/doc.go b/src/math/big/doc.go
index 71d2199..a3c2375 100644
--- a/src/math/big/doc.go
+++ b/src/math/big/doc.go
@@ -10,25 +10,42 @@
Rat rational numbers
Float floating-point numbers
-Declaration: The zero value for an Int, Rat, or Float (not the pointers
-*Int, *Rat, *Float!) correspond to 0. Thus, new values can be declared
-in the usual ways and denote 0 without further initialization:
+The zero value for an Int, Rat, or Float correspond to 0. Thus, new
+values can be declared in the usual ways and denote 0 without further
+initialization:
var x Int // &x is an *Int of value 0
var r = &Rat{} // r is a *Rat of value 0
y := new(Float) // y is a *Float of value 0
-Arithmetic: Setters, numeric operations and predicates are represented
-as methods of the form:
+Alternatively, new values can be allocated and initialized with factory
+functions of the form:
+
+ func NewT(v V) *T
+
+For instance, NewInt(x) returns an *Int set to the value of the int64
+argument x, NewRat(a, b) returns a *Rat set to the fraction a/b where
+a and b are int64 values, and NewFloat(f) returns a *Float initialized
+to the float64 argument f. More flexibility is provided with explicit
+setters, for instance:
+
+ var z1 Int
+ z1.SetUint64(123) // z1 := 123
+ z2 := new(Rat).SetFloat64(1.2) // z2 := 6/5
+ z3 := new(Float).SetInt(z1) // z3 := 123.0
+
+Setters, numeric operations and predicates are represented as methods of
+the form:
func (z *T) SetV(v V) *T // z = v
func (z *T) Unary(x *T) *T // z = unary x
func (z *T) Binary(x, y *T) *T // z = x binary y
- func (x *T) Pred() T1 // v = pred(x)
+ func (x *T) Pred() P // p = pred(x)
with T one of Int, Rat, or Float. For unary and binary operations, the
-result is the receiver (usually named z in that case); if it is one of
-the operands x or y it may be safely overwritten (and its memory reused).
+result is the receiver (usually named z in that case; see below); if it
+is one of the operands x or y it may be safely overwritten (and its memory
+reused).
Arithmetic expressions are typically written as a sequence of individual
method calls, with each call corresponding to an operation. The receiver
@@ -45,10 +62,10 @@
to accumulate values x in a sum.
-Rationale: By always passing in a result value via the receiver, memory
-use can be much better controlled. Instead of having to allocate new memory
-for each result, an operation can reuse the space allocated for the result
-value, and overwrite that value with the new result in the process.
+(By always passing in a result value via the receiver, memory use can be
+much better controlled. Instead of having to allocate new memory for each
+result, an operation can reuse the space allocated for the result value,
+and overwrite that value with the new result in the process.)
Notational convention: Incoming method parameters (including the receiver)
are named consistently in the API to clarify their use. Incoming operands
@@ -68,5 +85,15 @@
the first operand, named x:
func (x *Int) Sign() int
+
+Various methods support conversions between strings and corresponding
+numeric values, and vice versa: *Int, *Rat, and *Float values implement
+the Stringer interface for a (default) string representation of the value,
+but also provide SetString methods to initialize a value from a string in
+a variety of supported formats (see the respective SetString documentation).
+
+Finally, *Int, *Rat, and *Float satisfy the fmt package's Scanner interface
+for scanning and (except for *Rat) the Formatter interface for formatted
+printing.
*/
package big
diff --git a/src/math/big/floatconv_test.go b/src/math/big/floatconv_test.go
index cea8f82..b6f9993 100644
--- a/src/math/big/floatconv_test.go
+++ b/src/math/big/floatconv_test.go
@@ -567,7 +567,6 @@
{"%v", -1e-9, "-1e-09"},
{"%v", float32(-1e-9), "-1e-09"},
{"%010v", 0.0, "0000000000"},
- {"%010v", 0.0, "0000000000"},
// *Float cases
{"%.20f", "1e-20", "0.00000000000000000001"},
diff --git a/src/math/big/ftoa.go b/src/math/big/ftoa.go
index 0ed5f6f..c5cdb5e 100644
--- a/src/math/big/ftoa.go
+++ b/src/math/big/ftoa.go
@@ -46,6 +46,7 @@
}
// String formats x like x.Text('g', 10).
+// (String must be called explicitly, Float.Format does not support %s verb.)
func (x *Float) String() string {
return x.Text('g', 10)
}
