treediff

https://docs.rs/treediff
Admin
A Rust crate that implements a generic diff algorithm to detect changes in arbitrary data structures...
Tokens:15,656
Snippets:192
Trust Score:9.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### Delegate added Method

Source: https://docs.rs/treediff/latest/treediff/trait.Delegate.html

Called when a Value `v` at Key `k` should be added. The Key provided is partial and should be combined with the recorded Keys from `push`.

```rust
fn added<'b>(&mut self, _k: &'b K, _v: &'a V) { ... }
```

--------------------------------

### Key Enum Trait Implementations

Source: https://docs.rs/treediff/latest/treediff/value/enum.Key.html

Lists and describes the trait implementations for the Key enum, including Clone, Debug, Display, Ord, PartialEq, and PartialOrd.

```APIDOC
## Trait Implementations

### impl Clone for Key

#### fn clone(&self) -> Key

Returns a duplicate of the value.

#### fn clone_from(&mut self, source: &Self)

Performs copy-assignment from `source`.

### impl Debug for Key

#### fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

### impl Display for Key

#### fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

### impl Ord for Key

#### fn cmp(&self, other: &Key) -> Ordering

This method returns an `Ordering` between `self` and `other`.

#### fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

#### fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

#### fn clamp(self, min: Self, max: Self) -> Self

Restrict a value to a certain interval.

### impl PartialEq for Key

#### fn eq(&self, other: &Key) -> bool

Tests for `self` and `other` values to be equal, and is used by `==`.

#### fn ne(&self, other: &Rhs) -> bool

Tests for `!=`.

### impl PartialOrd for Key

#### fn partial_cmp(&self, other: &Key) -> Option<Ordering>

This method returns an ordering between `self` and `other` values if one exists.

#### fn lt(&self, other: &Rhs) -> bool

Tests less than (for `self` and `other`) and is used by the `<` operator.

#### fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for `self` and `other`) and is used by the `<=` operator.

#### fn gt(&self, other: &Rhs) -> bool

Tests greater than (for `self` and `other`) and is used by the `>` operator.

#### fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for `self` and `other`) and is used by the `>=` operator.

### impl Eq for Key

### impl StructuralPartialEq for Key
```

--------------------------------

### Recorder Delegate push Method

Source: https://docs.rs/treediff/latest/treediff/tools/struct.Recorder.html

Records a `push` operation, indicating recursion into a Value at a given Key.

```rust
fn push(&mut self, k: &K)
```

--------------------------------

### Helper function mk

Source: https://docs.rs/treediff/latest/src/treediff/tools/record.rs.html

A helper function to create a new key path vector by appending a key to an existing cursor. It clones the key if provided.

```rust
fn mk<K>(c: &[K], k: Option<&K>) -> Vec<K>
where
    K: Clone,
{
    let mut c = Vec::from(c);
    match k {
        Some(k) => {
            c.push(k.clone());
            c
        }
        None => c,
    }
}
```

--------------------------------

### Delegate push Method

Source: https://docs.rs/treediff/latest/treediff/trait.Delegate.html

Called when recursing into a Value at a given Key. Delegates should use this to memoize the current Key path.

```rust
fn push(&mut self, _k: &K) { ... }
```

--------------------------------

### Recorder Default Implementation

Source: https://docs.rs/treediff/latest/src/treediff/tools/record.rs.html

Provides a default implementation for `Recorder`, initializing the cursor and calls list as empty vectors.

```rust
impl<'a, K, V> Default for Recorder<'a, K, V> {
    fn default() -> Self {
        Recorder {
            cursor: Vec::new(),
            calls: Vec::new(),
        }
    }
}
```

--------------------------------

### Recorder StructuralPartialEq Implementation

Source: https://docs.rs/treediff/latest/treediff/tools/struct.Recorder.html

Indicates that `Recorder` implements `StructuralPartialEq`.

```rust
impl<'a, K, V: 'a> StructuralPartialEq for Recorder<'a, K, V>
```

--------------------------------

### Recorder Delegate added Method

Source: https://docs.rs/treediff/latest/treediff/tools/struct.Recorder.html

Records an `added` operation, indicating that a Value at a given Key should be added.

```rust
fn added<'b>(&mut self, k: &'b K, v: &'a V)
```

--------------------------------

### Merger::from (impl From<V> for Merger)

Source: https://docs.rs/treediff/latest/src/treediff/tools/merge.rs.html

Creates a new Merger instance from an initial value `v`, using the `DefaultMutableFilter`.

```APIDOC
## Merger::from

### Description
Returns a new merger with the given initial value `v`, and the `DefaultMutableFilter`.

### Signature
`fn from(v: V) -> Self`

### Parameters
- **v** (V) - The initial value for the merger.
```

--------------------------------

### Define Key Enum and Display Implementation

Source: https://docs.rs/treediff/latest/src/treediff/value/shared.rs.html

Defines the `Key` enum for array indices and string keys, and implements `fmt::Display` for formatted output. Use this for representing keys in data structures.

```rust
use std::fmt;

/// A representation of all key types typical Value types will assume.
#[derive(Debug, Clone, PartialEq, Eq, Ord, PartialOrd)]
pub enum Key {
    /// An array index
    Index(usize),
    /// A string index for mappings
    String(String),
}

impl fmt::Display for Key {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        match *self {
            Key::String(ref v) => v.fmt(f),
            Key::Index(ref v) => v.fmt(f),
        }
    }
}
```

--------------------------------

### Create Merger with Custom Filter

Source: https://docs.rs/treediff/latest/src/treediff/tools/merge.rs.html

Constructs a new `Merger` instance with a specified initial value and a custom filter function. This is useful when you need fine-grained control over the merging process.

