Added readme file

Author: Giuseppe Lanza

Introsort/HeapSort.swift

@@ -0,0 +1,50 @@
+import Foundation
+
+private func shiftDown<T>(_ elements: inout [T], _ index: Int, _ range: Range<Int>, by areInIncreasingOrder: (T, T) -> Bool) {
+    let countToIndex = elements.distance(from: range.lowerBound, to: index)
+    let countFromIndex = elements.distance(from: index, to: range.upperBound)
+    
+    guard countToIndex + 1 < countFromIndex else { return }
+    
+    let left = elements.index(index, offsetBy: countToIndex + 1)
+    var largest = index
+    if areInIncreasingOrder(elements[largest], elements[left]) {
+        largest = left
+    }
+    
+    if countToIndex + 2 < countFromIndex {
+        let right = elements.index(after: left)
+        if areInIncreasingOrder(elements[largest], elements[right]) {
+            largest = right
+        }
+    }
+
+    if largest != index {
+        elements.swapAt(index, largest)
+        shiftDown(&elements, largest, range, by: areInIncreasingOrder)
+    }
+    
+}
+
+private func heapify<T>(_ list: inout [T], _ range: Range<Int>, by areInIncreasingOrder: (T, T) -> Bool) {
+    let root = range.lowerBound
+    var node = list.index(root, offsetBy: list.distance(from: range.lowerBound, to: range.upperBound)/2)
+    
+    while node != root {
+        list.formIndex(before: &node)
+        shiftDown(&list, node, range, by: areInIncreasingOrder)
+    }
+}
+
+public func heapsort<T>(for array: inout [T], range: Range<Int>, by areInIncreasingOrder: (T, T) -> Bool) {
+    var hi = range.upperBound
+    let lo = range.lowerBound
+    heapify(&array, range, by: areInIncreasingOrder)
+    array.formIndex(before: &hi)
+    
+    while hi != lo {
+        array.swapAt(lo, hi)
+        shiftDown(&array, lo, lo..<hi, by: areInIncreasingOrder)
+        array.formIndex(before: &hi)
+    }
+}

Introsort/InsertionSort.swift

@@ -0,0 +1,28 @@
+import Foundation
+
+public func insertionSort<T>(for array: inout [T], range: Range<Int>, by areInIncreasingOrder: (T, T) -> Bool) {
+    guard !range.isEmpty else { return }
+    
+    let start = range.lowerBound
+    var sortedEnd = start
+    
+    array.formIndex(after: &sortedEnd)
+    while sortedEnd != range.upperBound {
+        let x = array[sortedEnd]
+        
+        var i = sortedEnd
+        repeat {
+            let predecessor = array[array.index(before: i)]
+            
+            guard areInIncreasingOrder(x, predecessor) else { break }
+            array[i] = predecessor
+            array.formIndex(before: &i)
+        } while i != start
+        
+        if i != sortedEnd {
+            array[i] = x
+        }
+        array.formIndex(after: &sortedEnd)
+    }
+    
+}

Introsort/IntroSort.swift

@@ -0,0 +1,32 @@
+import Foundation
+
+public func introsort<T>(_ array: inout [T],  by areInIncreasingOrder: (T, T) -> Bool) {
+    //The depth limit is as best practice 2 * log( n )
+    let depthLimit = 2 * floor(log2(Double(array.count)))
+    
+    introSortImplementation(for: &array, range: 0..<array.count, depthLimit: Int(depthLimit), by: areInIncreasingOrder)
+}
+
+///This method is recursively executed for each partition result of the quicksort part of the algorithm
+private func introSortImplementation<T>(for array: inout [T], range: Range<Int>, depthLimit: Int, by areInIncreasingOrder: (T, T) -> Bool) {
+    if array.distance(from: range.lowerBound, to: range.upperBound) < 20 {
+        //if the partition count is less than 20 we can sort it using insertion sort. This algorithm in fact performs well on collections
+        //of this size, plus, at this point is quite probable that the quisksort part of the algorithm produced a partition which is
+        //nearly sorted. As we knoe insertion sort tends to O( n ) if this is the case.
+        insertionSort(for: &array, range: range, by: areInIncreasingOrder)
+    } else if depthLimit == 0 {
+        //If we reached the depth limit for this recursion branch, it's possible that we are hitting quick sort's worst case.
+        //Since quicksort degrades to O( n^2 ) in its worst case we stop using quicksort for this recursion branch and we switch to heapsort.
+        //Our preference remains quicksort, and we hope to be rare to see this condition to be true
+        heapsort(for: &array, range: range, by: areInIncreasingOrder)
+    } else {
+        //By default we use quicksort to sort our collection. The partition index method chose a pivot, and puts all the
+        //elements less than pivot on the left, and the ones bigger than pivot on the right. At the end of the operation the
+        //position of the pivot in the array is returned so that we can form the two partitions.
+        let partIdx = partitionIndex(for: &array, subRange: range, by: areInIncreasingOrder)
+        
+        //We can recursively call introsort implementation, decreasing the depthLimit for the left partition and the right partition.
+        introSortImplementation(for: &array, range: range.lowerBound..<partIdx, depthLimit: depthLimit &- 1, by: areInIncreasingOrder)
+        introSortImplementation(for: &array, range: partIdx..<range.upperBound, depthLimit: depthLimit &- 1, by: areInIncreasingOrder)
+    }
+}

