codekingpro/portable-devtools

1// Copyright 2009 The Go Authors. All rights reserved.2// Use of this source code is governed by a BSD-style3// license that can be found in the LICENSE file.4 5/*6Package big implements arbitrary-precision arithmetic (big numbers).7The following numeric types are supported:8 9	Int    signed integers10	Rat    rational numbers11	Float  floating-point numbers12 13The zero value for an [Int], [Rat], or [Float] correspond to 0. Thus, new14values can be declared in the usual ways and denote 0 without further15initialization:16 17	var x Int        // &x is an *Int of value 018	var r = &Rat{}   // r is a *Rat of value 019	y := new(Float)  // y is a *Float of value 020 21Alternatively, new values can be allocated and initialized with factory22functions of the form:23 24	func NewT(v V) *T25 26For instance, [NewInt](x) returns an *[Int] set to the value of the int6427argument x, [NewRat](a, b) returns a *[Rat] set to the fraction a/b where28a and b are int64 values, and [NewFloat](f) returns a *[Float] initialized29to the float64 argument f. More flexibility is provided with explicit30setters, for instance:31 32	var z1 Int33	z1.SetUint64(123)                 // z1 := 12334	z2 := new(Rat).SetFloat64(1.25)   // z2 := 5/435	z3 := new(Float).SetInt(z1)       // z3 := 123.036 37Setters, numeric operations and predicates are represented as methods of38the form:39 40	func (z *T) SetV(v V) *T          // z = v41	func (z *T) Unary(x *T) *T        // z = unary x42	func (z *T) Binary(x, y *T) *T    // z = x binary y43	func (x *T) Pred() P              // p = pred(x)44 45with T one of [Int], [Rat], or [Float]. For unary and binary operations, the46result is the receiver (usually named z in that case; see below); if it47is one of the operands x or y it may be safely overwritten (and its memory48reused).49 50Arithmetic expressions are typically written as a sequence of individual51method calls, with each call corresponding to an operation. The receiver52denotes the result and the method arguments are the operation's operands.53For instance, given three *Int values a, b and c, the invocation54 55	c.Add(a, b)56 57computes the sum a + b and stores the result in c, overwriting whatever58value was held in c before. Unless specified otherwise, operations permit59aliasing of parameters, so it is perfectly ok to write60 61	sum.Add(sum, x)62 63to accumulate values x in a sum.64 65(By always passing in a result value via the receiver, memory use can be66much better controlled. Instead of having to allocate new memory for each67result, an operation can reuse the space allocated for the result value,68and overwrite that value with the new result in the process.)69 70Notational convention: Incoming method parameters (including the receiver)71are named consistently in the API to clarify their use. Incoming operands72are usually named x, y, a, b, and so on, but never z. A parameter specifying73the result is named z (typically the receiver).74 75For instance, the arguments for (*Int).Add are named x and y, and because76the receiver specifies the result destination, it is called z:77 78	func (z *Int) Add(x, y *Int) *Int79 80Methods of this form typically return the incoming receiver as well, to81enable simple call chaining.82 83Methods which don't require a result value to be passed in (for instance,84[Int.Sign]), simply return the result. In this case, the receiver is typically85the first operand, named x:86 87	func (x *Int) Sign() int88 89Various methods support conversions between strings and corresponding90numeric values, and vice versa: *[Int], *[Rat], and *[Float] values implement91the Stringer interface for a (default) string representation of the value,92but also provide SetString methods to initialize a value from a string in93a variety of supported formats (see the respective SetString documentation).94 95Finally, *[Int], *[Rat], and *[Float] satisfy [fmt.Scanner] for scanning96and (except for *[Rat]) the Formatter interface for formatted printing.97*/98package big99