```rust
pub fn with_filter(v: V, f: BF) -> Self {
        Merger {
            inner: v,
            cursor: Vec::new(),
            filter: f,
            _d: PhantomData,
        }
    }
```

--------------------------------

### Recorder Delegate Implementation

Source: https://docs.rs/treediff/latest/src/treediff/tools/record.rs.html

Implements the `Delegate` trait for `Recorder`. This allows the `Recorder` to capture diff events like `push`, `pop`, `removed`, `added`, `unchanged`, and `modified`.

```rust
impl<'a, K, V> Delegate<'a, K, V> for Recorder<'a, K, V>
where
    K: Clone,
{
    fn push(&mut self, k: &K) {
        self.cursor.push(k.clone())
    }
    fn pop(&mut self) {
        self.cursor.pop();
    }
    fn removed<'b>(&mut self, k: &'b K, v: &'a V) {
        self.calls
            .push(ChangeType::Removed(mk(&self.cursor, Some(k)), v));
    }
    fn added<'b>(&mut self, k: &'b K, v: &'a V) {
        self.calls
            .push(ChangeType::Added(mk(&self.cursor, Some(k)), v));
    }
    fn unchanged<'b>(&mut self, v: &'a V) {
        self.calls
            .push(ChangeType::Unchanged(self.cursor.clone(), v));
    }
    fn modified<'b>(&mut self, v1: &'a V, v2: &'a V) {
        self.calls
            .push(ChangeType::Modified(mk(&self.cursor, None), v1, v2));
    }
}
```

--------------------------------

### Recorder PartialEq Implementation

Source: https://docs.rs/treediff/latest/treediff/tools/struct.Recorder.html

Implements the `PartialEq` trait for `Recorder`, enabling equality comparisons between two `Recorder` instances.

```rust
fn eq(&self, other: &Recorder<'a, K, V>) -> bool
```

--------------------------------

### Delegate pop Method

Source: https://docs.rs/treediff/latest/treediff/trait.Delegate.html

Called after processing all items within an object previously pushed. Used to leave the current key path.

```rust
fn pop(&mut self) { ... }
```

--------------------------------

### Merger Utility Methods

Source: https://docs.rs/treediff/latest/src/treediff/tools/merge.rs.html

Provides methods for interacting with the Merger, such as consuming it to retrieve the inner value, and accessing the mutable or immutable filter.

```rust
impl<K, V, BF, F> Merger<K, V, BF, F> {
    /// Consume the merger and return the contained target Value, which is the result of the
    /// merge operation.
    pub fn into_inner(self) -> V {
        self.inner
    }

    /// Returns a mutable borrow to the `MutableFilter` instance
    pub fn filter_mut(&mut self) -> &mut BF {
        &mut self.filter
    }

    /// Returns a borrow to the `MutableFilter` instance
    pub fn filter(&self) -> &BF {
        &self.filter
    }
}
```

--------------------------------

### Key Enum Variants

Source: https://docs.rs/treediff/latest/treediff/value/enum.Key.html

Details the variants of the Key enum, explaining their purpose.

```APIDOC
## Variants

### Index(usize)

An array index

### String(String)

A string index for mappings
```

--------------------------------

### Merger Methods

Source: https://docs.rs/treediff/latest/treediff/tools/struct.Merger.html

Provides methods for consuming the merger, accessing its filter instances, and creating new Merger instances.

```APIDOC
## impl<K, V, BF, F> Merger<K, V, BF, F>

### `into_inner`

Consume the merger and return the contained target Value, which is the result of the merge operation.

```rust
pub fn into_inner(self) -> V
```

### `filter_mut`

Returns a mutable borrow to the `MutableFilter` instance.

```rust
pub fn filter_mut(&mut self) -> &mut BF
```

### `filter`

Returns a borrow to the `MutableFilter` instance.

```rust
pub fn filter(&self) -> &BF
```
```

```APIDOC
## impl<'a, V, BF, F> Merger<V::Key, V, BF, F>

### `with_filter`

Return a new Merger with the given initial value `v` and the filter `f`.

```rust
pub fn with_filter(v: V, f: BF) -> Self
```
```

```APIDOC
## impl<'a, V> From<V> for Merger<V::Key, V, DefaultMutableFilter, DefaultMutableFilter>

### `from`

Return a new merger with the given initial value `v`, and the `DefaultMutableFilter`.

```rust
fn from(v: V) -> Self
```
```

--------------------------------

### Merger::from Constructor

Source: https://docs.rs/treediff/latest/treediff/tools/struct.Merger.html

Creates a new Merger instance with a given initial value and the `DefaultMutableFilter`. This is a convenient constructor for common use cases.

```rust
fn from(v: V) -> Self
```

--------------------------------

### Merger::with_filter

Source: https://docs.rs/treediff/latest/src/treediff/tools/merge.rs.html

Creates a new Merger instance with a specified initial value and a custom filter.

```APIDOC
## Merger::with_filter

### Description
Returns a new Merger with the given initial value `v` and the filter `f`.

### Signature
`pub fn with_filter(v: V, f: BF) -> Self`

### Parameters
- **v** (V) - The initial value for the merger.
- **f** (BF) - The filter to be used by the merger.
```

--------------------------------

### Recorder Delegate Methods

Source: https://docs.rs/treediff/latest/treediff/tools/struct.Recorder.html

Implements the Delegate trait for Recorder, defining methods for recording changes during a diff.

