From: Robert Griesemer Date: Mon, 28 Sep 2015 20:39:04 +0000 (-0700) Subject: math/big: more documentation X-Git-Tag: go1.6beta1~961 X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=3b9e8bb7f214db90fb116d25d67161e7fb932d75;p=gostls13.git 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 --- diff --git a/src/math/big/doc.go b/src/math/big/doc.go index 71d2199f0c..a3c23751ba 100644 --- a/src/math/big/doc.go +++ b/src/math/big/doc.go @@ -10,25 +10,42 @@ The following numeric types are supported: 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 @@ aliasing of parameters, so it is perfectly ok to write 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 @@ Int.Sign), simply return the result. In this case, the receiver is typically 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 cea8f82ca9..b6f9993608 100644 --- a/src/math/big/floatconv_test.go +++ b/src/math/big/floatconv_test.go @@ -567,7 +567,6 @@ func TestFloatFormat(t *testing.T) { {"%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 0ed5f6fe9b..c5cdb5eb70 100644 --- a/src/math/big/ftoa.go +++ b/src/math/big/ftoa.go @@ -46,6 +46,7 @@ func (x *Float) Text(format byte, prec int) string { } // 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) }