Ecosyste.ms: Packages

proxy.golang.org : github.com/govalues/decimal

Package decimal implements immutable decimal floating-point numbers. It is specifically designed for transactional financial systems and adheres to the principles set by ANSI X3.274-1996. Decimal is a struct with three fields: The numerical value of a decimal is calculated as follows: This approach allows the same numeric value to have multiple representations, for example, 1, 1.0, and 1.00, which represent the same value but have different scales and coefficients. The range of a decimal is determined by its scale. Here are the ranges for frequently used scales: Subnormal numbers are not supported to ensure peak performance. Consequently, decimals between -0.00000000000000000005 and 0.00000000000000000005 inclusive, are rounded to 0. Special values such as NaN, Infinity, or negative zeros are not supported. This ensures that arithmetic operations always produce either valid decimals or errors. Each arithmetic operation occurs in two steps: The operation is initially performed using uint64 arithmetic. If no overflow occurs, the exact result is immediately returned. If overflow occurs, the operation proceeds to step 2. The operation is repeated with increased precision using big.Int arithmetic. The result is then rounded to 19 digits. If no significant digits are lost during rounding, the inexact result is returned. If any significant digit is lost, an overflow error is returned. Step 1 improves performance by avoiding performance impact associated with big.Int arithmetic. It is expected that, in transactional financial systems, most arithmetic operations will compute an exact result during step 1. The following rules determine the significance of digits during step 2: Unlike many other decimal libraries, this package does not provide an explicit context. Instead, the context is implicit and can be approximately equated to the following settings: The equality of Etiny and Emin implies that this package does not support subnormal numbers. Implicit rounding is applied when a result exceeds 19 digits, rounding it to 19 digits using half-to-even rounding. This method ensures that rounding errors are evenly distributed between rounding up and down. For all arithmetic operations, except for Decimal.Pow and Decimal.PowExact, the result is the one that would be obtained by computing the exact mathematical result with infinite precision and then rounding it to 19 digits. Decimal.Pow and Decimal.PowExact may occasionally produce a result that is off by 1 unit in the last place. In addition to implicit rounding, the package provides several methods for explicit rounding: See the documentation for each method for more details. All methods are panic-free and pure. Errors are returned in the following cases: Division by Zero. Unlike the standard library, Decimal.Quo, Decimal.QuoRem, and Decimal.Inv do not panic when dividing by 0. Instead, they return an error. Invalid Operation. Decimal.Pow and Decimal.PowExact return an error if 0 is raised to a negative power. Overflow. Unlike standard integers, there is no "wrap around" for decimals at certain sizes. For out-of-range values, arithmetic operations return an error. Errors are not returned in the following cases: JSON. The package integrates seamlessly with standard encoding/json through the implementation of encoding.TextMarshaller and encoding.TextUnmarshaler interfaces. Here is an example structure: The package marshals decimals as quoted strings, ensuring the preservation of the exact numerical value. Here is an example OpenAPI schema: XML. The package integrates with standard encoding/xml via the implementation of encoding.TextMarshaller and encoding.TextUnmarshaler interfaces. Here is an example structure: "xs:decimal" type can be used to represent decimals in XML schema. It is possible to impose restrictions on the length of the decimals using the following type: Protocol Buffers. Protocol Buffers can represent decimals as numerical strings, preserving trailing zeros. To convert between numerical strings and decimals, use Parse and Decimal.String. Here is an example proto definition: Alternatively, decimals can be represented as two integers: one for the integer part and another for the fractional part. For conversion between this format and decimals, use NewFromInt64 and Decimal.Int64 with a scale argument equal to "9". Here is an example proto definition: SQL. The package integrates with the standard database/sql via the implementation of sql.Scanner and driver.Valuer interfaces. To ensure accurate preservation of decimal scales, it is essential to choose appropriate column types: Here are the reasons: For PostgreSQL, always use DECIMAL without precision or scale specifications (avoid DECIMAL(p) or DECIMAL(p, s)). DECIMAL accurately preserves the scale of decimals. In SQLite, prefer TEXT, since DECIMAL is just an alias for floating-point numbers. TEXT preserves the scale of decimals. In MySQL, use DECIMAL(19, d), as DECIMAL is just an alias for DECIMAL(10, 0). The disadvantage of this format is that MySQL automatically rescales all decimals: values with a scale exceeding "d" are rounded (using half away from zero), while those with a lower scale are padded with trailing zeros. To avoid automatic rescaling, consider using VARCHAR(22). This example demonstrates the advantage of decimals for financial calculations. It computes the sum 0.1 + 0.1 + 0.1 + 0.1 + 0.1 + 0.1 + 0.1 + 0.1 + 0.1 + 0.1. In decimal arithmetic, the result is exactly 1.0. In float64 arithmetic, the result slightly deviates from 1.0 due to binary floating-point representation. This example calculates an approximate value of π using the Leibniz formula. The Leibniz formula is an infinite series that converges to π/4, and is given by the equation: 1 - 1/3 + 1/5 - 1/7 + 1/9 - 1/11 + ... = π/4. This example computes the series up to the 500,000th term using decimal arithmetic and returns the approximate value of π. This example implements a simple calculator that evaluates mathematical expressions written in postfix notation. The calculator can handle basic arithmetic operations such as addition, subtraction, multiplication, and division.

Registry - Source - Documentation - JSON
purl: pkg:golang/github.com/govalues/decimal
Keywords: ansi-x3-274, decimal, financial, floating-point, general-decimal-arithmetic, go, golang, money
License: MIT
Latest release: 4 months ago
First release: about 1 year ago
Namespace: github.com/govalues
Dependent packages: 5
Stars: 21 on GitHub
Forks: 2 on GitHub
See more repository details: repos.ecosyste.ms
Last synced: 7 days ago

• Readme
• Versions 36
• Dependent Packages 5
• Maintainers 0