Introsort/Partition.swift

@@ -0,0 +1,43 @@
+import Foundation
+
+public func partitionIndex<T>(for elements: inout [T], subRange range: Range<Int>, by areInIncreasingOrder: (T, T) -> Bool) -> Int {
+    var lo = range.lowerBound
+    var hi = elements.index(before: range.upperBound)
+    
+    // Sort the first, middle, and last elements, then use the middle value
+    // as the pivot for the partition.
+    let half = elements.distance(from: lo, to: hi) / 2
+    let mid = elements.index(lo, offsetBy: half)
+    
+    sort3(in: &elements, a: lo, b: mid, c: hi, by: areInIncreasingOrder)
+    let pivot = elements[mid]
+    
+    while true {
+        elements.formIndex(after: &lo)
+        guard findLo(in: elements, pivot: pivot, from: &lo, to: hi, by: areInIncreasingOrder) else { break }
+        elements.formIndex(before: &hi)
+        guard findHi(in: elements, pivot: pivot, from: lo, to: &hi, by: areInIncreasingOrder) else { break }
+        elements.swapAt(lo, hi)
+    }
+
+    
+    return lo
+}
+
+private func findLo<T>(in array: [T], pivot: T, from lo: inout Int, to hi: Int, by areInIncreasingOrder: (T, T)->Bool) -> Bool {
+    while lo != hi {
+        if !areInIncreasingOrder(array[lo], pivot) {
+            return true
+        }
+        array.formIndex(after: &lo)
+    }
+    return false
+}
+
+private func findHi<T>(in array: [T], pivot: T, from lo: Int, to hi: inout Int, by areInIncreasingOrder: (T, T)->Bool) -> Bool {
+    while hi != lo {
+        if areInIncreasingOrder(array[hi], pivot) { return true }
+        array.formIndex(before: &hi)
+    }
+    return false
+}

Introsort/README.markdown

