Add ctor for instantiating with a collection of Hashables

Author: Simon Whitaker

Multiset/Multiset.playground/Contents.swift

@@ -24,3 +24,8 @@ set2.add("Foo")
 
 set2.isSubSet(of: set) // true
 set.isSubSet(of: set2) // false
+
+var cacti = Multiset<Character>("cacti")
+var tactical = Multiset<Character>("tactical")
+cacti.isSubSet(of: tactical) // true
+tactical.isSubSet(of: cacti) // false

Multiset/Multiset.playground/Sources/Multiset.swift

@@ -7,18 +7,24 @@
 
 import Foundation
 
-public struct Multiset<Element: Hashable> {
-  private var storage: [Element: UInt] = [:]
+public struct Multiset<T: Hashable> {
+  private var storage: [T: UInt] = [:]
   public private(set) var count: UInt = 0
 
   public init() {}
 
-  public mutating func add (_ elem: Element) {
+  public init<C: Collection>(_ collection: C) where C.Element == T {
+    for element in collection {
+      self.add(element)
+    }
+  }
+
+  public mutating func add (_ elem: T) {
     storage[elem, default: 0] += 1
     count += 1
   }
 
-  public mutating func remove (_ elem: Element) {
+  public mutating func remove (_ elem: T) {
     if let currentCount = storage[elem] {
       if currentCount > 1 {
         storage[elem] = currentCount - 1
@@ -29,7 +35,7 @@ public struct Multiset<Element: Hashable> {
     }
   }
 
-  public func isSubSet (of superset: Multiset<Element>) -> Bool {
+  public func isSubSet (of superset: Multiset<T>) -> Bool {
     for (key, count) in storage {
       let supersetcount = superset.storage[key] ?? 0
       if count > supersetcount {
@@ -39,12 +45,12 @@ public struct Multiset<Element: Hashable> {
     return true
   }
 
-  public func count(for key: Element) -> UInt {
+  public func count(for key: T) -> UInt {
     return storage[key] ?? 0
   }
 
-  public var allItems: [Element] {
-    var result = [Element]()
+  public var allItems: [T] {
+    var result = [T]()
     for (key, count) in storage {
       for _ in 0 ..< count {
         result.append(key)
@@ -56,7 +62,7 @@ public struct Multiset<Element: Hashable> {
 
 // MARK: - Equatable
 extension Multiset: Equatable {
-  public static func == (lhs: Multiset<Element>, rhs: Multiset<Element>) -> Bool {
+  public static func == (lhs: Multiset<T>, rhs: Multiset<T>) -> Bool {
     if lhs.storage.count != rhs.storage.count {
       return false
     }

Multiset/README.markdown

@@ -2,20 +2,30 @@
 
 A multiset (also known as a bag) is a data structure similar to a regular set, but it can store multiple instances of the same element.
 
-The following all represent the same *set*, but do not represent the same *multiset*.
+For example, if I added the elements 1, 2, 2 to a regular set, the set would only contain two items, since adding 2 a second time has no effect.
 
 ```
-[1, 3, 2]
-[1, 3, 2, 2]
+var set = Set<Int>()
+set.add(1) // set is now [1]
+set.add(2) // set is now [1, 2]
+set.add(2) // set is still [1, 2]
 ```
 
-In this multiset implementation, ordering is unimportant. So these two multisets are identical:
+By comparison, after adding the elements 1, 2, 2 to a multiset, it would contain three items.
 
 ```
-[1, 2, 2]
-[2, 1, 2]
+var set = Multiset<Int>()
+set.add(1) // set is now [1]
+set.add(2) // set is now [1, 2]
+set.add(2) // set is now [1, 2, 2]
 ```
 
+You might be thinking that this looks an awful lot like an array. So why would you use a multiset? Let's consider the differences between the two…
+
+- Ordering: arrays maintain the order of items added to them, multisets do not
+- Testing for membership: testing whether an element is a member of the collection is O(N) for arrays, O(1) for multisets.
+- Testing for subset: testing whether collection X is a subset of collection Y is a simple operation for a multiset, but complex for arrays
+
 Typical operations on a multiset are:
 
 - Add an element
@@ -24,6 +34,14 @@ Typical operations on a multiset are:
 - Get the count for the whole set (the number of items that have been added)
 - Check whether it is a subset of another multiset
 
+One real-world use of multisets is to determine whether one string is a partial anagram of another. For example, the word "cacti" is a partial anagrams of "tactical". (In other words, I can rearrange the letters of "tactical" to make "cacti", with some letters left over.)
+
+``` swift
+var cacti = Multiset<Character>("cacti")
+var tactical = Multiset<Character>("tactical")
+cacti.isSubSet(of: tactical) // true!
+```
+
 ## Implementation
 
 Under the hood, this implementation of Multiset uses a dictionary to store a mapping of elements to the number of times they've been added.
@@ -32,11 +50,7 @@ Here's the essence of it:
 
 ``` swift
 public struct Multiset<Element: Hashable> {
-  fileprivate var storage: [Element: UInt]
-  
-  public init() {
-    storage = [:]
-  }
+  private var storage: [Element: UInt] = [:]
 ```
 
 And here's how you'd use this class to create a multiset of strings:
@@ -49,11 +63,7 @@ Adding an element is a case of incrementing the counter for that element, or set
 
 ``` swift
 public mutating func add (_ elem: Element) {
-  if let currentCount = storage[elem] {
-    storage[elem] = currentCount + 1;
-  } else {
-    storage[elem] = 1
-  }
+  storage[elem, default: 0] += 1
 }
 ```
 
@@ -62,6 +72,7 @@ Here's how you'd use this method to add to the set we created earlier:
 ```swift
 set.add("foo")
 set.add("foo") 
+set.allItems // returns ["foo", "foo"]
 ```
 
 Our set now contains two elements, both the string "foo".