doc.gno

 1// The int256 package provides a 256-bit signed interger type for gno,
 2// supporting arithmetic operations and bitwise manipulation.
 3//
 4// It designed for applications that require high-precision arithmetic
 5// beyond the standard 64-bit range.
 6//
 7// ## Features
 8//
 9//   - 256-bit Signed Integers: Support for large integer ranging from -2^255 to 2^255-1.
10//   - Two's Complement Representation: Efficient storage and computation using two's complement.
11//   - Arithmetic Operations: Add, Sub, Mul, Div, Mod, Inc, Dec, etc.
12//   - Bitwise Operations: And, Or, Xor, Not, etc.
13//   - Comparison Operations: Cmp, Eq, Lt, Gt, etc.
14//   - Conversion Functions: Int to Uint, Uint to Int, etc.
15//   - String Parsing and Formatting: Convert to and from decimal string representation.
16//
17// ## Notes
18//
19//   - Some methods may panic when encountering invalid inputs or overflows.
20//   - The `int256.Int` type can interact with `uint256.Uint` from the `p/demo/uint256` package.
21//   - Unlike `math/big.Int`, the `int256.Int` type has fixed size (256-bit) and does not support
22//     arbitrary precision arithmetic.
23//
24// # Division and modulus operations
25//
26// This package provides three different division and modulus operations:
27//
28//   - Div and Rem: Truncated division (T-division)
29//   - Quo and Mod: Floored division (F-division)
30//   - DivE and ModE: Euclidean division (E-division)
31//
32// Truncated division (Div, Rem) is the most common implementation in modern processors
33// and programming languages. It rounds quotients towards zero and the remainder
34// always has the same sign as the dividend.
35//
36// Floored division (Quo, Mod) always rounds quotients towards negative infinity.
37// This ensures that the modulus is always non-negative for a positive divisor,
38// which can be useful in certain algorithms.
39//
40// Euclidean division (DivE, ModE) ensures that the remainder is always non-negative,
41// regardless of the signs of the dividend and divisor. This has several mathematical
42// advantages:
43//
44//  1. It satisfies the unique division with remainder theorem.
45//  2. It preserves division and modulus properties for negative divisors.
46//  3. It allows for optimizations in divisions by powers of two.
47//
48// [+] Currently, ModE and Mod are shared the same implementation.
49//
50// ## Performance considerations:
51//
52//   - For most operations, the performance difference between these division types is negligible.
53//   - Euclidean division may require an extra comparison and potentially an addition,
54//     which could impact performance in extremely performance-critical scenarios.
55//   - For divisions by powers of two, Euclidean division can be optimized to use
56//     bitwise operations, potentially offering better performance.
57//
58// ## Usage guidelines:
59//
60//   - Use Div and Rem for general-purpose division that matches most common expectations.
61//   - Use Quo and Mod when you need a non-negative remainder for positive divisors,
62//     or when implementing algorithms that assume floored division.
63//   - Use DivE and ModE when you need the mathematical properties of Euclidean division,
64//     or when working with algorithms that specifically require it.
65//
66// Note: When working with negative numbers, be aware of the differences in behavior
67// between these division types, especially at the boundaries of integer ranges.
68//
69// ## References
70//
71// Daan Leijen, “Division and Modulus for Computer Scientists”:
72// https://www.microsoft.com/en-us/research/wp-content/uploads/2016/02/divmodnote-letter.pdf
73package int256