From: Robert Griesemer Date: Sat, 26 Sep 2015 05:26:52 +0000 (-0700) Subject: math/big: improved documentation X-Git-Tag: go1.6beta1~967 X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=3d4cd144cc1e6fb554b12695d0d190a2db0c6a2c;p=gostls13.git math/big: improved documentation - moved existing package documentation from nat.go to doc.go - expanded on it For #11241. Change-Id: Ie75a2b0178a8904a4154307a1f5080d7efc5489a Reviewed-on: https://go-review.googlesource.com/15042 Reviewed-by: Alan Donovan --- diff --git a/src/math/big/doc.go b/src/math/big/doc.go new file mode 100644 index 0000000000..71d2199f0c --- /dev/null +++ b/src/math/big/doc.go @@ -0,0 +1,72 @@ +// Copyright 2009 The Go Authors. All rights reserved. +// Use of this source code is governed by a BSD-style +// license that can be found in the LICENSE file. + +/* +Package big implements arbitrary-precision arithmetic (big numbers). +The following numeric types are supported: + + Int signed integers + 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: + + 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: + + 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) + +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). + +Arithmetic expressions are typically written as a sequence of individual +method calls, with each call corresponding to an operation. The receiver +denotes the result and the method arguments are the operation's operands. +For instance, given three *Int values a, b and c, the invocation + + c.Add(a, b) + +computes the sum a + b and stores the result in c, overwriting whatever +value was held in c before. Unless specified otherwise, operations permit +aliasing of parameters, so it is perfectly ok to write + + sum.Add(sum, x) + +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. + +Notational convention: Incoming method parameters (including the receiver) +are named consistently in the API to clarify their use. Incoming operands +are usually named x, y, a, b, and so on, but never z. A parameter specifying +the result is named z (typically the receiver). + +For instance, the arguments for (*Int).Add are named x and y, and because +the receiver specifies the result destination, it is called z: + + func (z *Int) Add(x, y *Int) *Int + +Methods of this form typically return the incoming receiver as well, to +enable simple call chaining. + +Methods which don't require a result value to be passed in (for instance, +Int.Sign), simply return the result. In this case, the receiver is typically +the first operand, named x: + + func (x *Int) Sign() int +*/ +package big diff --git a/src/math/big/nat.go b/src/math/big/nat.go index 6545bc17ed..121daec829 100644 --- a/src/math/big/nat.go +++ b/src/math/big/nat.go @@ -2,31 +2,11 @@ // Use of this source code is governed by a BSD-style // license that can be found in the LICENSE file. -// Package big implements multi-precision arithmetic (big numbers). -// The following numeric types are supported: -// -// Int signed integers -// Rat rational numbers -// Float floating-point numbers -// -// Methods are typically of the form: -// -// func (z *T) Unary(x *T) *T // z = op x -// func (z *T) Binary(x, y *T) *T // z = x op y -// func (x *T) M() T1 // v = x.M() -// -// 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 overwritten (and its memory reused). -// To enable chaining of operations, the result is also returned. Methods -// returning a result other than *Int, *Rat, or *Float take an operand as -// the receiver (usually named x in that case). -// -package big +// This file implements unsigned multi-precision integers (natural +// numbers). They are the building blocks for the implementation +// of signed integers, rationals, and floating-point numbers. -// This file contains operations on unsigned multi-precision integers. -// These are the building blocks for the operations on signed integers -// and rationals. +package big import "math/rand"