Add sliding windows algorithm

Author: ollieatkinson

Guides/Windows.md

@@ -0,0 +1,51 @@
+# Windows
+
+[[Source](https://github.com/apple/swift-algorithms/blob/main/Sources/Algorithms/Windows.swift) | 
+ [Tests](https://github.com/apple/swift-algorithms/blob/main/Tests/SwiftAlgorithmsTests/WindowsTests.swift)]
+
+Break a collection into overlapping contiguous window subsequences where
+elements are slices from the original collection.
+
+The `windows(size:)` method takes in a integer size and returns a collection of subsequences.
+
+```swift
+let swift = "swift"
+
+let windowed = swift.windows(size: 2) 
+// windowed == [ "sw", "wi", "if", "ft" ]
+```
+
+## Detailed Design
+
+The `windows(size:)` is added as a method on an extension of  `Collection`
+
+```swift
+extension Collection {
+  public func windows(size: Int) -> WindowsSubSequence<Self> {
+    WindowsSubSequence(base: self, size: size)
+  }
+}
+```
+
+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` in each window slice.
+
+```swift
+[1, 2, 3].windows(size: 5).isEmpty // true
+```
+
+### Complexity
+
+O(_N_) time and O(_1_) space complexity.
+
+### Naming
+
+The name `window` is adopted from the the commonly known sliding windows problem or algorithm name.
+Alternatively this could be named `slidingWindows`, however I did not feel the verbosity here was 
+necessary.
+
+### Comparison with other languages
+
+[rust](https://doc.rust-lang.org/std/slice/struct.Windows.html) has `std::slice::Windows`  which is 
+a method available on slices. It has the same semantics as described here.

Sources/Algorithms/Windows.swift

@@ -0,0 +1,86 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift Algorithms open source project
+//
+// Copyright (c) 2020 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+//
+//===----------------------------------------------------------------------===//
+
+//===----------------------------------------------------------------------===//
+// windows(size:)
+//===----------------------------------------------------------------------===//
+
+extension Collection {
+  /// Returns a collection for all contiguous windows of length size. The windows overlap.
+  /// If the slice is shorter than `size`, the collection returns an empty subsequence.
+  public func windows(size: Int) -> WindowsSubSequence<Self> {
+    WindowsSubSequence(base: self, size: size)
+  }
+}
+
+public struct WindowsSubSequence<Base: Collection> {
+  
+  public struct Index: Comparable {
+    
+    internal var lowerBound: Base.Index
+    internal var upperBound: Base.Index
+    
+    public static func == (lhs: Index, rhs: Index) -> Bool {
+      lhs.lowerBound == rhs.upperBound && lhs.upperBound == rhs.upperBound
+    }
+    
+    public static func < (lhs: Index, rhs: Index) -> Bool {
+      lhs.upperBound < rhs.upperBound
+    }
+  }
+  
+  public let base: Base
+  public let size: Int
+  
+  public let startIndex: Index
+  public let endIndex: Index
+  
+  public init(base: Base, size: Int) {
+    precondition(size > 0, "Windows size must be greater than zero")
+    self.base = base
+    self.size = size
+    let limit = base.count - size
+    if limit > 0, let firstUpperBound = base.index(base.startIndex, offsetBy: size, limitedBy: base.endIndex) {
+      startIndex = Index(lowerBound: base.startIndex, upperBound: firstUpperBound)
+      endIndex = Index(lowerBound: base.endIndex, upperBound: base.endIndex)
+    } else {
+      startIndex = Index(lowerBound: base.startIndex, upperBound: base.startIndex)
+      endIndex = startIndex
+    }
+    
+  }
+}
+
+extension WindowsSubSequence: Collection {
+  
+  public subscript(index: Index) -> Base.SubSequence {
+    base[index.lowerBound..<index.upperBound]
+  }
+  
+  public func index(after index: Index) -> Index {
+    guard index.upperBound < base.endIndex else { return endIndex }
+    return Index(lowerBound: base.index(after: index.lowerBound), upperBound: base.index(after: index.upperBound))
+  }
+}
+
+extension WindowsSubSequence: BidirectionalCollection where Base: BidirectionalCollection {
+  
+  public func index(before index: Index) -> Index {
+    guard let lowerBound = base.index(index.lowerBound, offsetBy: -size, limitedBy: base.startIndex) else { return startIndex }
+    return Index(lowerBound: lowerBound, upperBound: index == endIndex ? index.upperBound : base.index(before: index.upperBound))
+  }
+}
+
+extension WindowsSubSequence: RandomAccessCollection where Base: RandomAccessCollection {}
+
+extension WindowsSubSequence: Equatable where Base: Equatable {}
+extension WindowsSubSequence: Hashable where Base: Hashable, Base.Index: Hashable {}
+extension WindowsSubSequence.Index: Hashable where Base.Index: Hashable {}

Tests/SwiftAlgorithmsTests/WindowsTests.swift

@@ -0,0 +1,74 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift Algorithms open source project
+//
+// Copyright (c) 2020 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+//
+//===----------------------------------------------------------------------===//
+
+import XCTest
+import Algorithms
+
+final class WindowsTests: XCTestCase {
+  
+  func testWindows() {
+    do {
+      let a = (0...100).map{ $0 }
+
+      XCTAssertTrue(a.windows(size: 200).isEmpty)
+
+      let w = a.windows(size: 10)
+
+      XCTAssertEqualSequences(w.first ?? [], 0..<10)
+      XCTAssertEqualSequences(w.last ?? [], 91..<101)
+    }
+
+    do {
+      let s = "swift"
+      var itr = s.windows(size: 2).makeIterator()
+
+      XCTAssertEqual(itr.next(), "sw")
+      XCTAssertEqual(itr.next(), "wi")
+      XCTAssertEqual(itr.next(), "if")
+      XCTAssertEqual(itr.next(), "ft")
+      XCTAssertNil(itr.next())
+    }
+
+    do {
+      let a = [ 0, 1, 0, 1 ].windows(size: 2)
+
+      XCTAssertEqual(a.count, 3)
+      XCTAssertEqual(a.map { $0.reduce(0, +) }, [1, 1, 1])
+
+      let a2 = [0, 1, 2, 3, 4, 5, 6].windows(size: 3).map {
+        $0.reduce(0, +)
+      }.reduce(0, +)
+
+      XCTAssertEqual(a2, 3 + 6 + 9 + 12 + 15)
+    }
+
+    do {
+      let a = [0, 1, 2, 3, 4, 5]
+      XCTAssertEqual(a.windows(size: 3).count, 4)
+
+      let a2 = [0, 1, 2, 3, 4]
+      XCTAssertEqual(a2.windows(size: 6).count, 0)
+
+      let a3 = [Int]()
+      XCTAssertEqual(a3.windows(size: 2).count, 0)
+    }
+
+    do {
+      let a = [0, 1, 2, 3, 4, 5]
+      let w = a.windows(size: 4)
+      let snd = w[w.index(after: w.startIndex)]
+      XCTAssertEqualSequences(snd, [1, 2, 3, 4])
+
+      let w2 = a.windows(size: 3)
+      XCTAssertEqualSequences(w2.last ?? [], [3, 4, 5])
+    }
+  }
+}