```APIDOC
```rust
impl<'a, K, V> Delegate<'a, K, V> for Recorder<'a, K, V>
where
    K: Clone,
{
    fn push(&mut self, k: &K) {
        // ... recurse into the Value at the given Key.
    }

    fn pop(&mut self) {
        // ... processed all items and leave the object previously pushed.
    }

    fn removed<'b>(&mut self, k: &'b K, v: &'a V) {
        // ... the Value v at the given Key k should be removed.
    }

    fn added<'b>(&mut self, k: &'b K, v: &'a V) {
        // ... the Value v at the given Key k should be added.
    }

    fn unchanged<'b>(&mut self, v: &'a V) {
        // The Value v was not changed.
    }

    fn modified<'b>(&mut self, v1: &'a V, v2: &'a V) {
        // ... the old Value was modified, and is now the new Value.
    }
}
```
```

--------------------------------

### Key Enum Definition

Source: https://docs.rs/treediff/latest/treediff/value/enum.Key.html

Defines the Key enum with its variants: Index and String.

```APIDOC
## Enum Key

### Summary
```
pub enum Key {
    Index(usize),
    String(String),
}
```

A representation of all key types typical Value types will assume.
```

--------------------------------

### Delegate removed Method

Source: https://docs.rs/treediff/latest/treediff/trait.Delegate.html

Called when a Value `v` at Key `k` should be removed. The Key provided is partial and should be combined with the recorded Keys from `push`.

```rust
fn removed<'b>(&mut self, _k: &'b K, _v: &'a V) { ... }
```

--------------------------------

### TryInto::try_into Implementation

Source: https://docs.rs/treediff/latest/treediff/tools/struct.Merger.html

Implements the `try_into` method for the `TryInto` trait, performing a conversion that may fail. This is the inverse of `try_from`.

```rust
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
```

--------------------------------

### Recorder Delegate pop Method

Source: https://docs.rs/treediff/latest/treediff/tools/struct.Recorder.html

Records a `pop` operation, signifying the completion of processing for a previously pushed object.

```rust
fn pop(&mut self)
```

--------------------------------

### Recorder Struct

Source: https://docs.rs/treediff/latest/src/treediff/tools/record.rs.html

A delegate implementation that records all calls made to it. It's useful for obtaining a flat list of all results from a diff operation without implementing a custom delegate.

```APIDOC
/// A `Delegate` to record all calls made to it.
///
/// It can be useful if you don't want to implement your own custom delegate, but instead just want
/// to quickly see a flat list of all results of the `diff` run.
///
/// # Examples
/// Please see the [tests][tests] for how to use this type.
///
/// [tests]: https://github.com/Byron/treediff-rs/blob/master/tests/diff.rs#L21
#[derive(Debug, PartialEq)]
pub struct Recorder<'a, K, V: 'a> {
    cursor: Vec<K>,
    /// A list of all calls the `diff` function made on us.
    pub calls: Vec<ChangeType<'a, K, V>>,
}
```

--------------------------------

### Merger::with_filter Constructor

Source: https://docs.rs/treediff/latest/treediff/tools/struct.Merger.html

Creates a new Merger instance with a given initial value and a mutable filter. This constructor is used when you need to provide a custom mutable filter.

```rust
pub fn with_filter(v: V, f: BF) -> Self
```

--------------------------------

### resolve_removal

Source: https://docs.rs/treediff/latest/treediff/tools/trait.MutableFilter.html

Called during `Delegate::removed(...)`, returns `None` to allow the Value at the `keys` path to be removed, or any Value to be set in its place instead. `removed` is the Value which is to be removed. `_target` provides access to the target of the merge operation.

```APIDOC
## fn resolve_removal<'a, K: Clone + Display, V: Clone>(
    &mut self,
    _keys: &[K],
    _removed: &'a V,
    _target: &mut V,
) -> Option<Cow<'a, V>>

### Description
Called during `Delegate::removed(...)`, returns `None` to allow the Value at the `keys` path to be removed, or any Value to be set in its place instead.
`removed` is the Value which is to be removed. `_target` provides access to the target of the merge operation.

### Parameters
- `_keys`: &[K] - The keys path.
- `_removed`: &'a V - The value which is to be removed.
- `_target`: &mut V - Provides access to the target of the merge operation.

### Returns
- `Option<Cow<'a, V>>` - `None` to allow removal, or `Some(Cow<'a, V>)` to set a new value instead.
```

--------------------------------

### Recorder Debug Formatting

Source: https://docs.rs/treediff/latest/treediff/tools/struct.Recorder.html

Implements the `Debug` trait for `Recorder` to allow formatted output for debugging.

```rust
fn fmt(&self, f: &mut Formatter<'_>) -> Result
```

--------------------------------

### Appended Helper Function

Source: https://docs.rs/treediff/latest/src/treediff/tools/merge.rs.html

A utility function to create a new vector of keys by appending an optional key to an existing slice of keys. Used internally by the Merger.

```rust
fn appended<K>(keys: &[K], k: Option<&K>) -> Vec<K>
where
    K: Clone,
{
    let mut keys = Vec::from(keys);
    if let Some(k) = k {
        keys.push(k.clone());
    }
    keys
}
```

--------------------------------

### resolve_removal Method

Source: https://docs.rs/treediff/latest/treediff/tools/trait.MutableFilter.html

Called during Delegate::removed. Returns None to allow removal or Some(Value) to replace the removed value. `removed` is the value to be removed, and `_target` provides access to the merge target.

```rust
fn resolve_removal<'a, K: Clone + Display, V: Clone>(
        &mut self,
        _keys: &[K],
        _removed: &'a V,
        _target: &mut V,
    ) -> Option<Cow<'a, V>>
```

--------------------------------

### resolve_conflict Method

Source: https://docs.rs/treediff/latest/treediff/tools/trait.MutableFilter.html

