[−][src]Crate visit_diff

Analyzing structural differences in Rust values using visitors.

Simple application

This crate provides three functions that you can use immediately without having to learn a bunch of traits.

debug_diff enables you to print the differences between two values of a Diff type using debug formatting.
any_difference and all_different scan values for differences and return a bool.

You can derive Diff for any custom type that implements Debug.

Under the hood

This scheme is modeled after a combination of core::fmt::Formatter and serde::Serialize. There are two main traits:

Diff is implemented by types that can be diff'd.
Differ is implemented by types that can process differences.

You'll typically derive Diff. Derived impls will simply present the structure of the type honestly, much like a derived Debug impl would. However, you can also implement it by hand if you need special functionality.

The most detailed docs are on the Differ trait.

Visitors

Together, Diff and Differ implement the Visitor Pattern for climbing over a data structure. This is a little different than some other applications of visitors you might have encountered. In particular:

The structure being visited is the Rust notion of types: here is a struct, the struct has fields, etc. A custom impl of Diff can fake the internals of a type to abstract away details, but the model is still the same.
Instead of visiting the parts of a single data structure, here we are visiting two data structures of the same type in parallel. This means we stop visiting if the structures diverge -- for example, if we discover two different variants of an enum type. (When this happens we notify the Differ through the difference method.)
The double dispatch aspect of the visitor pattern occurs at compile time, rather than at runtime, so there's very little overhead. The description of the pattern on Wikipedia (and the book Design Patterns that originated the name "visitor") doesn't discuss this version, only considering dyn-style runtime dispatch.

`no_std` support

This crate is no_std compatible, in case you want to diff data structures in a deeply-embedded system.

Modules

constant	A do-nothing differ that always winds up returning a fixed value.
record	Records a diff in a general data structure that can then be analyzed without knowledge of the original types involved.

Macros

assert_eq_diff

Replacement for the standard assert_eq! macro that prints a debug_diff between its arguments on failure.

Traits

Diff	A type that can be compared structurally to discover differences.
Differ	A type that can do something with information about structural differences.
MapDiffer	A type that can do something with information about differences in a map-like, key-value type.
SeqDiffer	A type that can do something with information about differences in a sequence, like a slice or `Vec`.
SetDiffer	A type that can do something with information about differences in a set-like sequence type, i.e. one in which elements are expected to be unique.
StructDiffer	A type that can deal with differences in a `struct`.
TupleDiffer	A type that can do something with information about differences in a tuple or tuple-like struct.

Functions

all_different	Checks if there is something different about every top-level part of `a` and `b`. For example, if every field of two structs has some difference.
any_difference	Checks for any difference between `a` and `b`.
debug_diff	Given two values that can be diffed, returns an object that will describe their differences when formatted using `Debug`.