Add AdjacentPairs

[christopherweems]

Description

Adds a LazyAdjacentPairs type, a lazy collection iterating over the adjacent elements of a base collection, and an accessor property on Collection and LazyCollectionProtocol. Each AdjacentPair is a tuple defined as (leading: Element, trailing: Element). The first pair is the first two elements of the base collection, the second pair is the second and third elements, and so forth.

Detailed Design

Include any additional information about the design here. At minimum, show any new API:

extension LazyCollectionProtocol {
    var adjacentPairs: LazyAdjacentPairs<Self>
}

extension Collection {
    typealias AdjacentPair = (leading: Element, trailing: Element)
    var adjacentPairs: [AdjacentPair]
}

Documentation Plan

How has the new feature been documented? Have the relevant portions of the guides been updated in addition to symbol-level documentation?

A usage guide exists in Guides/AdjacentPairs.md.

Test Plan

Tests have been added in Tests/SwiftAlgorithmsTests/AdjacentPairsTests.swift.

Source Impact

This is a purely additive change.

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 README.md remains unchanged

[timvermeulen]

For reference, this has previously been proposed for inclusion in the standard library (pitch, Swift Evolution, Swift Evolution Staging).

[christopherweems]

Thank you Tim, I had missed some of the previous attempts of getting this thing going. I noticed some of the previous proposals used .adjacentPairs() as a function call, and not a property as in this PR.

I'm concerned with the non-lazy implementation unnecessarily using twice the memory of the base collection. It's not something I have tested for, but seems that an array of tuples of overlapping elements would wastefully duplicate members of the base collection. I'm considering a rewrite to return a different collection that does not duplicate elements in storage.

[christopherweems]

This functionality has been covered by more general .slidingWindows() algorithm b28d248, making this redundant.