Rename rotate(at:) to rotate(toStartAt:)

This was the intended name for the rotate method, just missed in
the initial release.

Author: natecook1000

Guides/Rotate.md

@@ -7,7 +7,7 @@ A mutating method that rotates the elements of a collection to new positions.
 
 ```swift
 var numbers = [10, 20, 30, 40, 50, 60]
-let p = numbers.rotate(at: 2)
+let p = numbers.rotate(toStartAt: 2)
 // numbers == [30, 40, 50, 60, 10, 20]
 // p == 4 -- numbers[p] == 10
 ```
@@ -18,9 +18,9 @@ variants that take a range:
 
 ```swift
 var numbers = [10, 20, 30, 40, 50, 60]
-numbers.rotate(subrange: 0..<3, at: 1)
+numbers.rotate(subrange: 0..<3, toStartAt: 1)
 // numbers = [20, 30, 10, 40, 50, 60]
-numbers.rotate(subrange: 3..<6, at: 4)
+numbers.rotate(subrange: 3..<6, toStartAt: 4)
 // numbers = [20, 30, 10, 50, 60, 40]
 ```
 
@@ -30,11 +30,11 @@ This adds the two `MutableCollection` methods shown above:
 
 ```swift
 extension MutableCollection {
-    mutating func rotate(at p: Index) -> Index
+    mutating func rotate(toStartAt p: Index) -> Index
 
     mutating func rotate(
         subrange: Range<Index>,
-        at p: Index
+        toStartAt p: Index
     ) -> Index
 }
 ```
@@ -49,13 +49,14 @@ the number of swaps required per element, so `rotate` would need to be a
 ### Naming
 
 The index parameter has been proposed as `shiftingToStart` in the past; this
-proposal uses the simpler `at` label. `shiftingToStart` introduces the idea of
-a "shift", which can sound like shifting just that single element to the
+version uses the `toStartAt` label, instead. `shiftingToStart` introduces the 
+idea of a "shift", which can sound like shifting just that single element to the
 beginning of the collection.
 
 For the range-based overloads, the label could be omitted. That is, instead of
 using `subrange:`, the method could be called as 
-`numbers.rotate(0..<3, at: 2)`.
+`numbers.rotate(0..<3, toStartAt: 2)`. The label is included here for 
+consistency with other range-based mutating methods.
 
 ### Comparison with other languages
 
@@ -65,5 +66,5 @@ semantics to this one.
 **Ruby:** You can rotate the elements of an array by a number of positions,
 either forward or backward (by passing a negative number). For zero-indexed
 collections, forward rotation by e.g. 3 elements is equivalent to
-`rotate(at: 3)`.
+`rotate(toStartAt: 3)`.
 

Sources/Algorithms/Partition.swift

@@ -42,7 +42,7 @@ extension MutableCollection {
       count: n - h,
       subrange: i..<subrange.upperBound,
       by: belongsInSecondPartition)
-    return rotate(subrange: j..<k, at: i)
+    return rotate(subrange: j..<k, toStartAt: i)
   }
 
   /// Moves all elements satisfying the given predicate into a suffix of the

Sources/Algorithms/Rotate.swift

@@ -57,7 +57,7 @@ extension MutableCollection where Self: BidirectionalCollection {
 }
 
 //===----------------------------------------------------------------------===//
-// rotate(at:) / rotate(subrange:at:)
+// rotate(toStartAt:) / rotate(subrange:toStartAt:)
 //===----------------------------------------------------------------------===//
 
 extension MutableCollection {
@@ -101,7 +101,7 @@ extension MutableCollection {
   @discardableResult
   public mutating func rotate(
     subrange: Range<Index>,
-    at newStart: Index
+    toStartAt newStart: Index
   ) -> Index {
     var m = newStart, s = subrange.lowerBound
     let e = subrange.upperBound
@@ -160,16 +160,16 @@ extension MutableCollection {
   }
 
   @discardableResult
-  public mutating func rotate(at newStart: Index) -> Index {
-    rotate(subrange: startIndex..<endIndex, at: newStart)
+  public mutating func rotate(toStartAt newStart: Index) -> Index {
+    rotate(subrange: startIndex..<endIndex, toStartAt: newStart)
   }
 }
 
 extension MutableCollection where Self: BidirectionalCollection {
   @discardableResult
   public mutating func rotate(
     subrange: Range<Index>,
-    at newStart: Index
+    toStartAt newStart: Index
   ) -> Index {
     reverse(subrange: subrange.lowerBound..<newStart)
     reverse(subrange: newStart..<subrange.upperBound)
@@ -179,15 +179,15 @@ extension MutableCollection where Self: BidirectionalCollection {
   }
 
   /// Rotates the elements of this collection so that the element
-  /// at the specified index moves to the front of the collection.
+  /// at the specified index becomes the start of the collection.
   ///
   /// Rotating a collection is equivalent to breaking the collection into two
   /// sections at the index `newStart`, and then swapping those two sections.
   /// In this example, the `numbers` array is rotated so that the element at
   /// index `3` (`40`) is first:
   ///
   ///     var numbers = [10, 20, 30, 40, 50, 60, 70, 80]
-  ///     let oldStart = numbers.rotate(at: 3)
+  ///     let oldStart = numbers.rotate(toStartAt: 3)
   ///     // numbers == [40, 50, 60, 70, 80, 10, 20, 30]
   ///     // numbers[oldStart] == 10
   ///
@@ -197,7 +197,26 @@ extension MutableCollection where Self: BidirectionalCollection {
   ///
   /// - Complexity: O(*n*)
   @discardableResult
+  public mutating func rotate(toStartAt newStart: Index) -> Index {
+    rotate(subrange: startIndex..<endIndex, toStartAt: newStart)
+  }
+}
+
+// Deprecations
+
+extension MutableCollection {
+  @available(*, deprecated, renamed: "rotate(subrange:toStartAt:)")
+  @discardableResult
+  public mutating func rotate(
+    subrange: Range<Index>,
+    at newStart: Index) -> Index
+  {
+    rotate(subrange: subrange, toStartAt: newStart)
+  }
+  
+  @available(*, deprecated, renamed: "rotate(toStartAt:)")
+  @discardableResult
   public mutating func rotate(at newStart: Index) -> Index {
-    rotate(subrange: startIndex..<endIndex, at: newStart)
+    rotate(toStartAt: newStart)
   }
 }

Tests/SwiftAlgorithmsTests/RotateTests.swift

@@ -18,9 +18,9 @@ final class RotateTests: XCTestCase {
       let a = Array(0..<length)
       var b = a
       for j in 0..<length {
-        let i = b.rotate(at: j)
+        let i = b.rotate(toStartAt: j)
         XCTAssertEqualSequences(a[j...] + a[..<j], b)
-        b.rotate(at: i)
+        b.rotate(toStartAt: i)
         XCTAssertEqual(a, b)
       }
     }