Kind Pure package
Name v0
Namespace onbloc / int256
Exported functions n/a — not supported for pure packages by the node (vm/qfuncs)
Module gno.land/p/onbloc/int256/v0
gno 0.9 doc.gno 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 not supported for pure packages by the node (vm/qfuncs)
Signatures reconstructed verbatim from vm/qfuncs — interface params keep their inline definitions.
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
73 package int256
74