First Mismatching Elements, or Indexes Thereof

[CTMacUser]

Description

This request adapts the C++ function mismatch, having methods returning the first mismatching elements between two sequences. There are variant methods returning the corresponding indexes instead, i.e. the past-the-end points for a common prefix. Finally, another set of methods reverses the search to find a common suffix for bidirectional collections.

Detailed Design

extension Sequence {
    /// Returns the first non-matching element pair found when comparing this
    /// sequence to the given sequence element-wise, using the given predicate as
    /// the equivalence test.
    func firstDelta<PossibleMirror>(against possibleMirror: PossibleMirror, by areEquivalent: (Element, PossibleMirror.Element) throws -> Bool) rethrows -> (Element?, PossibleMirror.Element?) where PossibleMirror : Sequence
}

extension Sequence where Self.Element : Equatable {
    /// Returns the first non-equal element pair found when comparing this
    /// sequence to the given sequence element-wise.
    func firstDelta<PossibleMirror>(against possibleMirror: PossibleMirror) -> (Element?, Element?) where PossibleMirror : Sequence, Self.Element == PossibleMirror.Element
}

extension Collection {
    /// Finds the longest common prefix between this collection and the given
    /// collection, using the given predicate as the equivalence test, returning
    /// the past-the-end indexes of the respective subsequences.
    func diverges<PossibleMirror>(from possibleMirror: PossibleMirror, by areEquivalent: (Element, PossibleMirror.Element) throws -> Bool) rethrows -> (Index, PossibleMirror.Index) where PossibleMirror : Collection
}

extension Collection where Self.Element : Equatable {
    /// Finds the longest common prefix between this collection and the given
    /// collection, returning the past-the-end indexes of the respective
    /// subsequences.
    func diverges<PossibleMirror>(from possibleMirror: PossibleMirror) -> (Index, PossibleMirror.Index) where PossibleMirror : Collection, Self.Element == PossibleMirror.Element
}

extension BidirectionalCollection {
    /// Finds the longest common suffix between this collection and the given
    /// collection, using the given predicate as the equivalence test, returning
    /// the starting indexes of the respective subsequences.
    func converges<PossibleMirror>(with possibleMirror: PossibleMirror, by areEquivalent: (Element, PossibleMirror.Element) throws -> Bool) rethrows -> (Index, PossibleMirror.Index) where PossibleMirror : BidirectionalCollection
}

extension BidirectionalCollection where Self.Element : Equatable {
    /// Finds the longest common suffix between this collection and the given
    /// collection, returning the starting indexes of the respective subsequences.
    func converges<PossibleMirror>(with possibleMirror: PossibleMirror) -> (Index, PossibleMirror.Index) where PossibleMirror : BidirectionalCollection, Self.Element == PossibleMirror.Element
}

let a = [2, 4, 6, 8, 10, 12, 14, 16, 18, 20, 22, 24, 26, 28, 30, 32],
      b = [2, 4, 8, 16, 32]
a.firstDelta(against: b)  // returns (6, 8)
a.diverges(from: b)         // returns (2, 2)
a.converges(with: b)      // returns (15, 4)

Documentation Plan

The methods have block comments, and there is a guide file.

Test Plan

There is a test file included.

Source Impact

This request adds new API.

Checklist

• I've added at least one test that validates that my change is working, if appropriate
• I've followed the code style of the rest of the project
• I've read the Contribution Guidelines
• I've updated the documentation if necessary