Add additional tests to rotate functions, clarify variable names

Sources/Algorithms/Rotate.swift

@@ -25,23 +25,23 @@ extension MutableCollection where Self: BidirectionalCollection {
   ///     Output:
   ///     [p o n m e f g h i j k l d c b a]
   ///             ^               ^
-  ///             f               l
+  ///           lower           upper
   ///
-  /// - Postcondition: For returned indices `(f, l)`:
-  ///   `f == limit || l == limit`
+  /// - Postcondition: For returned indices `(lower, upper)`:
+  ///   `lower == limit || upper == limit`
   @usableFromInline
   @discardableResult
   internal mutating func _reverse(
     subrange: Range<Index>, until limit: Index
   ) -> (Index, Index) {
-    var f = subrange.lowerBound
-    var l = subrange.upperBound
-    while f != limit && l != limit {
-      formIndex(before: &l)
-      swapAt(f, l)
-      formIndex(after: &f)
+    var lower = subrange.lowerBound
+    var upper = subrange.upperBound
+    while lower != limit && upper != limit {
+      formIndex(before: &upper)
+      swapAt(lower, upper)
+      formIndex(after: &lower)
     }
-    return (f, l)
+    return (lower, upper)
   }
 
   /// Reverses the elements within the given subrange.
@@ -59,13 +59,12 @@ extension MutableCollection where Self: BidirectionalCollection {
   @inlinable
   public mutating func reverse(subrange: Range<Index>) {
     if subrange.isEmpty { return }
-    var lo = subrange.lowerBound
-    var hi = subrange.upperBound
-
-    while lo < hi {
-      formIndex(before: &hi)
-      swapAt(lo, hi)
-      formIndex(after: &lo)
+    var lower = subrange.lowerBound
+    var upper = subrange.upperBound
+    while lower < upper {
+      formIndex(before: &upper)
+      swapAt(lower, upper)
+      formIndex(after: &lower)
     }
   }
 }

Tests/SwiftAlgorithmsTests/RotateTests.swift

@@ -10,9 +10,70 @@
 //===----------------------------------------------------------------------===//
 
 import XCTest
-import Algorithms
+@testable import Algorithms
 
 final class RotateTests: XCTestCase {
+  /// Tests the example given in `_reverse(subrange:until:)`’s documentation
+  func testUnderscoreReverse() {
+    var input = ["a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k", "l", "m", "n", "o", "p"]
+    let limit: Int = 4
+    let (lower, upper) = input._reverse(subrange: input.startIndex..<input.endIndex, until: input.startIndex.advanced(by: limit))
+    let expected = ["p", "o", "n", "m", "e", "f", "g", "h", "i", "j", "k", "l", "d", "c", "b", "a"]
+    XCTAssertEqual(input, expected)
+    XCTAssertEqual(lower, input.startIndex.advanced(by: limit))
+    XCTAssertEqual(upper, input.endIndex.advanced(by: -limit))
+  }
+
+  /// Tests the example given in `reverse(subrange:)`’s documentation
+  func testReverse() {
+    var numbers = [10, 20, 30, 40, 50, 60, 70, 80]
+    numbers.reverse(subrange: 0..<4)
+    XCTAssertEqual(numbers, [40, 30, 20, 10, 50, 60, 70, 80])
+  }
+
+  /// Tests `rotate(subrange:toStartAt:)` with an empty subrange
+  /// The order of elements are unchanged
+  func testRotateEmptySubrange() {
+    var numbers = [10, 20, 30, 40, 50, 60, 70, 80]
+    let oldStart = numbers.rotate(subrange: 3..<3, toStartAt: 3)
+    XCTAssertEqual(numbers, [10, 20, 30, 40, 50, 60, 70, 80])
+    XCTAssertEqual(numbers[oldStart], 40)
+  }
+
+  /// Tests `rotate(subrange:toStartAt:)` with an empty collection
+  func testRotateSubrangeOnEmptyCollection() {
+    var numbers = [Int]()
+    let oldStart = numbers.rotate(subrange: 0..<0, toStartAt: 0)
+    XCTAssertEqual(numbers, [])
+    XCTAssertEqual(oldStart, numbers.startIndex)
+  }
+
+  /// Tests `rotate(subrange:toStartAt:)` with the full range of the collection
+  func testRotateFullRange() {
+    var numbers = [10, 20, 30, 40, 50, 60, 70, 80]
+    let oldStart = numbers.rotate(subrange: 0..<8, toStartAt: 1)
+    XCTAssertEqual(numbers, [20, 30, 40, 50, 60, 70, 80, 10])
+    XCTAssertEqual(numbers[oldStart], 10)
+  }
+
+  /// Tests the example given in `rotate(subrange:toStartAt:)`’s documentation
+  func testRotateSubrange() {
+    var numbers = [10, 20, 30, 40, 50, 60, 70, 80]
+    let oldStart = numbers.rotate(subrange: 0..<4, toStartAt: 2)
+    XCTAssertEqual(numbers, [30, 40, 10, 20, 50, 60, 70, 80])
+    XCTAssertEqual(numbers[oldStart], 10)
+  }
+
+  /// Tests the example given in `rotate(toStartAt:)`’s documentation
+  func testRotateExample() {
+    var numbers = [10, 20, 30, 40, 50, 60, 70, 80]
+    let oldStart = numbers.rotate(toStartAt: 3)
+    XCTAssertEqual(numbers, [40, 50, 60, 70, 80, 10, 20, 30])
+    XCTAssertEqual(numbers[oldStart], 10)
+  }
+
+  /// Tests `rotate(toStartAt:)` on collections of varying lengths, at different
+  /// starting points
   func testRotate() {
     for length in 0...15 {
       let a = Array(0..<length)