Called during Delegate::modified. Returns None to remove the value or Some(Value) to set a new value at the specified keys. `old` is the previous value, `new` is the current value, and `_target` provides access to the merge target.

```rust
fn resolve_conflict<'a, K: Clone + Display, V: Clone>(
        &mut self,
        _keys: &[K],
        _old: &'a V,
        new: &'a V,
        _target: &mut V,
    ) -> Option<Cow<'a, V>>
```

--------------------------------

### Delegate Trait Implementation for Merger

Source: https://docs.rs/treediff/latest/treediff/tools/struct.Merger.html

Implements the Delegate trait for Merger, defining how to handle push, pop, removed, added, unchanged, and modified operations during a diff merge.

```APIDOC
## impl<'a, K, V, F, BF> Delegate<'a, K, V> for Merger<K, V, BF, F>

### `push`

Recurse into the `Value` at the given `Key`.

```rust
fn push(&mut self, k: &K)
```

### `pop`

Process all items and leave the object previously `push`ed.

```rust
fn pop(&mut self)
```

### `removed`

Indicates that the Value `v` at the given Key `k` should be removed.

```rust
fn removed<'b>(&mut self, k: &'b K, v: &'a V)
```

### `added`

Indicates that the Value `v` at the given Key `k` should be added.

```rust
fn added<'b>(&mut self, k: &'b K, v: &'a V)
```

### `unchanged`

Indicates that the Value `v` was not changed.

```rust
fn unchanged<'b>(&mut self, v: &'a V)
```

### `modified`

Indicates that the `old` Value was modified, and is now the `new` Value.

```rust
fn modified<'b>(&mut self, old: &'a V, new: &'a V)
```
```

--------------------------------

### TryFrom Trait Implementation for DefaultMutableFilter

Source: https://docs.rs/treediff/latest/treediff/tools/struct.DefaultMutableFilter.html

Provides the try_from method as required by the TryFrom trait. This method attempts to convert a value into DefaultMutableFilter, returning a Result.

```rust
type Error = Infallible;
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
```

--------------------------------

### Merger AsRef Implementation

Source: https://docs.rs/treediff/latest/src/treediff/tools/merge.rs.html

Implements the AsRef trait for Merger, allowing it to be treated as a reference to its inner target value.

```rust
impl<K, V, BF, F> AsRef<V> for Merger<K, V, BF, F> {
    fn as_ref(&self) -> &V {
        &self.inner
    }
}
```

--------------------------------

### Generic Diff Algorithm for Value Types

Source: https://docs.rs/treediff/latest/src/treediff/diff.rs.html

This function recursively compares two `Value` types to find differences. It handles scalar values and complex structures (objects/maps). Use this when you need to compare tree-like data structures and report changes via a delegate.

```rust
use crate::traitdef::{Delegate, Value};
use std::{cmp::Ordering, collections::BTreeSet};

/// A generic diff algorithm suitable for `Value` types as seen in serialization/deserialization
/// libraries.
///
/// Such types can represent any tree-like data structure, which will be traversed to find
/// *additions*, *removals*, *modifications* and even portions that did not change at all.
///
/// # Parameters
/// * `l` - the left Value
/// * `r` - the right Value
/// * `d` - a `Delegate` to receive information about changes between `l` and `r`
pub fn diff<'a, V, D>(l: &'a V, r: &'a V, d: &mut D)
where
    V: Value<Item = V>,
    V::Key: Ord + Clone,
    D: Delegate<'a, V::Key, V>,
{
    match (l.items(), r.items()) {
        // two scalars, equal
        (None, None) if l == r => d.unchanged(l),
        // two scalars, different
        (None, None) => d.modified(l, r),
        // two objects, equal
        (Some(_), Some(_)) if l == r => d.unchanged(l),
        // object and scalar
        (Some(_), None) | (None, Some(_)) => d.modified(l, r),
        // two objects, different
        (Some(li), Some(ri)) => {
            let mut sl: BTreeSet<OrdByKey<_, _>> = BTreeSet::new();
            sl.extend(li.map(Into::into));
            let mut sr: BTreeSet<OrdByKey<_, _>> = BTreeSet::new();
            sr.extend(ri.map(Into::into));
            for k in sr.intersection(&sl) {
                let v1 = sl.get(k).expect("intersection to work");
                let v2 = sr.get(k).expect("intersection to work");
                d.push(&k.0);
                diff(v1.1, v2.1, d);
                d.pop();
            }
            for k in sr.difference(&sl) {
                d.added(&k.0, sr.get(k).expect("difference to work").1);
            }
            for k in sl.difference(&sr) {
                d.removed(&k.0, sl.get(k).expect("difference to work").1);
            }
        }
    }
}
```

--------------------------------

### TryInto Trait Implementation for DefaultMutableFilter

Source: https://docs.rs/treediff/latest/treediff/tools/struct.DefaultMutableFilter.html

Provides the try_into method as required by the TryInto trait. This method attempts to convert DefaultMutableFilter into another type, returning a Result.

```rust
type Error = <U as TryFrom<T>>::Error;
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
```

--------------------------------

### Treediff Value Module Structure

Source: https://docs.rs/treediff/latest/src/treediff/value/mod.rs.html

This snippet shows the module structure for treediff's value implementations. It highlights how different serialization libraries are conditionally compiled using feature flags.

```rust
1//! Contains all implementations of the `Value` and `Mutable` traits.
2//!
3//! Note that these are behind feature flags.
4mod shared;
5pub use self::shared::*;

#[cfg(feature = "with-rustc-serialize")]
mod rustc_json;

#[cfg(feature = "with-serde-json")]
mod serde_json;

#[cfg(feature = "with-serde-yaml")]
mod serde_yaml;

#[cfg(feature = "with-yaml-rust")]
mod yaml_rust;

```

