Add sliding windows algorithm

[ollieatkinson]

Many thanks to @timvermeulen for helping me refine this collection algorithm.

Description

Break a collection into overlapping contiguous window subsequences where
elements are slices from the original collection.

The slidingWindows(ofCount:) method takes in a integer size and returns a collection of subsequences.

let swift = "swift"

let windowed = swift.slidingWindows(ofCount: 2) 
// windowed == [ "sw", "wi", "if", "ft" ]

Detailed Design

The slidingWindows(ofCount:) is added as a method on an extension of Collection

extension Collection {
  public func slidingWindows(ofCount count: Int) -> SlidingWindows<Self> {
    SlidingWindows(base: self, size: count)
  }
}

If a size larger than the collection length is specified, an empty collection is returned. Due to this
behaviour the indexes must be calculated on initialisation as we have to be able to compare the
upperBound and allow Collection correctly calculate isEmpty .

[1, 2, 3].slidingWindows(ofCount: 5).isEmpty // true

The resulting SlidingWindows type is a collection, with conditional conformance to the
BidirectionalCollection, and RandomAccessCollection when the base collection
conforms.

Complexity

The call to slidingWindows(ofCount: k) is O(1) if the collection conforms to
RandomAccessCollection, otherwise O(k). Access to the next window
is O(1).

Naming

The type SlidingWindows takes its name from the algorithm, similarly the method takes
it's name from it too slidingWindows(ofCount: k).

The label on the method ofCount was chosen to create a consistent feel to the API
available in swift-algorithms repository. Inspiration was taken from
combinations(ofCount:) and permutations(ofCount:).

Previously the name windows was considered but was deemed to potentially create
ambiguity with the Windows operating system.

Comparison with other languages

rust has std::slice::Windows which is a method available on slices. It has the same semantics as
described here.

Documentation

This documentation exists in Guides/SlidingWindows.md

Impact

This is an additive change, no impact.

---

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

[kylemacomber]

What do you think about windows(ofCount:) rather than windows(size:)?

When we were naming combinations(ofCount:), permutations(ofCount:), and randomSample(count:), we tried to consistently use "count" when it referred to the number of elements in a sequence or collection—avoiding synonyms size and length.

[ollieatkinson]

What do you think about windows(ofCount:) rather than windows(size:)?

When we were naming combinations(ofCount:), permutations(ofCount:), and randomSample(count:), we tried to consistently use "count" when it referred to the number of elements in a sequence or collection—avoiding synonyms size and length.

I would not be against the name change, it was not immediately obvious to me that ofCount was an option. I prefer size but I also prefer consistent API naming.

The arguments you make are valid, so I would be happy to change it - but, before I do, It might be a good idea to see what other folks think first.

[natecook1000]

Thanks for this contribution, @ollieatkinson! 👏

[ollieatkinson]

@kylemacomber I've given this some thought and renamed the label to ofCount

[xwu]

In a general-purpose language that now has Windows support, I would be wary of a general-purpose API vending a type named Windows. I do think SlidingWindows would be more apt here.

[ollieatkinson]

In a general-purpose language that now has Windows support, I would be wary of a general-purpose API vending a type named Windows. I do think SlidingWindows would be more apt here.

That's a good thought, I'm liking the suggestion you've made! Thank you @xwu

[pyrtsa]

Any reason not to rename the function accordingly now, windows(ofCount:) → slidingWindows(ofCount:)?

[ollieatkinson]

Any reason not to rename the function accordingly now, windows(ofCount:) → slidingWindows(ofCount:)?

I'm in the process of renaming the type, function and updating the documentation now!

[natecook1000]

Looks great, @ollieatkinson!

[Danappelxx]

Should probably add a link to Guides/SlidingWindows.md to the README :)