Class Decimal256

core/src/main/java/io/questdb/std/Decimal256.java:27–2952

Decimal256 - a mutable decimal number implementation. The value is a signed number with two's complement representation. This class represents decimal numbers with a fixed scale (number of decimal places) using 256-bit integer arithmetic for precise calculations. All operations are performed in-

 * </p>
 */
public class Decimal256 implements Sinkable, Decimal {
    public static final int BYTES = 32;
    /**
     * Maximum allowed scale (number of decimal places)
     */
    public static final int MAX_SCALE = 76;
    public static final Decimal256 MAX_VALUE = new Decimal256(1593091911132452277L, 532749306367912313L, 8607968719199866879L, -1L, 0); // 10⁷⁶ - 1
    public static final Decimal256 MIN_VALUE = new Decimal256(-1593091911132452278L, -532749306367912314L, -8607968719199866880L, 1L, 0); // -10⁷⁶ + 1
    public static final Decimal256 NULL_VALUE = new Decimal256(Decimals.DECIMAL256_HH_NULL, Decimals.DECIMAL256_HL_NULL, Decimals.DECIMAL256_LH_NULL, Decimals.DECIMAL256_LL_NULL, 0);
    public static final Decimal256 ZERO = new Decimal256(0, 0, 0, 0, 0);
    // @formatter:off
    /**
     * Pre-computed powers of 10 table for decimal arithmetic.
     * Autogenerated. See `Decimal256Test.testPowersTenTable`.
     *
     * <p>
     * This table stores the 256-bit representation of powers of 10 (10^0 to 10^76)
     * multiplied by digits 1-9. Each row contains 9 complete 256-bit values, where
     * each 256-bit value is represented as 4 consecutive 64-bit longs:
     * - HH (bits 255-192, most significant 64 bits)
     * - HL (bits 191-128)
     * - LH (bits 127-64)
     * - LL (bits 63-0, least significant 64 bits)
     *
     * <p>
     * Structure: table[power][multiplier_offset + component]
     * - power: power of 10 (0 = 10^0, 1 = 10^1, ..., 76 = 10^76)
     * - multiplier_offset: (multiplier-1) * 4, where multiplier ∈ [1,9]
     * - component: 0=HH, 1=HL, 2=LH, 3=LL
     *
     * <p>
     * Example: To get 7 × 10^25:
     * - Row: table[25]
     * - Offset: (7-1) * 4 = 24
     * - Access: HH=table[25][24], HL=table[25][25], LH=table[25][26], LL=table[25][27]
     * - Value: (HH << 192) | (HL << 128) | (LH << 64) | LL
     *
     * <p>
     * This pre-computation enables fast multiplication by avoiding expensive
     * 256-bit arithmetic during decimal parsing and scaling operations.
     */
    private static final long[][] POWERS_TEN_TABLE = new long[][]{
            {0L, 0L, 0L, 1L, 0L, 0L, 0L, 2L, 0L, 0L, 0L, 3L, 0L, 0L, 0L, 4L, 0L, 0L, 0L, 5L, 0L, 0L, 0L, 6L, 0L, 0L, 0L, 7L, 0L, 0L, 0L, 8L, 0L, 0L, 0L, 9L},
            {0L, 0L, 0L, 10L, 0L, 0L, 0L, 20L, 0L, 0L, 0L, 30L, 0L, 0L, 0L, 40L, 0L, 0L, 0L, 50L, 0L, 0L, 0L, 60L, 0L, 0L, 0L, 70L, 0L, 0L, 0L, 80L, 0L, 0L, 0L, 90L},
            {0L, 0L, 0L, 100L, 0L, 0L, 0L, 200L, 0L, 0L, 0L, 300L, 0L, 0L, 0L, 400L, 0L, 0L, 0L, 500L, 0L, 0L, 0L, 600L, 0L, 0L, 0L, 700L, 0L, 0L, 0L, 800L, 0L, 0L, 0L, 900L},
            {0L, 0L, 0L, 1000L, 0L, 0L, 0L, 2000L, 0L, 0L, 0L, 3000L, 0L, 0L, 0L, 4000L, 0L, 0L, 0L, 5000L, 0L, 0L, 0L, 6000L, 0L, 0L, 0L, 7000L, 0L, 0L, 0L, 8000L, 0L, 0L, 0L, 9000L},
            {0L, 0L, 0L, 10000L, 0L, 0L, 0L, 20000L, 0L, 0L, 0L, 30000L, 0L, 0L, 0L, 40000L, 0L, 0L, 0L, 50000L, 0L, 0L, 0L, 60000L, 0L, 0L, 0L, 70000L, 0L, 0L, 0L, 80000L, 0L, 0L, 0L, 90000L},
            {0L, 0L, 0L, 100000L, 0L, 0L, 0L, 200000L, 0L, 0L, 0L, 300000L, 0L, 0L, 0L, 400000L, 0L, 0L, 0L, 500000L, 0L, 0L, 0L, 600000L, 0L, 0L, 0L, 700000L, 0L, 0L, 0L, 800000L, 0L, 0L, 0L, 900000L},
            {0L, 0L, 0L, 1000000L, 0L, 0L, 0L, 2000000L, 0L, 0L, 0L, 3000000L, 0L, 0L, 0L, 4000000L, 0L, 0L, 0L, 5000000L, 0L, 0L, 0L, 6000000L, 0L, 0L, 0L, 7000000L, 0L, 0L, 0L, 8000000L, 0L, 0L, 0L, 9000000L},
            {0L, 0L, 0L, 10000000L, 0L, 0L, 0L, 20000000L, 0L, 0L, 0L, 30000000L, 0L, 0L, 0L, 40000000L, 0L, 0L, 0L, 50000000L, 0L, 0L, 0L, 60000000L, 0L, 0L, 0L, 70000000L, 0L, 0L, 0L, 80000000L, 0L, 0L, 0L, 90000000L},
            {0L, 0L, 0L, 100000000L, 0L, 0L, 0L, 200000000L, 0L, 0L, 0L, 300000000L, 0L, 0L, 0L, 400000000L, 0L, 0L, 0L, 500000000L, 0L, 0L, 0L, 600000000L, 0L, 0L, 0L, 700000000L, 0L, 0L, 0L, 800000000L, 0L, 0L, 0L, 900000000L},
            {0L, 0L, 0L, 1000000000L, 0L, 0L, 0L, 2000000000L, 0L, 0L, 0L, 3000000000L, 0L, 0L, 0L, 4000000000L, 0L, 0L, 0L, 5000000000L, 0L, 0L, 0L, 6000000000L, 0L, 0L, 0L, 7000000000L, 0L, 0L, 0L, 8000000000L, 0L, 0L, 0L, 9000000000L},
            {0L, 0L, 0L, 10000000000L, 0L, 0L, 0L, 20000000000L, 0L, 0L, 0L, 30000000000L, 0L, 0L, 0L, 40000000000L, 0L, 0L, 0L, 50000000000L, 0L, 0L, 0L, 60000000000L, 0L, 0L, 0L, 70000000000L, 0L, 0L, 0L, 80000000000L, 0L, 0L, 0L, 90000000000L},
            {0L, 0L, 0L, 100000000000L, 0L, 0L, 0L, 200000000000L, 0L, 0L, 0L, 300000000000L, 0L, 0L, 0L, 400000000000L, 0L, 0L, 0L, 500000000000L, 0L, 0L, 0L, 600000000000L, 0L, 0L, 0L, 700000000000L, 0L, 0L, 0L, 800000000000L, 0L, 0L, 0L, 900000000000L},
            {0L, 0L, 0L, 1000000000000L, 0L, 0L, 0L, 2000000000000L, 0L, 0L, 0L, 3000000000000L, 0L, 0L, 0L, 4000000000000L, 0L, 0L, 0L, 5000000000000L, 0L, 0L, 0L, 6000000000000L, 0L, 0L, 0L, 7000000000000L, 0L, 0L, 0L, 8000000000000L, 0L, 0L, 0L, 9000000000000L},
            {0L, 0L, 0L, 10000000000000L, 0L, 0L, 0L, 20000000000000L, 0L, 0L, 0L, 30000000000000L, 0L, 0L, 0L, 40000000000000L, 0L, 0L, 0L, 50000000000000L, 0L, 0L, 0L, 60000000000000L, 0L, 0L, 0L, 70000000000000L, 0L, 0L, 0L, 80000000000000L, 0L, 0L, 0L, 90000000000000L},
            {0L, 0L, 0L, 100000000000000L, 0L, 0L, 0L, 200000000000000L, 0L, 0L, 0L, 300000000000000L, 0L, 0L, 0L, 400000000000000L, 0L, 0L, 0L, 500000000000000L, 0L, 0L, 0L, 600000000000000L, 0L, 0L, 0L, 700000000000000L, 0L, 0L, 0L, 800000000000000L, 0L, 0L, 0L, 900000000000000L},
            {0L, 0L, 0L, 1000000000000000L, 0L, 0L, 0L, 2000000000000000L, 0L, 0L, 0L, 3000000000000000L, 0L, 0L, 0L, 4000000000000000L, 0L, 0L, 0L, 5000000000000000L, 0L, 0L, 0L, 6000000000000000L, 0L, 0L, 0L, 7000000000000000L, 0L, 0L, 0L, 8000000000000000L, 0L, 0L, 0L, 9000000000000000L},