--------------------------------

### From Trait Implementation for DefaultMutableFilter

Source: https://docs.rs/treediff/latest/treediff/tools/struct.DefaultMutableFilter.html

Provides the from method as required by the From trait. This implementation simply returns the argument unchanged, as DefaultMutableFilter is a unit type.

```rust
fn from(t: T) -> T
```

--------------------------------

### Merger Delegate Implementation

Source: https://docs.rs/treediff/latest/src/treediff/tools/merge.rs.html

Implements the Delegate trait for the Merger struct. This allows the Merger to process diff operations like push, pop, removed, added, unchanged, and modified by interacting with the inner target object and the filter.

```rust
impl<'a, K, V, F, BF> Delegate<'a, K, V> for Merger<K, V, BF, F>
where
    V: Mutable<Key = K, Item = V> + Clone + 'a,
    K: Clone + Display,
    F: MutableFilter,
    BF: BorrowMut<F>,
{
    fn push(&mut self, k: &K) {
        self.cursor.push(k.clone());
    }
    fn pop(&mut self) {
        self.cursor.pop();
    }
    fn removed<'b>(&mut self, k: &'b K, v: &'a V) {
        let keys = appended(&self.cursor, Some(k));
        match self
            .filter
            .borrow_mut()
            .resolve_removal(&keys, v, &mut self.inner)
        {
            Some(nv) => self.inner.set(&keys, &nv),
            None => self.inner.remove(&keys),
        }
    }
    fn added<'b>(&mut self, k: &'b K, v: &'a V) {
        self.inner.set(&appended(&self.cursor, Some(k)), v);
    }
    fn unchanged<'b>(&mut self, v: &'a V) {
        self.inner.set(&self.cursor, v)
    }
    fn modified<'b>(&mut self, old: &'a V, new: &'a V) {
        let keys = appended(&self.cursor, None);
        match self
            .filter
            .borrow_mut()
            .resolve_conflict(&keys, old, new, &mut self.inner)
        {
            Some(v) => self.inner.set(&keys, &v),
            None => self.inner.remove(&keys),
        }
    }
}
```

--------------------------------

### Recorder Delegate removed Method

Source: https://docs.rs/treediff/latest/treediff/tools/struct.Recorder.html

Records a `removed` operation, indicating that a Value at a given Key should be removed.

```rust
fn removed<'b>(&mut self, k: &'b K, v: &'a V)
```

--------------------------------

### Delegate modified Method

Source: https://docs.rs/treediff/latest/treediff/trait.Delegate.html

Called when a Value has been modified, providing both the old and new Values.

```rust
fn modified(&mut self, _old: &'a V, _new: &'a V) { ... }
```

--------------------------------

### TryFrom::try_from Implementation

Source: https://docs.rs/treediff/latest/treediff/tools/struct.Merger.html

Implements the `try_from` method for the `TryFrom` trait, performing a conversion that may fail. The associated `Error` type is `Infallible`.

```rust
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
```

--------------------------------

### Merger Struct

Source: https://docs.rs/treediff/latest/treediff/tools/struct.Merger.html

Represents a Merger that wraps a target object and applies changes based on the diff algorithm. Custom resolver functions can be provided for flexible merge operations.

```APIDOC
## Struct Merger

```rust
pub struct Merger<K, V, BF, F> { /* private fields */ }
```

A `Delegate` which applies differences to a target object. It wraps the target object and applies all calls by the `diff` algorithm to it, which changes it in some way. Custom resolver functions can be provided to arbitrarily alter the way the merge is performed. This allows you, for example, to keep your own meta-data, or to implement custom conflict resolutions.
```

--------------------------------

### Helper Struct for Ordered Keys

Source: https://docs.rs/treediff/latest/src/treediff/diff.rs.html

The `OrdByKey` struct is used internally by the `diff` function to allow keys to be ordered within a `BTreeSet`. It wraps a key and a reference to a value, implementing necessary traits for comparison.

```rust
struct OrdByKey<'a, K, V: 'a>(pub K, pub &'a V);

impl<'a, K, V> From<(K, &'a V)> for OrdByKey<'a, K, V> {
    fn from(src: (K, &'a V)) -> Self {
        OrdByKey(src.0, src.1)
    }
}

impl<'a, K, V> Eq for OrdByKey<'a, K, V> where K: Eq + PartialOrd {}

impl<'a, K, V> PartialEq for OrdByKey<'a, K, V>
where
    K: PartialOrd,
{
    fn eq(&self, other: &OrdByKey<'a, K, V>) -> bool {
        self.0.eq(&other.0)
    }
}

impl<'a, K, V> PartialOrd for OrdByKey<'a, K, V>
where
    K: PartialOrd,
{
    fn partial_cmp(&self, other: &OrdByKey<'a, K, V>) -> Option<Ordering> {
        self.0.partial_cmp(&other.0)
    }
}

impl<'a, K, V> Ord for OrdByKey<'a, K, V>
where
    K: Ord,
{
    fn cmp(&self, other: &Self) -> Ordering {
        self.0.cmp(&other.0)
    }
}
```

--------------------------------

### resolve_conflict

Source: https://docs.rs/treediff/latest/treediff/tools/trait.MutableFilter.html

Called during `Delegate::modified(...)`, returns `None` to cause the Value at the `keys` to be removed, or any Value to be set in its place. `old` is the previous value at the given `keys` path, and `new` is the one now at its place. `_target` provides access to the target of the merge operation.

