Implement insertion sort

Author: kylehughes

.jazzy.yaml

@@ -2,4 +2,4 @@ author: "Kyle Hughes"
 author_url: "https://kylehugh.es"
 github_url: https://github.com/kylehughes/sort-state-university
 module: "SortStateUniversity"
-module_version: "1.0.0"
+module_version: "1.1.0"

README.md

@@ -17,8 +17,14 @@ called to produce the next step, and so on, until the output is produced.
 
 Sort State University brings this dream to life.
 
+### Provided Algorithms
+
+- Insertion Sort
+- Merge Sort
+
 ### Use Cases
 
+- Asynchronous sorting
 - Sorting visualizations
 - Et cetera
 
@@ -27,19 +33,20 @@ implementations.
 
 ### The Name
 
-I knew that "sort" and "state" had to be in the name. It seemed natural and funny to append "university."
+I knew that "sort" and "state" had to be in the name. It seemed natural and funny to append "university." There is nothing inherently
+educational about this framework.
 
 ## Usage
 
 ### Create an Algorithm
 
-The input to an algorithm does not need to conform to `Comparable` because the answers to the comparisons are supplied
-by the caller.
-
 ```swift
 var algorithm = MergeSort(input: elements)
 ```
 
+The input to an algorithm does not need to conform to `Comparable` because the answers to the comparisons are supplied
+by the caller.
+
 ### Advance the Algorithm
 
 A mutable algorithm can be called like a function. The return value is the next step in the algorithm: either a
@@ -56,11 +63,11 @@ case let .finished(output):
 
 ### Answer the Comparison
 
-A comparison is a decision about the inherent order of two elements. The answer to a comparison will produce the next 
-state of the algorithm. The caller is responsible for consistently applying the inherent order to the comparisons.
+A comparison is a decision about the inherent order of two elements. The caller is responsible for consistently applying the inherent 
+order to the comparisons. For example, the "inherent order" could be a user's personal preference, so the answer to the comparions 
+would be whichever element the user prefers.
 
-For example, the "inherent order" could be a user's personal preference, so the answer to the comparions would
-be whichever element the user prefers.
+A comparison can be answered directly to produce the next state of the sorting algorithm.
 
 ```swift
 algorithm = comparison(.left)
@@ -72,6 +79,19 @@ or
 algorithm = comparison(.right)
 ```
 
+The answer to a comparison can also be provided to, and mutate, the algorithm directly. Both approaches produce the same result but 
+their calling patterns suit different use cases.
+
+```swift
+algorithm.answer(.left)
+```
+
+or 
+
+```swift
+algorithm.answer(.right)
+```
+
 ### Handle the Sorted Output
 
 The output is a sorted array of elements. Handling this value is an exercise left to the reader.

Sources/SortStateUniversity/Insertion Sort/InsertionSort.swift