@@ -0,0 +1,110 @@
+# IntroSort
+
+Goal: Sort an array from low to high (or high to low).
+
+IntroSort is the algorithm used by swift to sort a collection. Introsort is an hybrid algorithm invented by David Musser  in 1993 with the purpose of giving a generic sorting algorithm for the C++ standard library. The classic implementation of introsort expect a recursive Quicksort with fallback to Heapsort in case the recursion depth level reached a certain max. The maximum depends on the number of elements in the collection and it is usually 2 * log(n). The reason behind this “fallback” is that if Quicksort was not able to get the solution after 2 * log(n) recursions for a branch, probably it hit its worst case and it is degrading to complexity O( n^2 ). To optimise even further this algorithm, the swift implementation introduce an extra step in each recursion where the partition is sorted using InsertionSort if the count of the partition is less than 20.
+
+The number 20 is an empiric number obtained observing the behaviour of InsertionSort with lists of this size.
+
+Here's an implementation in Pseudocode:
+
+```
+procedure sort(A : array):
+    let maxdepth = ⌊log(length(A))⌋ × 2
+    introSort(A, maxdepth)
+
+procedure introsort(A, maxdepth):
+    n ← length(A)
+    if n < 20:
+        insertionsort(A)
+    else if maxdepth = 0:
+        heapsort(A)
+    else:
+        p ← partition(A)  // the pivot is selected using median of 3
+        introsort(A[0:p], maxdepth - 1)
+        introsort(A[p+1:n], maxdepth - 1)
+```
+
+## An example
+
+Let's walk through the example. The array is initially:
+
+	[ 10, 0, 3, 9, 2, 14, 8, 27, 1, 5, 8, -1, 26 ]
+
+
+for this example let's assume that `maxDepth` is **2** and that the size of the partition for the insertionSort to kick in is **5**
+
+At the first iteration we run introSort on the full collection that counts 13 elements. the maxDepth is 2, therefore we fall in the else case where quicksort acts.
+
+The `partition`  method picks the first element, the median and the last, it sorts them and uses the new median as pivot.
+
+    [ 10, 8, 26 ] -> [ 8, 10, 26 ]
+    
+Our array is now
+
+    [ 8, 0, 3, 9, 2, 14, 10, 27, 1, 5, 8, -1, 26 ]
+
+**10** is the pivot. After the choice of the pivot, the `partition` method swaps elements to get all the elements less than pivot on the left, and all the elements more or equal than pivot on the right.
+
+    [ 8, 0, 3, 9, 2, 1, 5, 8, -1, 10, 27, 14, 26 ]
+    
+Because of the swaps, the index of of pivot is now changed and returned. The next step of introsort is to call recursively itself for the two sub arrays:
+
+    less: [ 8, 0, 3, 9, 2, 1, 5, 8, -1, 10 ]
+    greater: [ 27, 14, 26 ]
+
+## maxDepth: 1, branch: less
+
+    [ 8, 0, 3, 9, 2, 1, 5, 8, -1, 10 ]
+
+The count of the array is still more than 5 so we don't meet yet the conditions for insertion sort to kick in. At this iteration maxDepth is decreased by one but it is still more than zero, so heapsort will not act.
+
+Just like in the previous iteration quicksort wins and the `partition` method choses a pivot and sorts the elemets less than pivot on the left and the elements more or equeal than pivot on the right.
+
+    array: [ 8, 0, 3, 9, 2, 1, 5, 8, -1, 10 ]
+    pivot candidates: [ 8, 1, 10] -> [ 1, 8, 10]
+    pivot: 8
+    before partition: [ 1, 0, 3, 9, 2, 8, 5, 8, -1, 10 ]
+    after partition: [ 1, 0, 3, -1, 2, 5, 8, 8, 9, 10 ]
+    
+    less: [ 1, 0, 3, -1, 2, 5, 8 ]
+    greater: [ 8, 9, 10 ]
+    
+## maxDepth: 0, branch: less
+
+    [ 1, 0, 3, -1, 2, 5, 8 ]
+    
+Just like before, introsort is recursively executed for `less` and greater. This time `less`has a count more than **5** so it will not be sorted with insertion sort, but the maxDepth decreased again by 1 is now 0 and heapsort takes over sorting the array.
+
+    heapsort -> [ -1, 0, 1, 2, 3, 5, 8 ]
+    
+## maxDepth: 0, branch: greater
+
+    [ 8, 9, 10 ]
+
+following greater in this recursion, the count of elements is 3, which is less than 5, so this partition is sorted using insertionSort.
+
+    insertionSort -> [ 8, 9 , 10]
+    
+
+## back to maxDepth = 1, branch: greater
+
+    [ 27, 14, 26 ]
+
+At this point the original array has mutated to be
+
+    [ -1, 0, 1, 2, 3, 5, 8, 8, 9, 10, 27, 14, 26 ]
+    
+now the `less` partition is sorted  and since the count of the `greater` partition is 3 it will be sorted with insertion sort  `[ 14, 26, 27 ]`
+
+The array is now successfully sorted
+
+    [ -1, 0, 1, 2, 3, 5, 8, 8, 9, 10, 14, 26, 27 ]
+
+
+## See also
+
+[Introsort on Wikipedia](https://en.wikipedia.org/wiki/Introsort)
+[Introsort comparison with other sorting algorithms](http://agostini.tech/2017/12/18/swift-sorting-algorithm/)
+
+*Written for Swift Algorithm Club by Giuseppe Lanza*

Introsort/Randomize.swift

@@ -0,0 +1,9 @@
+import Foundation
+
+public func randomize(n: Int) -> [Int] {
+    var unsorted = [Int]()
+    for _ in 0..<n {
+        unsorted.append(Int(arc4random()))
+    }
+    return unsorted
+}

Introsort/Sort3.swift

@@ -0,0 +1,21 @@
+import Foundation
+
+public func sort3<T>(in array: inout [T], a: Int, b: Int, c: Int, by areInIncreasingOrder: (T, T) -> Bool) {
+    switch (areInIncreasingOrder(array[b], array[a]),
+            areInIncreasingOrder(array[c], array[b])) {
+    case (false, false): break
+    case (true, true): array.swapAt(a, c)
+    case (true, false):
+        array.swapAt(a, b)
+        
+        if areInIncreasingOrder(array[c], array[b]) {
+            array.swapAt(b, c)
+        }
+    case (false, true):
+        array.swapAt(b, c)
+        
+        if areInIncreasingOrder(array[b], array[a]) {
+            array.swapAt(a, b)
+        }
+    }
+}

README.markdown

@@ -73,6 +73,10 @@ Fast sorts:
 - [Merge Sort](Merge%20Sort/)
 - [Heap Sort](Heap%20Sort/)
 
+Hybrid sorts:
+
+- [Introsort](Introsort/)
+
 Special-purpose sorts:
 
 - [Counting Sort](Counting%20Sort/)