Files
swift-algorithms/Guides/Rotate.md
T
2020-10-07 10:24:43 -05:00

2.2 KiB

Rotate

[Source | Tests]

A mutating method that rotates the elements of a collection to new positions.

var numbers = [10, 20, 30, 40, 50, 60]
let p = numbers.rotate(at: 2)
// numbers == [30, 40, 50, 60, 10, 20]
// p == 4 -- numbers[p] == 10

To work around the CoW / slice mutation problem for divide-and-conquer algorithms, which are the idiomatic use case for rotation, this also includes variants that take a range:

var numbers = [10, 20, 30, 40, 50, 60]
numbers.rotate(subrange: 0..<3, at: 1)
// numbers = [20, 30, 10, 40, 50, 60]
numbers.rotate(subrange: 3..<6, at: 4)
// numbers = [20, 30, 10, 50, 60, 40]

Detailed Design

This adds the two MutableCollection methods shown above:

extension MutableCollection {
    mutating func rotate(at p: Index) -> Index

    mutating func rotate(
        subrange: Range<Index>,
        at p: Index
    ) -> Index
}

Complexity

Rotation is a O(n) operation, where n is the length of the range being rotated. The BidirectionalCollection version of rotation significantly lowers the number of swaps required per element, so rotate would need to be a MutableCollection customization point were it adopted by the standard library.

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 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).

Comparison with other langauges

C++: The <algorithm> library defines a rotate function with similar 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).