Merge branch 'master' of https://github.com/zainh96/swift-algorithm-club

Author: 318236213

Ordered Set/README.md

@@ -1,5 +1,166 @@
 # Ordered Set
+An Ordered Set is a collection of unique items in sorted order. Items are usually sorted from least to greatest. The Ordered Set data type is a representation of a [Set in Mathematics](https://en.wikipedia.org/wiki/Set_(mathematics)). It's important to keep in mind that two items can have the same *value* but still may not be equal. 
+For example, we could define "a" and "z" to have the same value (their lengths), but clearly "a" != "z".
+
+### Examples of Ordered Sets
+```
+[1, 2, 3, 6, 8, 10, 1000]
+Where each item (Integers) has it's normal definition of value and equality
+```
+```
+["a", "is", "set", "this"]
+Where each item (String) has it's value equal to it's length
+```
+
+### These are not Ordered Sets
+```
+[1, 1, 2, 3, 5, 8]
+This Set violates the property of uniqueness
+```
+```
+[1, 11, 2, 3]
+This Set violates the sorted property
+```
+
+## The Code
+We'll start by creating our internal representation for the Ordered Set. Since the idea of a set is similar to that of an array, we will use an array to represent our set. Furthermore, since we'll need to keep our set sorted, we need to compare the individual elemants. Thus, any type must conform to the [Comparable Protocol](https://developer.apple.com/library/watchos/documentation/Swift/Reference/Swift_Comparable_Protocol/index.html).
+
+``` swift
+public struct OrderedSet<T: Comparable> {
+    private var internalSet: [T]! = nil
+    
+    // returns size of Set
+    public var count: Int {
+        return internalSet!.count
+    }
+    
+    public init(){
+        internalSet = [T]() // create the internal array on init
+    }
+    ...
+```
+
+Lets take a look at the insert function first. The insert function first checks if the item already exists, and if so returns and does not insert the item. Otherwise, it will insert the item through straight forward iteration. It starts from the first item, and checks to see if this item is larger than the item we want to insert. Once we find such an item, we insert the given item into it's place, and shift the array over to the right by 1.
+
+``` swift
+  // inserts an item
+  public mutating func insert(item: T){
+      if exists(item) {
+          return // don't add an item if it already exists
+      }
+      // if the set is initially empty, we need to simply append the item to internalSet
+      if count == 0 {
+          internalSet.append(item)
+          return
+      }
+        
+      for i in 0..<count {
+          if internalSet[i] > item {
+            internalSet.insert(item, atIndex: i)
+            return
+          }
+        }
+        
+      // if an item is larger than any item in the current set, append it to the back.
+      internalSet.append(item)
+  }
+```
+The first part of the function checks if the item is already in the set.As we'll see later on, this has an efficiency of **O(log(n) + k)** where k is the number of items with the same value as the item we are inserting. The second part iterates through the interal array so that it can find a spot for our given item. This is at worse **O(n)**. The insert function for arrays has an efficiency of **O(log(n))**, thus making the insert function for our Ordered Set **O(log(n) + k)**.
+
+
+Next we have the `remove` function. First check if the item exists. If not, then return and no nothing. If it does exist, remove it.
+
+``` swift
+    // removes an item if it exists
+    public mutating func remove(item: T) {
+        if !exists(item) {
+            return
+        }
+        
+        internalSet.removeAtIndex(findIndex(item))
+    }
+```
+Again, because of the `exists` function, the efficiency for remove is **O(log(n) + k)**
+
+The next function is the `findIndex` function which takes in an item of type `T` and returns the index of the item if it is in the set, otherwise returns -1. 
+
+``` swift
+// returns the index of an item if it exists, otherwise returns -1.
+    public func findIndex(item: T) -> Int {
+        var leftBound = 0
+        var rightBound = count - 1
+        
+        while leftBound <= rightBound {
+            let mid = leftBound + ((rightBound - leftBound) / 2)
+            
+            if internalSet[mid] > item {
+                rightBound = mid - 1
+            } else if internalSet[mid] < item {
+                leftBound = mid + 1
+            } else {
+                // check the mid value to see if it is the item we are looking for
+                if internalSet[mid] == item {
+                    return mid
+                }
+                
+                var j = mid
+                
+                // check right side of mid
+                while j < internalSet.count - 1 && !(internalSet[j] < internalSet[j + 1]) {
+                    if internalSet[j + 1] == item {
+                        return j + 1
+                    }
+                    
+                    j += 1
+                }
+                
+                j = mid
+                
+                // check left side of mid
+                while j > 0 && !(internalSet[j] < internalSet[j - 1]) {
+                    if internalSet[j - 1] == item {
+                        return j - 1
+                    }
+                    
+                    j -= 1
+                }
+                return -1
+            }
+        }
+        
+        return -1
+    }
+```
+Since our set is sorted, we can use a binary search to quickly search for the item. If you are not familiar with the concept of binary search, we have an article all about it [here](../Binary\ Search). 
+
+Since a set can contain multiple items with the same *value*, it is important to check to see if we have the correct item.
+
+For example, consider this Ordered  Set
+```
+["a", "b", "c", "longer string", "even longer string"]
+Where the value of each String is equal to it's length.
+```
+The call `findIndex("a")` with the traditional implementation of Binary Search would give us the value of 2, however we know that "a" is located at index 0. Thus, we need to check the items with the same *value* to the right and left of the mid value.
+
+The code to check the left and right side are similar so we will only look at the code that checks the left side.
+``` swift
+    j = mid
+
+    // check left side of mid
+    while j > 0 && !(internalSet[j] < internalSet[j - 1]) {
+        if internalSet[j - 1] == item {
+            return j - 1
+        }
+                    
+        j -= 1
+    }
+    return -1
+```
+First, `j` starts at the mid value. Above, we've already checked to see that the item at index `j` is not equal to the item we are looking for. Then, we keep looping until we either reach the end of the array, or hit an element which has a lower value than the current item at index `j`. If the item at value `j - 1` is equal to the one we are looking for, we return that index, otherwise we keep decreasing `j`. Once the loop terminates, we were unable to find the item and so we return -1. 
+
+The combined runtime for this function is **O(log(n) + k)** where `n` is the length of the set, and `k` is the number of 
+items with the same *value* as the one that is being searched for. 
+
 
-Under Construction
 
 *Written By Zain Humayun*