obitools4/autodoc/docmd/pkg_obifp.md

# `obifp`: Semantic Overview of Public API

The `obifp` package provides a family of fixed-size, arbitrary-precision unsigned integer types—`Uint64`, `Uint128`, and `Uint256`—designed for high-precision arithmetic where overflow safety, bitwise control, and type consistency are critical (e.g., cryptography, genomics with OBITools). All types share a unified interface (`FPUint[T]`) and enforce strict correctness via panics on overflow/underflow or division-by-zero.

## Core Principles

- **Explicit precision**: No silent truncation; narrowing casts emit warnings (via `obilog.Warnf`).
- **Panic-on-error semantics**: Arithmetic operations (`Add`, `Sub`, `Mul`, etc.) panic on overflow/underflow.
- **Bit-level fidelity**: Shifts and bitwise operations operate across full bit-width with carry propagation.

---

## Unified Interface: `FPUint[T]`

All three types (`Uint64`, `Uint128`, `Uint256`) implement this generic interface:

- **Construction & Initialization**
  - `Zero() T`: Returns the additive identity.
  - `Set64(v uint64) T`: Initializes from a native 64-bit value (zero-extended).
  - `OneUint[T]`: Helper to construct the value *1*.

- **Downcasting & Utility**
  - `AsUint64() uint64`: Extracts the least-significant limb (assumes higher limbs are zero; warns if not).
  - `IsZero() bool`: Checks for equality with zero.

- **Logical & Bitwise Operations**
  - `And(v T)`, `Or(v T)`, `Xor(v T)` — bitwise logic between two values of same type.
  - `Not() T` — inverts all bits (two’s complement style for unsigned).
  - `LeftShift(n uint) T`, `RightShift(n uint) T` — multi-limb shifts with carry handling; warns if shift ≥ full bit-width.

- **Arithmetic**
  - `Add(v T)`, `Sub(v T)` — with carry/borrow propagation; panics on overflow/underflow.
  - `Mul(v T)` — full-width multiplication (uses hardware-optimized limb-wise ops); panics on overflow.
  - *Division (`Div`, `Mod`) is implemented only for concrete types (see below).*

- **Comparison**
  - `Cmp(v T) int` — returns `-1`, `0`, or `+1`.
  - Overloaded operators: `<`, `<=`, `>`, `>=` (all returning `bool`).

---

## Concrete Types & Specialized Features

### ✅ `Uint64`
- Native Go `uint64` wrapper with strict overflow checking.
- Uses `math/bits.Add64`, `Mul64` internally for correctness.
- Supports conversion to larger types: `Uint128()`, `Uint256()`.

### ✅ `Uint128`
- Internally: two limbs (`w0`, `w1`).
- **Arithmetic**:
  - Full support: `Add(v)`, `Sub(v)`, `Mul(v)` (128×128), and scalar variants: `Add64`, `Mul64`.
  - Division & Modulo:
    - `Div(v)`, `Mod(v)` — integer division with remainder.
    - `QuoRem(v Uint128) (q, r Uint128)` — combined quotient/remainder.
    - `Div64`, `Mod64` for division by 64-bit scalar.
- **Bitwise**: Full support (`And`, `Or`, `Xor`, `Not`), plus shifts.
- **Conversion**:
  - Safe upcast to `Uint256`.
  - Downcast to `uint64` via `AsUint64()` (warns if high limb ≠ 0).

### ✅ `Uint256`
- Internally: four limbs (`w0` to `w3`) — supports values up to $2^{256} - 1$.
- **Arithmetic**:
  - `Add(v)`, `Sub(v)` — limb-wise with carry/borrow.
  - `Mul(v)` — schoolbook multiplication across limbs; panics on overflow.
  - `Div(v)`: Long division implementation (repeated subtraction of shifted multiples); panics on zero divisor.
- **Shifts**: Multi-limb shifts with carry propagation across all limbs.
- **Conversion**:
  - Downcast to `Uint128()` / `AsUint64()`, with overflow warnings.
  - Upcast from smaller types via implicit zero-extension.

---

## Helper Functions (Generic)

- `ZeroUint[T FPUint[T]]() T`: Returns zero for type parameter.
- `From64[T FPUint[T]](v uint64) T`: Converts native 64-bit to typed value.

All operations are **value-returning** (no in-place mutation), enabling fluent chaining and immutability.

> ⚠️ **Design Note**: Division methods are *not* part of the generic `FPUint[T]` interface (commented out), but are implemented concretely for each type. This reflects performance/complexity trade-offs and leaves room to extend later.