```APIDOC
## fn resolve_conflict<'a, K: Clone + Display, V: Clone>(
    &mut self,
    _keys: &[K],
    _old: &'a V,
    new: &'a V,
    _target: &mut V,
) -> Option<Cow<'a, V>>

### Description
Called during `Delegate::modified(...)`, returns `None` to cause the Value at the `keys` to be removed, or any Value to be set in its place.
`old` is the previous value at the given `keys` path, and `new` is the one now at its place. `_target` provides access to the target of the merge operation.

### Parameters
- `_keys`: &[K] - The keys path.
- `_old`: &'a V - The previous value at the given keys path.
- `new`: &'a V - The new value at the given keys path.
- `_target`: &mut V - Provides access to the target of the merge operation.

### Returns
- `Option<Cow<'a, V>>` - `None` to remove the value, or `Some(Cow<'a, V>)` to set a new value.
```

--------------------------------

### Into Trait Implementation for DefaultMutableFilter

Source: https://docs.rs/treediff/latest/treediff/tools/struct.DefaultMutableFilter.html

Provides the into method as required by the Into trait. This method converts the type into another type that implements From<T>.

```rust
fn into(self) -> U
```

--------------------------------

### Recorder Struct Definition

Source: https://docs.rs/treediff/latest/treediff/tools/struct.Recorder.html

Defines the structure of the Recorder, which holds a vector of ChangeType records.

```APIDOC
```rust
pub struct Recorder<'a, K, V: 'a> {
    pub calls: Vec<ChangeType<'a, K, V>>,
    /* private fields */
}
```
```

--------------------------------

### Recorder Struct Definition

Source: https://docs.rs/treediff/latest/src/treediff/tools/record.rs.html

A delegate that records all calls made to it during a diff operation. It stores the current cursor path and a list of all detected changes.

```rust
pub struct Recorder<'a, K, V: 'a> {
    cursor: Vec<K>,
    /// A list of all calls the `diff` function made on us.
    pub calls: Vec<ChangeType<'a, K, V>>,
}
```

--------------------------------

### Generic diff function signature

Source: https://docs.rs/treediff/latest/treediff/fn.diff.html

This is the signature for the generic `diff` function. It takes two values to compare and a delegate to report changes. Ensure your Value type implements `Ord` and `Clone` for its keys, and the delegate implements the `Delegate` trait.

```rust
pub fn diff<'a, V, D>(
    l: &'a V,
    r: &'a V,
    d: &mut D,
)
where
    V: Value<Item = V>,
    V::Key: Ord + Clone,
    D: Delegate<'a, V::Key, V>,

```

--------------------------------

### diff Function Signature

Source: https://docs.rs/treediff/latest/treediff/fn.diff.html

The diff function is a generic method that takes two values and a delegate to report changes.

```APIDOC
## diff<V, D>

A generic diff algorithm suitable for `Value` types as seen in serialization/deserialization libraries. Such types can represent any tree-like data structure, which will be traversed to find _additions_ , _removals_ , _modifications_ and even portions that did not change at all.

### Parameters

* `l` - the left Value
* `r` - the right Value
* `d` - a `Delegate` to receive information about changes between `l` and `r`

### Signature

```rust
pub fn diff<'a, V, D>(l: &'a V, r: &'a V, d: &mut D)
where
    V: Value<Item = V>,
    V::Key: Ord + Clone,
    D: Delegate<'a, V::Key, V>,
```
```

--------------------------------

### Merger Struct

Source: https://docs.rs/treediff/latest/src/treediff/tools/merge.rs.html

The `Merger` struct wraps a target object and applies differences to it. It allows for custom conflict resolution through a `MutableFilter`.

```APIDOC
/// A `Delegate` which applies differences to a target object.
///
/// It wraps the target object and applies all calls by the `diff`
/// algorithm to it, which changes it in some way.
///
/// Custom resolver functions can be provided to arbitrarily alter
/// the way the merge is performed. This allows you, for example, to
/// keep your own meta-data, or to implement custom conflict resolutions.
///
/// # Examples
/// Please see the [tests][tests] for usage examples.
///
/// [tests]: https://github.com/Byron/treediff-rs/blob/master/tests/merge.rs#L22
pub struct Merger<K, V, BF, F>
```

--------------------------------

### Delegate unchanged Method

Source: https://docs.rs/treediff/latest/treediff/trait.Delegate.html

Called when a Value `v` has not changed.

```rust
fn unchanged(&mut self, _v: &'a V) { ... }
```

--------------------------------

### Delegate Trait Definition

Source: https://docs.rs/treediff/latest/treediff/trait.Delegate.html

Defines the interface for callbacks during the diff algorithm. Implementors should handle events for added, removed, modified, and unchanged values, and manage key path tracking via push/pop.

```rust
pub trait Delegate<'a, K, V> {
    // Provided methods
    fn push(&mut self, _k: &K) { ... }
    fn pop(&mut self) { ... }
    fn removed<'b>(&mut self, _k: &'b K, _v: &'a V) { ... }
    fn added<'b>(&mut self, _k: &'b K, _v: &'a V) { ... }
    fn unchanged(&mut self, _v: &'a V) { ... }
    fn modified(&mut self, _old: &'a V, _new: &'a V) { ... }
}
```

--------------------------------

### Borrow Trait Implementation for DefaultMutableFilter

Source: https://docs.rs/treediff/latest/treediff/tools/struct.DefaultMutableFilter.html

Provides the borrow method as required by the Borrow trait. This allows immutable borrowing of the DefaultMutableFilter instance.

```rust
fn borrow(&self) -> &T
```

--------------------------------

### Set Method - Mutable Trait

Source: https://docs.rs/treediff/latest/treediff/trait.Mutable.html

Sets a new value at the specified path. Intermediate container values are created as needed.

