Skip to content

Scanner doc & correctness cleanups#7

Open
killerra wants to merge 3 commits into
mainfrom
scanner-nits
Open

Scanner doc & correctness cleanups#7
killerra wants to merge 3 commits into
mainfrom
scanner-nits

Conversation

@killerra

@killerra killerra commented Jul 1, 2026

Copy link
Copy Markdown
Collaborator

Follow-up tidy-up after the merged scanner work. Five low-risk items — four documentation clarifications and one small defensive correctness fix. No behaviour change on any real binary.

Changes

docs(pattern): clarify Skip(0) and alternation capture semantics

  • Document that Skip(0) is the pelite-style "skip one pointer width" convention (resolved at scan time via the view's pointer size; target-dependent, not zero) and that the parser never emits it, so it's only reachable when building atoms programmatically.
  • Document alternation (Case/Break) capture semantics: a slot written only by an abandoned arm is rolled back to its initial value, so the save array does not tell you which arm matched — use a distinct per-arm Save slot to disambiguate.

docs(scanner): finds_prepared guidance + scratch borrow note

  • Note on finds_code that it re-analyses the pattern each call, and that repeated uniqueness scans should prepare_pattern once and use finds_prepared / finds_prepared_with.
  • Comment the field-split borrow of scratch in exec_backtracking (work_save vs. calls/save_log/stack), so a future refactor doesn't route those fields through a &mut self method and break the borrow check.

fix(scanner): terminate match iteration on cursor overflow

  • Matches::next advanced cursor with checked_add(1) and, on the u64::MAX boundary, left cursor = None, which restarts (and re-yields) the span. It now advances to the next range instead, matching the finds path's clean termination. This is unreachable with consistent views (mapped.len() == file.len() caps any match offset at u64::MAX - 1) and only matters for adversarial/synthetic views, so it's a defensive guard.

Verification

  • cargo test --workspace --all-targets --all-features + cargo test --workspace --doc — green.
  • cargo clippy --workspace --all-targets --all-features -- -D warnings -D clippy::all clean.
  • cargo fmt --all -- --check clean.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant