1// Copyright 2009 The Go Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style
3// 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 integers
10	Rat    rational numbers
11	Float  floating-point numbers
12
13The zero value for an [Int], [Rat], or [Float] correspond to 0. Thus, new
14values can be declared in the usual ways and denote 0 without further
15initialization:
16
17	var x Int        // &x is an *Int of value 0
18	var r = &Rat{}   // r is a *Rat of value 0
19	y := new(Float)  // y is a *Float of value 0
20
21Alternatively, new values can be allocated and initialized with factory
22functions of the form:
23
24	func NewT(v V) *T
25
26For instance, [NewInt](x) returns an *[Int] set to the value of the int64
27argument x, [NewRat](a, b) returns a *[Rat] set to the fraction a/b where
28a and b are int64 values, and [NewFloat](f) returns a *[Float] initialized
29to the float64 argument f. More flexibility is provided with explicit
30setters, for instance:
31
32	var z1 Int
33	z1.SetUint64(123)                 // z1 := 123
34	z2 := new(Rat).SetFloat64(1.25)   // z2 := 5/4
35	z3 := new(Float).SetInt(z1)       // z3 := 123.0
36
37Setters, numeric operations and predicates are represented as methods of
38the form:
39
40	func (z *T) SetV(v V) *T          // z = v
41	func (z *T) Unary(x *T) *T        // z = unary x
42	func (z *T) Binary(x, y *T) *T    // z = x binary y
43	func (x *T) Pred() P              // p = pred(x)
44
45with T one of [Int], [Rat], or [Float]. For unary and binary operations, the
46result is the receiver (usually named z in that case; see below); if it
47is one of the operands x or y it may be safely overwritten (and its memory
48reused).
49
50Arithmetic expressions are typically written as a sequence of individual
51method calls, with each call corresponding to an operation. The receiver
52denotes the result and the method arguments are the operation's operands.
53For instance, given three *Int values a, b and c, the invocation
54
55	c.Add(a, b)
56
57computes the sum a + b and stores the result in c, overwriting whatever
58value was held in c before. Unless specified otherwise, operations permit
59aliasing of parameters, so it is perfectly ok to write
60
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 be
66much better controlled. Instead of having to allocate new memory for each
67result, 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 operands
72are usually named x, y, a, b, and so on, but never z. A parameter specifying
73the result is named z (typically the receiver).
74
75For instance, the arguments for (*Int).Add are named x and y, and because
76the receiver specifies the result destination, it is called z:
77
78	func (z *Int) Add(x, y *Int) *Int
79
80Methods of this form typically return the incoming receiver as well, to
81enable 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 typically
85the first operand, named x:
86
87	func (x *Int) Sign() int
88
89Various methods support conversions between strings and corresponding
90numeric values, and vice versa: *[Int], *[Rat], and *[Float] values implement
91the Stringer interface for a (default) string representation of the value,
92but also provide SetString methods to initialize a value from a string in
93a variety of supported formats (see the respective SetString documentation).
94
95Finally, *[Int], *[Rat], and *[Float] satisfy [fmt.Scanner] for scanning
96and (except for *[Rat]) the Formatter interface for formatted printing.
97*/
98package big
99