```rust
fn set(&mut self, keys: &[Self::Key], new: &Self::Item);
```

--------------------------------

### DefaultMutableFilter::resolve_removal Implementation

Source: https://docs.rs/treediff/latest/treediff/tools/struct.DefaultMutableFilter.html

Implements the resolve_removal method for DefaultMutableFilter. This method is called during Delegate::removed. It returns None, allowing the value at the specified keys to be removed.

```rust
fn resolve_removal<'a, K: Clone + Display, V: Clone>(
    &mut self,
    _keys: &[K],
    _removed: &'a V,
    _target: &mut V,
) -> Option<Cow<'a, V>> {
    None
}
```

--------------------------------

### BorrowMut Trait Implementation for DefaultMutableFilter

Source: https://docs.rs/treediff/latest/treediff/tools/struct.DefaultMutableFilter.html

Provides the borrow_mut method as required by the BorrowMut trait. This allows mutable borrowing of the DefaultMutableFilter instance.

```rust
fn borrow_mut(&mut self) -> &mut T
```

--------------------------------

### Recorder Struct Definition

Source: https://docs.rs/treediff/latest/treediff/tools/struct.Recorder.html

Defines the `Recorder` struct, which holds a vector of `ChangeType` to record delegate calls.

```rust
pub struct Recorder<'a, K, V: 'a> {
    pub calls: Vec<ChangeType<'a, K, V>>,
    /* private fields */
}
```

--------------------------------

### Recorder Delegate unchanged Method

Source: https://docs.rs/treediff/latest/treediff/tools/struct.Recorder.html

Records an `unchanged` operation, indicating that a Value was not modified.

```rust
fn unchanged<'b>(&mut self, v: &'a V)
```

--------------------------------

### Delegate Trait Definition

Source: https://docs.rs/treediff/latest/src/treediff/traitdef.rs.html

Defines the callback interface for the diff algorithm. Implement this trait to receive notifications about changes (added, removed, modified, unchanged) when comparing two values.

```rust
/// The delegate receiving callbacks by the `diff` algorithm, which compares an old to a new value.
///
/// # Type Parameters
/// * `K` is the Key's type
/// * `V` is the Value's type
///
/// Methods will be called if...
pub trait Delegate<'a, K, V> {
    /// ... we recurse into the `Value` at the given `Key`.
    ///
    /// Delegates should memoize the current Key path to be able to compute
    /// the full Key path when needed.
    fn push(&mut self, _k: &K) {}
    /// ... we have processed all items and leave the object previously `push`ed.
    fn pop(&mut self) {}
    /// ... the Value `v` at the given Key `k` should be removed.
    ///
    /// *Note* that the Key is partial, and should be used in conjunction with the recorded Keys
    /// received via `push(...)`
    fn removed<'b>(&mut self, _k: &'b K, _v: &'a V) {}
    /// .. the Value `v` at the given Key `k` should be added.
    ///
    /// *Note* that the Key is partial, and should be used in conjunction with the recorded Keys
    /// received via `push(...)`
    fn added<'b>(&mut self, _k: &'b K, _v: &'a V) {}
    /// The Value `v` was not changed.
    fn unchanged(&mut self, _v: &'a V) {}

    /// ... the `old` Value was modified, and is now the `new` Value.
    fn modified(&mut self, _old: &'a V, _new: &'a V) {}
}
```

--------------------------------

### impl MutableFilter for DefaultMutableFilter

Source: https://docs.rs/treediff/latest/treediff/tools/struct.DefaultMutableFilter.html

Implementations of the MutableFilter trait for DefaultMutableFilter, defining how conflicts and removals are resolved.

```APIDOC
## Trait Implementations

### impl MutableFilter for DefaultMutableFilter

#### fn resolve_conflict<'a, K: Clone + Display, V: Clone>(
    &mut self,
    _keys: & [K],
    _old: &'a V,
    new: &'a V,
    _target: &mut V,
) -> Option<Cow<'a, V>>

Called during `Delegate::modified(...)`, returns `None` to cause the Value at the `keys` to be removed, or any Value to be set in its place. Read more

#### fn resolve_removal<'a, K: Clone + Display, V: Clone>(
    &mut self,
    _keys: & [K],
    _removed: &'a V,
    _target: &mut V,
) -> Option<Cow<'a, V>>

Called during `Delegate::removed(...)`, returns `None` to allow the Value at the `keys` path to be removed, or any Value to be set in its place instead. Read more
```

--------------------------------

### DefaultMutableFilter Struct

Source: https://docs.rs/treediff/latest/src/treediff/tools/merge.rs.html

The default implementation for `MutableFilter`. This struct can be used when no custom filtering logic is required.

```APIDOC
/// The default implementation used when when creating a new `Merger` from any `Value` type.
///
/// If you want to choose your own filter, use `Merger::with_filter(...)` instead.
pub struct DefaultMutableFilter;
impl MutableFilter for DefaultMutableFilter {}
```

--------------------------------

### Any Trait Implementation for DefaultMutableFilter

Source: https://docs.rs/treediff/latest/treediff/tools/struct.DefaultMutableFilter.html

Provides the type_id method as required by the Any trait. This allows the DefaultMutableFilter type to be queried for its unique TypeId.

```rust
fn type_id(&self) -> TypeId
```

--------------------------------

### Value Trait Definition

Source: https://docs.rs/treediff/latest/treediff/trait.Value.html

Defines the Value trait with associated types Key and Item, and the items method.

```APIDOC
## Trait Value

Represents a scalar value or an associative array.

### Associated Types

#### type Key
The Key type used to find Values in a mapping.

#### type Item
The Value type itself.

### Methods

#### fn items<'a>(
    &'a self,
) -> Option<Box<dyn Iterator<Item = (Self::Key, &'a Self::Item)> + 'a>>

Returns `None` if this is a scalar value, and an iterator yielding (Key, Value) pairs otherwise. It is entirely possible for it to yield no values though.
```