@@ -0,0 +1,214 @@
+//
+//  InsertionSort.swift
+//  SortStateUniversity
+//
+//  Created by Kyle Hughes on 6/22/21.
+//
+
+import Foundation
+
+/// A simple sorting algorithm that sorts its elements one at a time.
+///
+/// - SeeAlso: https://en.wikipedia.org/wiki/Insertion_sort
+public struct InsertionSort<Element>: Identifiable {
+    /// A type that represents the collection of the elements that the algorithm is sorting.
+    public typealias Elements = Array<Element>
+    
+    /// The stable identity of the algorithm.
+    public let id: UUID
+    
+    /// The given elements that the algorithm is sorting.
+    ///
+    /// This value is constant and will not change after instantiation.
+    public let input: Elements
+    
+    /// The current result of applying the sorting algorithm to `input`.
+    ///
+    /// This value is "live" and will change as the algorithm is executed. When the algorithm is finished this value
+    /// will contain the sorted result of `input`. It is primarily exposed to allow the internals of the algorithm to
+    /// be observed.
+    ///
+    /// This value should not be used as the final output of the algorithm unless it is known that the algorithm has
+    /// finished. It may be easier to perform `callAsFunction()` and respond to the step that is returned – the output
+    /// will be reported through that function if the algorithm is finished.
+    ///
+    /// - SeeAlso: `outputAfterTransactions`
+    public private(set) var output: Elements
+    
+    /// The position (in `output`) of the element that is currently being sorted.
+    public private(set) var sortingElementIndex: Elements.Index
+    
+    /// The position (in `output`) that is one greater than the last sorted element in `output`.
+    ///
+    /// `output` is sorted when this value is equal to `output.endIndex`.
+    public private(set) var sortedEndIndex: Elements.Index
+    
+    // MARK: Public Initialization
+    
+    /// Creates an algorithm to sort the given input using insertion sort.
+    ///
+    /// - Parameter input: The elements to sort.
+    public init(input: Elements) {
+        self.input = input
+        
+        id = UUID()
+        output = input
+        sortingElementIndex = output.index(after: output.startIndex)
+        sortedEndIndex = sortingElementIndex
+    }
+    
+    // MARK: Private Instance Interface
+    
+    private var adjacentSortedElementIndex: Elements.Index {
+        output.index(before: sortingElementIndex)
+    }
+    
+    private var isNotFinished: Bool {
+        sortedEndIndex < output.endIndex
+    }
+
+    private mutating func advanceToNextIndexToSort() {
+        output.formIndex(after: &sortedEndIndex)
+        sortingElementIndex = sortedEndIndex
+    }
+    
+    @discardableResult
+    private mutating func swapSortingElementWithAdjacentSortedElement() -> Elements.Index {
+        let sortedElementIndex = adjacentSortedElementIndex
+        output.swapAt(sortingElementIndex, sortedElementIndex)
+        
+        return sortedElementIndex
+    }
+    
+    private mutating func swapSortingElementWithAdjacentSortedElementAndAdvanceToNextComparison() {
+        let newSortingElementIndex = swapSortingElementWithAdjacentSortedElement()
+        
+        if output.startIndex < newSortingElementIndex {
+            sortingElementIndex = newSortingElementIndex
+        } else {
+            advanceToNextIndexToSort()
+        }
+    }
+}
+
+// MARK: - SortingAlgorithm Extension
+
+extension InsertionSort: SortingAlgorithm {
+    // MARK: Public Static Interface
+    
+    /// The runtime complexity of the algorithm.
+    public static var complexity: Complexity {
+        .quadratic
+    }
+    
+    /// The unique name of the sorting algorithm.
+    public static var label: SortingAlgorithmLabel {
+        .insertion
+    }
+    
+    /// Returns the number of comparisons that the algorithm will perform, in the worst case, given an input
+    /// with `n` elements.
+    ///
+    /// The algorithm may require fewer total comparisons than returned depending on the state of the input and the
+    /// answers to the comparisons. The algorithm is guaranteed to not require more comparisons than returned.
+    ///
+    /// This value is provably correct and precise. It is not an estimate.
+    ///
+    /// - SeeAlso: http://watson.latech.edu/book/algorithms/algorithmsSorting2.html
+    /// - Parameter n: The number of elements.
+    /// - Returns: The number of comparisons that the algorithm will perform in the worst case.
+    public static func calculateMaximumNumberOfComparisonsInWorstCase(for n: Int) -> Int {
+        guard 1 < n else {
+            return 0
+        }
+        
+        var sum = 0
+        
+        for i in 1 ... n-1 {
+            sum += i
+        }
+        
+        return sum
+    }
+    
+    // MARK: Public Instance Interface
+    
+    /// Answers the current comparison with the given side.
+    ///
+    /// The algorithm is advanced to the state that follows the answer.
+    ///
+    /// If the algorithm is not at a point of comparison then this function will have no effect.
+    ///
+    /// - Parameter answer: The answer to the current comparison.
+    public mutating func answer(_ answer: Comparison<Self>.Side) {
+        guard isNotFinished else {
+            return
+        }
+        
+        switch answer {
+        case .left:
+            advanceToNextIndexToSort()
+        case .right:
+            swapSortingElementWithAdjacentSortedElementAndAdvanceToNextComparison()
+        }
+    }
+    
+    /// Executes the algorithm in its current state and, if possible, advances it to the next state and returns the
+    /// step to the caller.
+    ///
+    /// When the algorithm is not finished this function will return the next comparison that needs to
+    /// be answered to continue the algorithm. When the algorithm is finished this function will return the sorted
+    /// output.
+    ///
+    /// This function is idempotent: for a given state of the algorithm, calling this function will always produce
+    /// the same result and will always leave the algorithm in the same – possibly new – state. Performing this
+    /// function consecutively on the same algorithm will have no additional affect.
+    ///
+    /// - Returns: The next step in the algorithm: either the next comparison to answer, or the sorted output.
+    public func callAsFunction() -> SortingAlgorithmStep<Self> {
+        guard isNotFinished else {
+            return .finished(output)
+        }
+
+        return .comparison(Comparison(source: self))
+    }
+    
+    /// Returns the element that represents the given side of the current comparison.
+    ///
+    /// If the algorithm is not at a point of comparison then `nil` will be returned. For example, if the
+    /// algorithm has not started or is finished then `nil` will be returned.
+    ///
+    /// - Parameter answer: The answer that represents the side of the comparison to peek at.
+    /// - Returns: The element that represents the given side of the current comparison, or `nil` if the algorithm
+    ///   is not at a point of comparison.
+    public func peekAtElement(for answer: Comparison<InsertionSort<Element>>.Side) -> Element? {
+        guard isNotFinished else {
+            return nil
+        }
+        
+        switch answer {
+        case .left:
+            return output[adjacentSortedElementIndex]
+        case .right:
+            return output[sortingElementIndex]
+        }
+    }
+}
+
+// MARK: - Codable Extension
+
+extension InsertionSort: Codable where Element: Codable {
+    // NO-OP
+}
+
+// MARK: - Equatable Extension
+
+extension InsertionSort: Equatable where Element: Equatable {
+    // NO-OP
+}
+
+// MARK: - Hashable Extension
+
+extension InsertionSort: Hashable where Element: Hashable {
+    // NO-OP
+}

