Add Stride for Collection

Author: ollieatkinson

Guides/Stride.md

@@ -0,0 +1,63 @@
+# Stride
+
+[[Source](https://github.com/apple/swift-algorithms/blob/main/Sources/Algorithms/Stride.swift) | 
+ [Tests](https://github.com/apple/swift-algorithms/blob/main/Tests/SwiftAlgorithmsTests/StrideTests.swift)]
+
+A type that steps over a collection’s elements by the specified amount.
+
+This is available through the `stride(by:)` method on any `Collection`.
+
+```swift
+(0...10).stride(by: 2) // == [0, 2, 4, 6, 8, 10]
+```
+
+If the stride is larger than the collection count, the resulting wrapper only contains the 
+first element.
+
+The stride amount must be a positive value.
+
+## Detailed Design
+
+The `stride(by:)` method is declared as a `Collection` extension, and returns a 
+`Stride` type:
+
+```swift
+extension Collection {
+  public func stride(by step: Int) -> Stride<Self>
+}
+```
+
+A custom `Index` type is defined so that it's not possible to get confused when trying 
+to access an index of the stride collection.
+
+```swift
+[0, 1, 2, 3, 4].stride(by: 2)[1] // == 1
+[0, 1, 2, 3, 4].stride(by: 2).map { $0 }[1] // == 2
+```
+
+A careful thought was given to the composition of these strides by giving a custom 
+implementation to `index(_:offsetBy:limitedBy)` which multiplies the offset by the 
+stride amount. 
+
+```swift
+base.index(i.base, offsetBy: distance * stride, limitedBy: base.endIndex)
+```
+
+The following two lines of code are equivalent, including performance:
+
+```swift
+(0...10).stride(by: 6)
+(0...10).stride(by: 2).stride(by: 3)
+```
+
+### Complexity
+
+The call to `stride(by: k)` is always O(_1_) and access to the next value in the stride 
+is O(_1_) if the collection conforms to `RandomAccessCollection`, otherwise O(_k_).
+
+### Comparison with other languages
+
+[rust has `Strided`](https://docs.rs/strided/0.2.9/strided/) available in a crate. 
+[c++ has std::slice::stride](http://www.cplusplus.com/reference/valarray/slice/stride/)
+
+The semantics of `stride` described in this documentation are equivalent.

Sources/Algorithms/Stride.swift

@@ -0,0 +1,115 @@
+//===----------------------------------------------------------------------===//
+//
+// 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
+//
+//===----------------------------------------------------------------------===//
+
+//===----------------------------------------------------------------------===//
+// stride(by:)
+//===----------------------------------------------------------------------===//
+
+extension Collection {
+  /// - Complexity: O(_1_) and access to the next value in the stride
+  /// is O(_1_) if the collection conforms to `RandomAccessCollection`,
+  /// otherwise O(_k_) where `k` is the stride `step`.
+  ///
+  /// - Parameter step: The amount to step with each iteration.
+  /// - Returns: Returns a collection stepping through the elements by the
+  /// specified amount.
+  public func stride(by step: Int) -> Stride<Self> {
+    Stride(base: self, stride: step)
+  }
+}
+
+public struct Stride<Base: Collection> {
+  
+  public let base: Base
+  public let stride: Int
+  
+  init(base: Base, stride: Int) {
+    precondition(stride > 0, "stride must be greater than zero")
+    self.base = base
+    self.stride = stride
+  }
+}
+
+extension Stride: Collection {
+  
+  public struct Index: Comparable {
+    
+    let base: Base.Index
+    
+    init(_ base: Base.Index) {
+      self.base = base
+    }
+    
+    public static func < (lhs: Index, rhs: Index) -> Bool {
+      lhs.base < rhs.base
+    }
+  }
+  
+  public var startIndex: Index {
+    Index(base.startIndex)
+  }
+  
+  public var endIndex: Index {
+    Index(base.endIndex)
+  }
+  
+  public subscript(i: Index) -> Base.Element {
+    base[i.base]
+  }
+  
+  public func index(after i: Index) -> Index {
+    precondition(i.base < base.endIndex, "Advancing past end index")
+    return base.index(i.base, offsetBy: stride, limitedBy: base.endIndex)
+      .map(Index.init) ?? endIndex
+  }
+  
+  public func index(
+    _ i: Index,
+    offsetBy distance: Int,
+    limitedBy limit: Index
+  ) -> Index? {
+    base.index(i.base, offsetBy: distance * stride, limitedBy: limit.base)
+      .map(Index.init)
+  }
+  
+  // TODO: Implement distance(from:to:) and index(_:offsetBy:)
+
+}
+
+extension Stride: BidirectionalCollection
+  where Base: RandomAccessCollection {
+  
+  public func index(before i: Index) -> Index {
+    precondition(i.base > base.startIndex, "Incrementing past start index")
+    if i == endIndex {
+      let count = base.count
+      precondition(count > 0, "Asking for an index when count is zero")
+      return Index(
+        base.index(
+          base.endIndex,
+          offsetBy: -((count - 1) % stride + 1)
+        )
+      )
+    } else {
+      return base.index(i.base, offsetBy: -stride, limitedBy: startIndex.base)
+        .map(Index.init) ?? startIndex
+    }
+  }
+}
+
+extension Stride: RandomAccessCollection
+  where Base: RandomAccessCollection {}
+
+extension Stride: Equatable
+  where Base: Equatable {}
+
+extension Stride: Hashable
+  where Base: Hashable, Base.Index: Hashable {}

Tests/SwiftAlgorithmsTests/StrideTests.swift

@@ -0,0 +1,69 @@
+//===----------------------------------------------------------------------===//
+//
+// 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 StridingTests: XCTestCase {
+  
+  func testStride() {
+    let a = (0...10)
+    XCTAssertEqualSequences(a.stride(by: 1), (0...10))
+    XCTAssertEqualSequences(a.stride(by: 2), [0, 2, 4, 6, 8, 10])
+    XCTAssertEqualSequences(a.stride(by: 3), [0, 3, 6, 9])
+    XCTAssertEqualSequences(a.stride(by: 4), [0, 4, 8])
+    XCTAssertEqualSequences(a.stride(by: 5), [0, 5, 10])
+    XCTAssertEqualSequences(a.stride(by: 10), [0, 10])
+    XCTAssertEqualSequences(a.stride(by: 11), [0])
+  }
+  
+  func testStrideString() {
+    let s = "swift"
+    XCTAssertEqualSequences(s.stride(by: 2), ["s", "i", "t"])
+  }
+  
+  func testStrideReversed() {
+    let a = [0, 1, 2, 3, 4, 5]
+    XCTAssertEqualSequences(a.stride(by: 3).reversed(), [3, 0])
+    XCTAssertEqualSequences(a.reversed().stride(by: 2), [5, 3, 1])
+  }
+  
+  func testStrideIndexes() {
+    let a = [0, 1, 2, 3, 4, 5].stride(by: 2)
+    var i = a.startIndex
+    XCTAssertEqual(a[i], 0)
+    a.formIndex(after: &i)
+    XCTAssertEqual(a[i], 2)
+    a.formIndex(after: &i)
+    XCTAssertEqual(a[i], 4)
+    a.formIndex(before: &i)
+    XCTAssertEqual(a[i], 2)
+    a.formIndex(before: &i)
+    XCTAssertEqual(a[i], 0)
+//    a.formIndex(before: &i) // Precondition failed: Advancing past start index
+//    a.index(after: a.endIndex) // Precondition failed: Advancing past end index
+  }
+  
+  func testStrideCompositionEquivalence() {
+    let a = (0...10)
+    XCTAssertEqualSequences(a.stride(by: 6), a.stride(by: 2).stride(by: 3))
+  }
+  
+  func testStrideLast() {
+    XCTAssertEqual((1...10).stride(by: 2).last, 9) // 1, 3, 5, 7, 9
+    XCTAssertEqual((1...10).stride(by: 3).last, 10) // 1, 4, 7, 10
+    XCTAssertEqual((1...10).stride(by: 4).last, 9) // 1, 5, 9
+    XCTAssertEqual((1...10).stride(by: 5).last, 6) // 1, 6
+    XCTAssertEqual((1...100).stride(by: 50).last, 51) // 1, 51
+    XCTAssertEqual((1...5).stride(by: 2).last, 5) // 1, 3, 5
+    XCTAssertEqual([Int]().stride(by: 2).last, nil) // 1, 3, 5
+  }
+}