--------------------------------

### Recorder Delegate modified Method

Source: https://docs.rs/treediff/latest/treediff/tools/struct.Recorder.html

Records a `modified` operation, indicating that a Value has changed from an old to a new state.

```rust
fn modified<'b>(&mut self, v1: &'a V, v2: &'a V)
```

--------------------------------

### DefaultMutableFilter::resolve_conflict Implementation

Source: https://docs.rs/treediff/latest/treediff/tools/struct.DefaultMutableFilter.html

Implements the resolve_conflict method for DefaultMutableFilter. This method is called during Delegate::modified. It currently does not modify the target value and returns None, indicating no change or removal.

```rust
fn resolve_conflict<'a, K: Clone + Display, V: Clone>(
    &mut self,
    _keys: &[K],
    _old: &'a V,
    new: &'a V,
    _target: &mut V,
) -> Option<Cow<'a, V>> {
    None
}
```

--------------------------------

### Merger::into_inner

Source: https://docs.rs/treediff/latest/treediff/tools/struct.Merger.html

Consumes the Merger instance and returns the contained target Value, which represents the result of the merge operation.

```rust
pub fn into_inner(self) -> V
```

--------------------------------

### Delegate Trait Definition

Source: https://docs.rs/treediff/latest/treediff/trait.Delegate.html

The Delegate trait defines the interface for receiving callbacks from the diff algorithm. Implementors of this trait can react to changes detected during the comparison of two values.

```APIDOC
## Trait Delegate<K, V>

The delegate receiving callbacks by the `diff` algorithm, which compares an old to a new value.

### Type Parameters
* `K`: The Key’s type
* `V`: The Value’s type

### Methods
#### fn push(&mut self, _k: &K)
... we recurse into the `Value` at the given `Key`. Delegates should memoize the current Key path to be able to compute the full Key path when needed.

#### fn pop(&mut self)
... we have processed all items and leave the object previously `push`ed.

#### fn removed<'b>(&mut self, _k: &'b K, _v: &'a V)
... the Value `v` at the given Key `k` should be removed. Note that the Key is partial, and should be used in conjunction with the recorded Keys received via `push(...)`.

#### fn added<'b>(&mut self, _k: &'b K, _v: &'a V)
.. the Value `v` at the given Key `k` should be added. Note that the Key is partial, and should be used in conjunction with the recorded Keys received via `push(...)`.

#### fn unchanged(&mut self, _v: &'a V)
The Value `v` was not changed.

#### fn modified(&mut self, _old: &'a V, _new: &'a V)
… the `old` Value was modified, and is now the `new` Value.
```

--------------------------------

### Delegate::modified Implementation for Merger

Source: https://docs.rs/treediff/latest/treediff/tools/struct.Merger.html

Implements the `modified` method for the `Delegate` trait on `Merger`. This method is called when a Value has been modified, providing both the old and new versions.

```rust
fn modified<'b>(&mut self, old: &'a V, new: &'a V)
```

--------------------------------

### Key Enum

Source: https://docs.rs/treediff/latest/src/treediff/value/shared.rs.html

The Key enum represents keys used in treediff values. It can be either an array index (usize) or a string key for mappings.

```APIDOC
/// A representation of all key types typical Value types will assume.
#[derive(Debug, Clone, PartialEq, Eq, Ord, PartialOrd)]
pub enum Key {
    /// An array index
    Index(usize),
    /// A string index for mappings
    String(String),
}

impl fmt::Display for Key {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        match *self {
            Key::String(ref v) => v.fmt(f),
            Key::Index(ref v) => v.fmt(f),
        }
    }
}
```

--------------------------------

### Merger Struct Definition

Source: https://docs.rs/treediff/latest/src/treediff/tools/merge.rs.html

Defines the Merger struct, which wraps a target object and applies diff operations to it. It uses a cursor for tracking the current path and a filter for custom merge logic.

```rust
pub struct Merger<K, V, BF, F> {
    cursor: Vec<K>,
    inner: V,
    filter: BF,
    _d: PhantomData<F>,
}
```

--------------------------------

### Mutable Trait

Source: https://docs.rs/treediff/latest/treediff/trait.Mutable.html

Defines the interface for types that can be mutated. It requires associated types for keys and items, and methods for setting and removing values.

```APIDOC
## Trait Mutable

### Description
A trait to allow changing any `Value`.

### Associated Types

#### type Key
The Key type used to find Values in a mapping.

#### type Item
The Value type itself.

### Methods

#### fn set(&mut self, keys: &[Self::Key], new: &Self::Item)
Set the `new` Value at the path identified by `keys`. Intermediate container values (like HashMaps, Arrays) must be created until the last Key in `keys` can be modified or inserted with `new`.

#### fn remove(&mut self, keys: &[Self::Key])
Remove the value located at the path identified by `keys`. If the value does not exist, just return. Intermediate container values must not be created.
```

--------------------------------

### Merger::filter

Source: https://docs.rs/treediff/latest/treediff/tools/struct.Merger.html

Returns an immutable borrow to the MutableFilter instance associated with the Merger.

```rust
pub fn filter(&self) -> &BF
```

--------------------------------

### Enum Key Definition

Source: https://docs.rs/treediff/latest/treediff/value/enum.Key.html

Defines the Key enum with variants for array indices and string identifiers. This is the fundamental type for keys in treediff's value representation.

```rust
pub enum Key {
    Index(usize),
    String(String),
}
```
Tokens:
Raw