^ ^                 ^ ^
=(o.o)=  ~byakuren  =(o.o)=
  m m                 m m

Arithmetic Internals

Code location: SUBSECTION 15.2 in flowlog.c.

Integer representation

Flowlog uses a two-tier integer model:

• Small integers: stored directly in pl_term as SLO (PL_TERM_INT).
• Big integers: heap-allocated pl_bigint (PL_TERM_BIGINT) when values do not fit in SLO.

Bigint layout

struct pl_bigint {
  int sign;      // -1, 0, +1
  ULO len;       // number of limbs
  uint32_t limbs[len];  // little-endian base-2^32 limbs
}

Notes: - Limbs are little-endian (limbs[0] is the least-significant 32 bits). - The base is 2^32, so each limb stores 32 bits. - Bigints are normalized: no leading zero limbs; zero is represented as sign=0, len=0.

Promotion and canonicalization

• Arithmetic on SLO uses overflow checks; on overflow, operands are promoted to pl_bigint.
• Results are canonicalized: if a pl_bigint fits in SLO, it is demoted back to PL_TERM_INT.
• This keeps current_prolog_flag(bounded,false) true while preserving fast paths for small integers.

Arithmetic operators

• +, -, *:
  • Use SLO fast paths with overflow detection.
  • Promote to bigints on overflow.
• Bigint * uses schoolbook multiplication for small limb counts and Karatsuba for larger operands.
• ^ (power) uses exponentiation by squaring, with a specialized bigint squaring fast path (switches to Karatsuba at large sizes).
• // and rem use truncation toward zero.
• div and mod use floor division (ISO behavior).
• Bigint division uses a normalized long-division algorithm (Knuth-style, base-2^32).

Shifts and bitwise operators

• << shifts left by inserting zero bits.
• >> shifts right using floor semantics for negative values (consistent with div by powers of two).
• Bitwise ops (/\\, \\/, xor, \\) operate on a fixed-width two’s-complement view:
  • Width = max(bit_length(|A|), bit_length(|B|)) + 1
  • Operands are converted to two’s-complement arrays, operated on, then converted back.
  • When both operands are non-negative, Flowlog skips the two’s-complement step and operates directly on limbs.

Parsing and printing

• number_chars/2 and number_codes/2 parse decimal digits into SLO or pl_bigint as needed.
• Bigint printing uses base-10 chunking (1e9 per chunk) via repeated division for stability and speed.

Floating-point interop

• Integer-to-float conversion (num_as_double) attempts exact conversion; very large values map to ±HUGE_VAL.
• Float arithmetic follows ISO rules and uses double.

Memory and parallel safety

• Bigints are allocated via Flowlog’s pool allocator, so they share the same lifetime model as other terms.
• Operations do not mutate inputs; they allocate new bigints for results.
• Division normalization and two’s-complement conversions reuse thread-local scratch buffers to avoid per-call heap churn; buffers grow to the largest size seen on that thread.

Potential future optimizations

• Use larger limbs (e.g., 64-bit) on 64-bit platforms to reduce limb count. (slower in testing)
• Tune Karatsuba thresholds or add Toom/FFT multiplication for very large numbers.
• Tune scratch buffer growth limits or add a small free-list for base-10 chunk buffers.