Sources/SortStateUniversity/Merge Sort/MergeSort.swift

@@ -7,7 +7,7 @@
 
 import Foundation
 
-/// A divide-and-conquer sorting algorithm, implemented statefully.
+/// A divide-and-conquer sorting algorithm.
 ///
 /// - SeeAlso: https://en.wikipedia.org/wiki/Merge_sort
 public struct MergeSort<Element>: Identifiable {
@@ -64,6 +64,8 @@ public struct MergeSort<Element>: Identifiable {
         ongoingMerge = nil
         output = input
         partitionSize = 1
+        
+        _ = self()
     }
 
     // MARK: Public Instance Interface
@@ -147,6 +149,11 @@ extension MergeSort: SortingAlgorithm {
         .linearithmic
     }
 
+    /// The unique name of the sorting algorithm.
+    public static var label: SortingAlgorithmLabel {
+        .merge
+    }
+    
     /// Returns the number of comparisons that the algorithm will perform, in the worst case, given an input
     /// with `n` elements.
     ///

Sources/SortStateUniversity/SortingAlgorithm.swift

@@ -23,6 +23,9 @@ public protocol SortingAlgorithm: Identifiable {
     /// The runtime complexity of the algorithm.
     static var complexity: Complexity { get }
 
+    /// The unique label of the algorithm.
+    static var label: SortingAlgorithmLabel { get }
+    
     /// Returns the number of comparisons that the algorithm will perform, in the worst case, given an input
     /// with `n` elements.
     ///
@@ -34,7 +37,7 @@ public protocol SortingAlgorithm: Identifiable {
     /// - Parameter n: The number of elements.
     /// - Returns: The number of comparisons that the algorithm will perform in the worst case.
     static func calculateMaximumNumberOfComparisonsInWorstCase(for n: Int) -> Int
-
+    
     // MARK: Instance Interface
 
     /// The given elements that the algorithm is sorting.

Sources/SortStateUniversity/SortingAlgorithmLabel.swift

@@ -0,0 +1,49 @@
+//
+//  SortingAlgorithmLabel.swift
+//  SortStateUniversity
+//
+//  Created by Kyle Hughes on 6/24/21.
+//
+
+/// The type used to uniquely identify a sorting algorithm implementation.
+public struct SortingAlgorithmLabel: Codable, Equatable, Hashable, Identifiable {
+    /// The stable identity of the sorting algorithm label.
+    public let id: String
+    
+    /// The name of the associated sorting algorithm.
+    ///
+    /// Suitable for display in UI.
+    ///
+    /// All names from the library are supplied in English.
+    public let name: String
+    
+    // MARK: Public Initialization
+    
+    /// Creates a new label for a sorting algorithm.
+    ///
+    /// - Parameter name: The name of the sorting algorithm.
+    public init(id: String, name: String) {
+        self.id = id
+        self.name = name
+    }
+}
+
+// MARK: - Constants
+
+extension SortingAlgorithmLabel {
+    // MARK: Collections
+    
+    /// The labels of all sorting algorithms that are built into the library.
+    public static let allBuiltIn: [SortingAlgorithmLabel] = [
+        .insertion,
+        .merge,
+    ]
+    
+    // MARK: Individual Sorts
+    
+    /// The label of the `InsertionSort` algorithm.
+    public static let insertion = SortingAlgorithmLabel(id: "insertion", name: "Insertion Sort")
+    
+    /// The label of the `MergeSort` algorithm.
+    public static let merge = SortingAlgorithmLabel(id: "merge", name: "Merge Sort")
+}