java-diff-utils-rs

Experimental preview release of a Rust port of the core diffing and patching behavior behind java-diff-utils.

This project aims to provide Java-compatible diff semantics in a safe, idiomatic Rust implementation while keeping the public API approachable for users who want patch generation, text diffing, and unified diff support without unsafe Rust code.

Release status

This is an experimental alpha release.

The crate is intended for early adopters and maintainers who want to evaluate the Rust port against the upstream Java project. The public API is intentionally focused on correctness and parity rather than making unsupported speed claims. Performance benchmarking is ongoing and the long-running algorithm benchmark is kept ignored by default so normal test runs stay fast.

Overview

This crate includes:

• MyersDiff: classic quadratic-space Myers algorithm
• MyersDiffWithLinearSpace: linear-space Myers variant for larger inputs
• HistogramDiff: anchor-based diff path with fallback behavior for tricky sequences
• patch generation and application helpers
• unified diff parsing and writing support
• inline and side-by-side diff row generation

The project is structured around a small set of clearly separated layers:

• src/algorithm/: diff algorithm implementations and factories
• src/patch/: deltas, chunk verification, and patch application
• src/text/: diff row generation and string utilities
• src/unifieddiff/: unified diff readers and writers
• src/diff_utils.rs: public convenience helpers and default selection points

Safety and idiomatic constraints

The crate intentionally enforces a no-unsafe policy:

• #![forbid(unsafe_code)] at the crate root and binary entry points
• no raw pointer arithmetic or unsafe memory aliasing
• explicit ownership and borrowing patterns
• bounded, predictable workspace allocation strategies

Quick start

use java_diff_utils_rs::{DiffUtils, HistogramDiff, MyersDiff};
use java_diff_utils_rs::algorithm::DiffAlgorithm;

let original = vec!["A", "B", "C", "D"];
let revised = vec!["A", "X", "C", "D"];

let changes = MyersDiff::default().diff(&original, &revised);
let patch = java_diff_utils_rs::Patch::generate(&original, &revised, &changes, false);
let applied = patch.apply_to(&original).unwrap();
assert_eq!(applied, revised);

let histogram_changes = HistogramDiff::new().diff(&original, &revised);
assert!(!histogram_changes.is_empty());

Upstream Java parity check

The port was validated against the official java-diff-utils reference library in Docker using the same representative edit scenario.

Java reference output:

delta_count=1
CHANGE src=1:1 tgt=1:1

The Rust implementation matches the same semantic result for the equivalent diff case.

Performance notes

The implementation is designed to balance correctness and efficiency, but this project does not yet make a blanket claim that it is faster than Java. Performance measurement is ongoing, and the long-running algorithm benchmark is intentionally ignored by default so the standard validation loop stays practical for day-to-day development.

Benchmarking

Use Criterion to compare the available algorithms when you want to run the longer benchmark intentionally:

cargo bench --bench myers_diff

The benchmark exercises:

• public API diffing
• Myers quadratic vs linear-space behavior
• histogram diff behavior on similar and pathological inputs

Testing

The detailed test matrix and validation commands live in TESTS.md.

The standard project verification command is:

cargo test --quiet

License

This project is licensed under the Apache License, Version 2.0. See the LICENSE file for details.