htoprs — Documentation
Description: htoprs — a faithful Rust port of htop, the interactive process viewer. The htop 3.5.1 C source is the spec; every function under src/ported/ ports a specific htop C function, cited by File.c:line, enforced by a build-time port-purity gate.

## >_HTOPRS

The htop C source is the spec. htoprs is a faithful Rust port of htop, the interactive process viewer. The upstream C is translated function-for-function, never reimplemented from scratch. Every function under `src/ported/` ports a specific htop C function and cites its origin (`<File>.c:<line>`) in its doc comment.

## Porting methodology

Spec | htop 3.5.1 at `~/forkedRepos/htop` (131 `.c` files, platform-split darwin / linux / freebsd / …)
Port tree | `src/ported/<file>.rs` — one Rust module per C file; each `fn` cites `/// Port of` its `<File>.c:<line>` origin
Port-purity gate | `build.rs` checks every free `fn` name under `src/ported/` against the htop C-function snapshot; a name with no C counterpart fails the build. Cannot be bypassed by `cargo test --test X`
C-name snapshot | `tests/data/htop_c_fn_names.txt`, regenerated by `tests/data/extract_c_fn_names.sh` after pulling upstream htop
Allowlist | `tests/data/fake_fn_allowlist.txt` — genuine Rust-only architectural helpers only, each justified
Port report | `scripts/gen_port_report.py` → port_report.html, per-file + overall coverage derived from source at run time

## Ported so far — `XUtils.c`

htop's string and math utility layer. The pure string/math functions port faithfully; the C allocation wrappers, null-terminated helpers, varargs formatters, and `String_freeArray` have no faithful safe-Rust analog (Rust owns its allocation, bounds, and lifetimes) and are intentionally not ported.

`String_cat` | concatenation
`String_trim` | trims leading/trailing space, tab, newline (only those three)
`String_split` | splits on a separator; interior empties kept, trailing empty dropped
`String_splitFirst` | splits on the first separator only
`String_contains_i` | case-insensitive substring; pipe-separated multi-needle mode
`compareRealNumbers` | NaN-aware ordering (NaN sorts first)
`sumPositiveValues` | sum of strictly-positive values, NaN skipped
`countDigits` | digit count in a given base, with overflow guard
`countTrailingZeros` | mod-37 lowest-set-bit table

## Build & test

    cargo build          # runs the port-purity gate
    cargo test           # hand-crafted unit tests pin the C edge behavior
    python3 scripts/gen_port_report.py   # regenerate docs/port_report.html

The snapshot is regenerated with `HTOP_C_SOURCE=~/forkedRepos/htop tests/data/extract_c_fn_names.sh` after pulling new upstream htop commits.

## The MenkeTechnologies stack

htoprs follows the same faithful-port precedent as zshrs (the first compiled Unix shell, a 1:1 port of zsh's C). Browse the rest via the MenkeTechnologiesMeta umbrella repo.