Crate paircomp_core 

Raw-byte file inspection, prefix fingerprinting, and difference localization.

Each instance reads only its local file. The caller exchanges counts and compares fingerprints with the other instance; this crate handles file access and search state without terminal or network I/O.

Comparison workflow

1. Call inspect_file and compare the whole-file fingerprints. If they match, the comparison is complete.
2. On a mismatch, exchange line counts and construct a LineSearch. Use fingerprint_through_line for each requested comparison and pass the answer to LineSearch::record_result until the differing line is known.
3. To continue within that line, call inspect_line, exchange byte lengths (zero for an absent line), and construct a ByteSearch. Compare fingerprint_line_prefix results and call ByteSearch::record_result.
4. Optionally annotate the differing byte with utf8_character_position.

Both instances must use accurate counts and the same comparison answers. Localization also assumes that distinct prefixes have distinct fingerprints.

Bytes and positions

Hashing uses raw bytes without normalization or UTF-8 decoding. LF terminates a line and belongs to it; CR is ordinary content. A nonempty suffix after the last LF counts as a line, and a trailing LF creates no extra line.

Line, byte, and Unicode code-point positions start at 1. Only fingerprint_through_line accepts line zero, denoting an empty file prefix. Byte positions are relative to the selected line. Character annotations require that entire line to be valid UTF-8 and count code points, not grapheme clusters or visual columns.

File stability

Each file operation opens the supplied path afresh. The library does not snapshot files, lock them, or detect changes.

Both files must remain unchanged from the start of the initial inspection until the comparison ends, including during reads and between calls. If either file is edited or replaced, discard the collected metadata, fingerprints, and LineSearch/ByteSearch state, and restart both instances from the initial inspection.

Structs

ByteSearch

A deterministic search for the first differing byte within a differing line.

FileInfo

Metadata calculated from the bytes read from a regular file.

Fingerprint

A full 256-bit BLAKE3 digest of raw bytes.

LineInfo

Metadata for an existing line, including its terminating LF if present.

LineSearch

A deterministic search for the first differing line using file prefixes.

Enums

ByteSearchStep

A requested line-local prefix comparison, or the first differing byte.

Error

An error returned by a core operation.

LineSearchStep

A prefix comparison requested by LineSearch, or its completed result.

Functions

fingerprint_file

Fingerprints every raw byte of a regular file using BLAKE3.

fingerprint_line_prefix

Hashes only the first byte_count raw bytes of a 1-based line.

fingerprint_through_line

Fingerprints the file prefix through the selected line, including any LF.

inspect_file

Inspects a regular file without interpreting its bytes as text.

inspect_line

Inspects a 1-based line of a regular file.

utf8_character_position

Maps a 1-based byte position to a 1-based Unicode code-point position.