From 00e29bccb4576e007de78e41ca1c282908ceb7b9 Mon Sep 17 00:00:00 2001 From: Denis Bernard Date: Fri, 22 May 2020 01:51:54 +0200 Subject: [PATCH] Add licensing info and package level docs --- LICENSE | 24 +++++++++++ LICENSE-go | 27 ++++++++++++ dec.go | 4 ++ dec_arith.go | 4 ++ dec_arith_amd64.s | 2 +- dec_arith_decl.go | 4 ++ dec_arith_decl_pure.go | 4 ++ dec_arith_test.go | 4 ++ dec_conv.go | 4 ++ dec_conv_test.go | 2 +- dec_test.go | 2 +- decimal.go | 4 ++ decimal_conv.go | 4 ++ decimal_marsh.go | 2 +- decimal_sqrt.go | 4 ++ decimal_test.go | 4 ++ decimal_toa.go | 2 +- doc.go | 93 ++++++++++++++++++++++++++++++++++++++++++ stdlib.go | 6 ++- 19 files changed, 194 insertions(+), 6 deletions(-) create mode 100644 LICENSE create mode 100644 LICENSE-go create mode 100644 doc.go diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..cf24fb8 --- /dev/null +++ b/LICENSE @@ -0,0 +1,24 @@ +Copyright (c) 2020 Denis Bernard . All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met: + + * Redistributions of source code must retain the above copyright +notice, this list of conditions and the following disclaimer. + * Redistributions in binary form must reproduce the above +copyright notice, this list of conditions and the following disclaimer +in the documentation and/or other materials provided with the +distribution. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/LICENSE-go b/LICENSE-go new file mode 100644 index 0000000..6a66aea --- /dev/null +++ b/LICENSE-go @@ -0,0 +1,27 @@ +Copyright (c) 2009 The Go Authors. All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met: + + * Redistributions of source code must retain the above copyright +notice, this list of conditions and the following disclaimer. + * Redistributions in binary form must reproduce the above +copyright notice, this list of conditions and the following disclaimer +in the documentation and/or other materials provided with the +distribution. + * Neither the name of Google Inc. nor the names of its +contributors may be used to endorse or promote products derived from +this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/dec.go b/dec.go index 13dd108..09206b5 100644 --- a/dec.go +++ b/dec.go @@ -1,3 +1,7 @@ +// Copyright 2020 Denis Bernard . All rights reserved. +// Use of this source code is governed by a BSD-style +// license that can be found in the LICENSE file. + package decimal import ( diff --git a/dec_arith.go b/dec_arith.go index 39a87c2..783a5cc 100644 --- a/dec_arith.go +++ b/dec_arith.go @@ -1,3 +1,7 @@ +// Copyright 2020 Denis Bernard . All rights reserved. +// Use of this source code is governed by a BSD-style +// license that can be found in the LICENSE file. + package decimal import ( diff --git a/dec_arith_amd64.s b/dec_arith_amd64.s index beaad84..ab5dad2 100644 --- a/dec_arith_amd64.s +++ b/dec_arith_amd64.s @@ -1,4 +1,4 @@ -// Copyright 2009 The Go Authors. All rights reserved. +// Copyright 2020 Denis Bernard . All rights reserved. // Use of this source code is governed by a BSD-style // license that can be found in the LICENSE file. diff --git a/dec_arith_decl.go b/dec_arith_decl.go index 31d28f5..e1c817a 100644 --- a/dec_arith_decl.go +++ b/dec_arith_decl.go @@ -1,3 +1,7 @@ +// Copyright 2020 Denis Bernard . All rights reserved. +// Use of this source code is governed by a BSD-style +// license that can be found in the LICENSE file. + // +build !decimal_pure_go,amd64 package decimal diff --git a/dec_arith_decl_pure.go b/dec_arith_decl_pure.go index 7f54839..628aa74 100644 --- a/dec_arith_decl_pure.go +++ b/dec_arith_decl_pure.go @@ -1,3 +1,7 @@ +// Copyright 2020 Denis Bernard . All rights reserved. +// Use of this source code is governed by a BSD-style +// license that can be found in the LICENSE file. + // +build decimal_pure_go !amd64 package decimal diff --git a/dec_arith_test.go b/dec_arith_test.go index a736cab..e475a35 100644 --- a/dec_arith_test.go +++ b/dec_arith_test.go @@ -1,3 +1,7 @@ +// Copyright 2020 Denis Bernard . All rights reserved. +// Use of this source code is governed by a BSD-style +// license that can be found in the LICENSE file. + package decimal import ( diff --git a/dec_conv.go b/dec_conv.go index bb2147a..1c22a6f 100644 --- a/dec_conv.go +++ b/dec_conv.go @@ -1,3 +1,7 @@ +// Copyright 2020 Denis Bernard . All rights reserved. +// Use of this source code is governed by a BSD-style +// license that can be found in the LICENSE file. + package decimal import ( diff --git a/dec_conv_test.go b/dec_conv_test.go index bd06a24..479838d 100644 --- a/dec_conv_test.go +++ b/dec_conv_test.go @@ -1,4 +1,4 @@ -// Copyright 2015 The Go Authors. All rights reserved. +// Copyright 2020 Denis Bernard . All rights reserved. // Use of this source code is governed by a BSD-style // license that can be found in the LICENSE file. diff --git a/dec_test.go b/dec_test.go index 1fd4a87..1f5e33c 100644 --- a/dec_test.go +++ b/dec_test.go @@ -1,4 +1,4 @@ -// Copyright 2009 The Go Authors. All rights reserved. +// Copyright 2020 Denis Bernard . All rights reserved. // Use of this source code is governed by a BSD-style // license that can be found in the LICENSE file. diff --git a/decimal.go b/decimal.go index 7d21944..ae5a7f7 100644 --- a/decimal.go +++ b/decimal.go @@ -1,3 +1,7 @@ +// Copyright 2020 Denis Bernard . All rights reserved. +// Use of this source code is governed by a BSD-style +// license that can be found in the LICENSE file. + package decimal import ( diff --git a/decimal_conv.go b/decimal_conv.go index b9be357..7ecd4df 100644 --- a/decimal_conv.go +++ b/decimal_conv.go @@ -1,3 +1,7 @@ +// Copyright 2020 Denis Bernard . All rights reserved. +// Use of this source code is governed by a BSD-style +// license that can be found in the LICENSE file. + package decimal import ( diff --git a/decimal_marsh.go b/decimal_marsh.go index 2da2b3c..e89e328 100644 --- a/decimal_marsh.go +++ b/decimal_marsh.go @@ -1,4 +1,4 @@ -// Copyright 2015 The Go Authors. All rights reserved. +// Copyright 2020 Denis Bernard . All rights reserved. // Use of this source code is governed by a BSD-style // license that can be found in the LICENSE file. diff --git a/decimal_sqrt.go b/decimal_sqrt.go index 425e649..18978ed 100644 --- a/decimal_sqrt.go +++ b/decimal_sqrt.go @@ -1,3 +1,7 @@ +// Copyright 2020 Denis Bernard . All rights reserved. +// Use of this source code is governed by a BSD-style +// license that can be found in the LICENSE file. + package decimal import ( diff --git a/decimal_test.go b/decimal_test.go index 7847ec3..4ae2c1d 100644 --- a/decimal_test.go +++ b/decimal_test.go @@ -1,3 +1,7 @@ +// Copyright 2020 Denis Bernard . All rights reserved. +// Use of this source code is governed by a BSD-style +// license that can be found in the LICENSE file. + package decimal import ( diff --git a/decimal_toa.go b/decimal_toa.go index 173f570..c7e7660 100644 --- a/decimal_toa.go +++ b/decimal_toa.go @@ -1,4 +1,4 @@ -// Copyright 2015 The Go Authors. All rights reserved. +// Copyright 2020 Denis Bernard . All rights reserved. // Use of this source code is governed by a BSD-style // license that can be found in the LICENSE file. diff --git a/doc.go b/doc.go new file mode 100644 index 0000000..4b18d87 --- /dev/null +++ b/doc.go @@ -0,0 +1,93 @@ +// Copyright 2020 Denis Bernard . All rights reserved. +// Use of this source code is governed by a BSD-style +// license that can be found in the LICENSE file. + +/* +Package decimal implements arbitrary-precision decimal floating-point +arithmetic. + +The implementation is heavily based on big.Float and besides a few additional +getters and setters for other math/big types, the API is identical to that of +*big.Float. + +Howvever, and unlike big.Float, the mantissa of a decimal is stored in a +little-endian Word slice as "declets" of 9 or 19 decimal digits per 32 or 64 +bits Word. All arithmetic operations are performed directly in base 10**9 or +10**19 without conversion to/from binary. + +The zero value for a Decimal corresponds to 0. Thus, new values can be declared +in the usual ways and denote 0 without further initialization: + + x := new(Decimal) // x is a *Decimal of value 0 + +Alternatively, new Decimal values can be allocated and initialized with the +function: + + func NewDecimal(f float64) *Decimal + +For instance, NewDecimal(x) returns a *Decimal set to the value of the float64 +argument f. More flexibility is provided with explicit setters, for instance: + + z := new(Float).SetUint64(123) // z3 := 123.0 + +Setters, numeric operations and predicates are represented as methods of the +form: + + func (z *Decimal) SetV(v V) *Decimal // z = v + func (z *Decimal) Unary(x *Decimal) *Decimal // z = unary x + func (z *Decimal) Binary(x, y *Decimal) *Decimal // z = x binary y + func (x *Decimal) Pred() P // p = pred(x) + +For unary and binary operations, the 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 denotes the +result and the method arguments are the operation's operands. For instance, +given three *Decimal 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. + +(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 (*Decimal).Add are named x and y, and because +the receiver specifies the result destination, it is called z: + + func (z *Decimal) Add(x, y *Decimal) *Decimal + +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, +Decimal.Sign), simply return the result. In this case, the receiver is typically +the first operand, named x: + + func (x *Decimal) Sign() int + +Various methods support conversions between strings and corresponding numeric +values, and vice versa: Decimal implements the Stringer interface for a +(default) string representation of the value, but also provides SetString +methods to initialize a Decimal value from a string in a variety of supported +formats (see the SetString documentation). + +Finally, *Decimal satisfies the fmt package's Scanner interface for scanning and +the Formatter interface for formatted printing. +*/ +package decimal diff --git a/stdlib.go b/stdlib.go index 3865976..33bcf77 100644 --- a/stdlib.go +++ b/stdlib.go @@ -1,4 +1,8 @@ -// This file mirrors types and constants from math/big. +// Copyright 2020 Denis Bernard . All rights reserved. +// Use of this source code is governed by a BSD-style +// license that can be found in the LICENSE file. + +// This file mirrors constants, types and some internal functions from math/big. package decimal