similar

similar is a dependency-free Rust crate that implements multiple diffing algorithms and granular diffing levels. It supports:

Algorithms

• Myers' diff
• Patience diff
• Hunt-style diff
• Histogram diff
• Classic LCS table diff

Diffing Granularity

• Line level
• Word level
• Character level
• Grapheme level

Data Types

• Text diffing
• Byte diffing
• Diffing on arbitrary comparable sequences
• Unified diff generation

The repository provides several specific diffing scenarios to test different library behaviors:

In version 3.0, TextDiff::iter_changes will panic if a DiffOp range is out of bounds. While iterating directly over diff.ops() is safe, you must manually validate any DiffOp values that are deserialized, transformed, or manually constructed.

Use the following pattern to validate that an operation is within the bounds of the TextDiff:

use similar::{DiffOp, TextDiff};

fn op_in_bounds(diff: &TextDiff<'_, '_, str>, op: &DiffOp) -> bool {
    let (_, old, new) = op.as_tag_tuple();
    old.end <= diff.old_len() && new.end <= diff.new_len()
}

The examples/diffs/ directory uses a consistent naming scheme designed for lexicographic glob expansion. This allows you to easily pair 'before' (old) and 'after' (new) files using patterns like caseNN.*.txt.

• Old files (before): caseNN.01.before_<scenario>.txt
• New files (after): caseNN.02.after_<scenario>.txt

When upgrading from version 2.7.x to 3.0, ensure your Rust toolchain is updated to 1.85 or newer. Key breaking changes include:

• std is now an explicit default feature. For no_std environments, you must disable default features.
• TextDiff slice accessors (old_slices() and new_slices()) have been replaced with new accessor APIs.
• TextDiff::iter_changes is stricter and will panic if a DiffOp range is out of bounds.
• TextDiff type annotations have a different lifetime shape.
• get_diff_ratio has been renamed to diff_ratio.
• Several constructors are now const and can be used in const contexts.

By default, similar enables std. If you are working in a no_std environment with an allocator, you must disable default features.

Depending on your requirements, you can choose between two backends for internal collections:

1. Default (BTreeMap): Use default-features = false to use alloc::collections::BTreeMap.
2. Hashbrown (HashMap): Use default-features = false, features = ["hashbrown"] to use hashbrown::HashMap.

[dependencies]
similar = { version = "3", default-features = false }

The Replace<D> struct is a DiffHook wrapper that optimizes diff results. It intercepts delete and insert events and, when they occur consecutively, combines them into a single replace event. This is useful for obtaining blocks of maximal length and ensuring a consistent order of operations. While the core text processing in similar may resolve these back to deletes and inserts, using Replace is recommended for consistent diff output.

To use it, wrap an existing DiffHook (such as Capture) using Replace::new(d).

The DiffInput<'a, T> enum is used by diffing APIs to accept both borrowed and owned text values efficiently. This prevents unnecessary allocations when the caller already owns the data or when working with slices.

• DiffInput::Borrowed(&'a T): Holds a reference to a DiffableStr.
• DiffInput::Owned(<T as ToOwned>::Owned): Holds an owned version of the DiffableStr.

You can retrieve the underlying DiffableStr reference using .as_diffable_str().

pub enum DiffInput<'a, T: DiffableStr + ?Sized> {
    Borrowed(&'a T),
    Owned(<T as ToOwned>::Owned),
}

impl<T: DiffableStr + ?Sized> DiffInput<'_, T> {
    pub fn as_diffable_str(&self) -> &T {
        match self {
            DiffInput::Borrowed(value) => value,
            DiffInput::Owned(value) => value.borrow(),
        }
    }
}

The InlineChangeMode enum determines how text is broken down into tokens during the second-level refinement process.

• Auto: Uses the crate default. If the unicode feature is enabled, it uses unicode words; otherwise, it uses whitespace-based words.
• Words: Tokenizes by whitespace runs and non-whitespace runs.
• Chars: Tokenizes by individual characters.
• UnicodeWords: Tokenizes by unicode words (requires unicode feature).
• Graphemes: Tokenizes by unicode grapheme clusters (requires unicode feature).

When performing line diffs, the library accounts for the fact that files may or may not end in a newline character.

• If a diff was created via TextDiff::from_lines, you can check TextDiff::newline_terminated() to see if the system is tracking missing newlines.
• Individual Change objects provide a missing_newline() method which returns true if the change is missing a trailing newline. This allows callers to render special markers like \ No newline at end of file in unified diffs.