Add docs for undocumented methods. Increase unit test coverage.

Author: lorentey

Sources/BTree.swift

@@ -148,7 +148,7 @@ extension BTree: BidirectionalCollection {
 
     /// Returns the successor of the given index.
     ///
-    /// - Requires: `index` is valid of this tree and it is not equal to `endIndex`.
+    /// - Requires: `index` is a valid index of this tree and it is not equal to `endIndex`.
     /// - Complexity: Amortized O(1).
     public func index(after index: Index) -> Index {
         checkIndex(index)
@@ -159,7 +159,7 @@ extension BTree: BidirectionalCollection {
 
     /// Replaces the given index with its successor.
     ///
-    /// - Requires: `index` is valid of this tree and it is not equal to `endIndex`.
+    /// - Requires: `index` is a valid index of this tree and it is not equal to `endIndex`.
     /// - Complexity: Amortized O(1).
     public func formIndex(after index: inout Index) {
         checkIndex(index)
@@ -168,7 +168,7 @@ extension BTree: BidirectionalCollection {
 
     /// Returns the predecessor of the given index.
     ///
-    /// - Requires: `index` is valid of this tree and it is not equal to `startIndex`.
+    /// - Requires: `index` is a valid index of this tree and it is not equal to `startIndex`.
     /// - Complexity: Amortized O(1).
     public func index(before index: Index) -> Index {
         checkIndex(index)
@@ -179,7 +179,7 @@ extension BTree: BidirectionalCollection {
 
     /// Replaces the given index with its predecessor.
     ///
-    /// - Requires: `index` is valid of this tree and it is not equal to `startIndex`.
+    /// - Requires: `index` is a valid index of this tree and it is not equal to `startIndex`.
     /// - Complexity: Amortized O(1).
     public func formIndex(before index: inout Index) {
         checkIndex(index)
@@ -212,7 +212,7 @@ extension BTree: BidirectionalCollection {
 
     /// Returns an index that is the specified distance from the given index, unless that distance is beyond a given limiting index.
     ///
-    /// - Requires: `index` must be a valid index in this tree. The operation must not advance the index beyond `endIndex` or before `startIndex`.
+    /// - Requires: `index` and `limit` must be valid indices of this tree. The operation must not advance the index beyond `endIndex` or before `startIndex`.
     /// - Complexity: O(log(*count*)) where *count* is the number of elements in the tree.
     public func index(_ i: Index, offsetBy n: Int, limitedBy limit: Index) -> Index? {
         checkIndex(i)
@@ -228,7 +228,7 @@ extension BTree: BidirectionalCollection {
 
     /// Offsets the given index by the specified distance, or so that it equals the given limiting index.
     ///
-    /// - Requires: `index` must be a valid index in this tree. The operation must not advance the index beyond `endIndex` or before `startIndex`.
+    /// - Requires: `index` and `limit` must be valid indices of this tree. The operation must not advance the index beyond `endIndex` or before `startIndex`.
     /// - Complexity: O(log(*count*)) where *count* is the number of elements in the tree.
     @discardableResult
     public func formIndex(_ i: inout Index, offsetBy n: Int, limitedBy limit: Index) -> Bool {
@@ -240,6 +240,7 @@ extension BTree: BidirectionalCollection {
 
     /// Returns the distance between two indices.
     ///
+    /// - Requires: `start` and `end` must be valid indices in this tree.
     /// - Complexity: O(1)
     public func distance(from start: Index, to end: Index) -> Int {
         checkIndex(start)

Sources/BTreeCursor.swift

@@ -692,15 +692,14 @@ public final class BTreeCursor<Key: Comparable, Value> {
             split.suffix.insert(split.separator, atOffset: 0)
             return split.suffix
         }
-        else {
-            let (left, sep1, tail) = state.split()
-            state = State(root: tail.root, offset: n - 1)
-            var (mid, sep2, right) = state.split()
-            state.invalidate()
-            let j = Node.join(left: left.root, separator: sep2, right: right.root)
-            state = State(root: j, offset: offset)
-            mid.insert(sep1, atOffset: 0)
-            return mid
-        }
+
+        let (left, sep1, tail) = state.split()
+        state = State(root: tail.root, offset: n - 1)
+        var (mid, sep2, right) = state.split()
+        state.invalidate()
+        let j = Node.join(left: left.root, separator: sep2, right: right.root)
+        state = State(root: j, offset: offset)
+        mid.insert(sep1, atOffset: 0)
+        return mid
     }
 }

Sources/List.swift

@@ -134,41 +134,52 @@ extension List: MutableCollection, BidirectionalCollection {
         return Iterator(tree.makeIterator())
     }
 
+    /// Return the successor value of `index`. This method does not verify that the given index or the result are valid in this list.
     public func index(after index: Index) -> Index {
         return index + 1
     }
 
+    /// Replace `index` by its successor.
+    /// This method does not verify that the given index or the result are valid in this list.
     public func formIndex(after index: inout Index) {
         index += 1
     }
 
+    /// Return the predecessor value of `index`. 
+    /// This method does not verify that the given index or the result are valid in this list.
     public func index(before index: Index) -> Index {
         return index - 1
     }
 
+    /// Replace `index` by its predecessor.
+    /// This method does not verify that the given index or the result are valid in this list.
     public func formIndex(before index: inout Index) {
         index -= 1
     }
 
+    /// Add `n` to `i` and return the result. 
+    /// This method does not verify that the given index or the result are valid in this list.
     public func index(_ i: Index, offsetBy n: Int) -> Index {
         return i + n
     }
 
+    /// Add `n` to `i` in place. 
+    /// This method does not verify that the given index or the result are valid in this list.
+    public func formIndex(_ i: inout Index, offsetBy n: Int) {
+        i += n
+    }
+
+    /// Add `n` to `i` and return the result, unless the result would exceed (or, in case of negative `n`, go under) `limit`, in which case return `nil`.
+    /// This method does not verify that the given indices (or the resulting value) are valid in this list.
     public func index(_ i: Index, offsetBy n: Int, limitedBy limit: Index) -> Index? {
         if (n >= 0 && i + n > limit) || (n < 0 && i + n < limit) {
             return nil
         }
         return i + n
     }
 
-    public func distance(from start: Index, to end: Index) -> Int {
-        return end - start
-    }
-
-    public func formIndex(_ i: inout Index, offsetBy n: Int) {
-        i += n
-    }
-
+    /// Add `n` to `i` in place, unless the result would exceed (or, in case of negative `n`, go under) `limit`, in which case set `i` to `limit`.
+    /// This method does not verify that the given indices (or the resulting value) are valid in this list.
     @discardableResult
     public func formIndex(_ i: inout Index, offsetBy n: Int, limitedBy limit: Index) -> Bool {
         if (n >= 0 && i + n > limit) || (n < 0 && i + n < limit) {
@@ -179,10 +190,18 @@ extension List: MutableCollection, BidirectionalCollection {
         return true
     }
 
+    /// Return the difference between `end` and `start`.
+    /// This method does not verify that the given indices are valid in this list.
+    public func distance(from start: Index, to end: Index) -> Int {
+        return end - start
+    }
+
+    /// Return the first element in this list, or `nil` if the list is empty.
     public var first: Element? {
         return tree.first?.1
     }
 
+    /// Return the last element in this list, or `nil` if the list is empty.
     public var last: Element? {
         return tree.last?.1
     }

Sources/Map.swift

@@ -153,39 +153,79 @@ extension Map: Collection {
         return tree.makeIterator()
     }
 
+    /// Returns the successor of the given index.
+    ///
+    /// - Requires: `index` is a valid index of this map and it is not equal to `endIndex`.
+    /// - Complexity: Amortized O(1).
     public func index(after index: Index) -> Index {
         return tree.index(after: index)
     }
 
+    /// Replaces the given index with its successor.
+    ///
+    /// - Requires: `index` is a valid index of this map and it is not equal to `endIndex`.
+    /// - Complexity: Amortized O(1).
     public func formIndex(after index: inout Index) {
         tree.formIndex(after: &index)
     }
 
+    /// Returns the predecessor of the given index.
+    ///
+    /// - Requires: `index` is a valid index of this map and it is not equal to `startIndex`.
+    /// - Complexity: Amortized O(1).
     public func index(before index: Index) -> Index {
         return tree.index(before: index)
     }
 
+    /// Replaces the given index with its predecessor.
+    ///
+    /// - Requires: `index` is a valid index of this map and it is not equal to `startIndex`.
+    /// - Complexity: Amortized O(1).
     public func formIndex(before index: inout Index) {
         tree.formIndex(before: &index)
     }
 
+    /// Returns an index that is the specified distance from the given index.
+    ///
+    /// - Requires: `index` must be a valid index of this map.
+    ///              If `n` is positive, it must not exceed the distance from `index` to `endIndex`.
+    ///              If `n` is negative, it must not be less than the distance from `index` to `startIndex`.
+    /// - Complexity: O(log(*count*)) where *count* is the number of elements in the map.
     public func index(_ i: Index, offsetBy n: Int) -> Index {
         return tree.index(i, offsetBy: n)
     }
 
+    /// Offsets the given index by the specified distance.
+    ///
+    /// - Requires: `index` must be a valid index of this map.
+    ///              If `n` is positive, it must not exceed the distance from `index` to `endIndex`.
+    ///              If `n` is negative, it must not be less than the distance from `index` to `startIndex`.
+    /// - Complexity: O(log(*count*)) where *count* is the number of elements in the map.
     public func formIndex(_ i: inout Index, offsetBy n: Int) {
         tree.formIndex(&i, offsetBy: n)
     }
 
+    /// Returns an index that is the specified distance from the given index, unless that distance is beyond a given limiting index.
+    ///
+    /// - Requires: `index` and `limit` must be valid indices in this map. The operation must not advance the index beyond `endIndex` or before `startIndex`.
+    /// - Complexity: O(log(*count*)) where *count* is the number of elements in the map.
     public func index(_ i: Index, offsetBy n: Int, limitedBy limit: Index) -> Index? {
         return tree.index(i, offsetBy: n, limitedBy: limit)
     }
 
+    /// Offsets the given index by the specified distance, or so that it equals the given limiting index.
+    ///
+    /// - Requires: `index` and `limit` must be valid indices in this map. The operation must not advance the index beyond `endIndex` or before `startIndex`.
+    /// - Complexity: O(log(*count*)) where *count* is the number of elements in the map.
     @discardableResult
     public func formIndex(_ i: inout Index, offsetBy n: Int, limitedBy limit: Index) -> Bool {
         return tree.formIndex(&i, offsetBy: n, limitedBy: limit)
     }
 
+    /// Returns the distance between two indices.
+    ///
+    /// - Requires: `start` and `end` must be valid indices in this map.
+    /// - Complexity: O(1)
     public func distance(from start: Index, to end: Index) -> Int {
         return tree.distance(from: start, to: end)
     }

Sources/SortedSet.swift

@@ -111,39 +111,79 @@ extension SortedSet: Collection {
         return Iterator(tree.makeIterator())
     }
 
+    /// Returns the successor of the given index.
+    ///
+    /// - Requires: `index` is a valid index of this set and it is not equal to `endIndex`.
+    /// - Complexity: Amortized O(1).
     public func index(after index: Index) -> Index {
         return tree.index(after: index)
     }
 
+    /// Replaces the given index with its successor.
+    ///
+    /// - Requires: `index` is a valid index of this set and it is not equal to `endIndex`.
+    /// - Complexity: Amortized O(1).
     public func formIndex(after index: inout Index) {
         tree.formIndex(after: &index)
     }
 
+    /// Returns the predecessor of the given index.
+    ///
+    /// - Requires: `index` is a valid index of this set and it is not equal to `startIndex`.
+    /// - Complexity: Amortized O(1).
     public func index(before index: Index) -> Index {
         return tree.index(before: index)
     }
 
+    /// Replaces the given index with its predecessor.
+    ///
+    /// - Requires: `index` is a valid index of this set and it is not equal to `startIndex`.
+    /// - Complexity: Amortized O(1).
     public func formIndex(before index: inout Index) {
         tree.formIndex(before: &index)
     }
 
+    /// Returns an index that is the specified distance from the given index.
+    ///
+    /// - Requires: `index` must be a valid index of this set.
+    ///              If `n` is positive, it must not exceed the distance from `index` to `endIndex`.
+    ///              If `n` is negative, it must not be less than the distance from `index` to `startIndex`.
+    /// - Complexity: O(log(*count*)) where *count* is the number of elements in the set.
     public func index(_ i: Index, offsetBy n: Int) -> Index {
         return tree.index(i, offsetBy: n)
     }
 
+    /// Offsets the given index by the specified distance.
+    ///
+    /// - Requires: `index` must be a valid index of this set.
+    ///              If `n` is positive, it must not exceed the distance from `index` to `endIndex`.
+    ///              If `n` is negative, it must not be less than the distance from `index` to `startIndex`.
+    /// - Complexity: O(log(*count*)) where *count* is the number of elements in the set.
     public func formIndex(_ i: inout Index, offsetBy n: Int) {
         tree.formIndex(&i, offsetBy: n)
     }
 
+    /// Returns an index that is the specified distance from the given index, unless that distance is beyond a given limiting index.
+    ///
+    /// - Requires: `index` and `limit` must be valid indices in this set. The operation must not advance the index beyond `endIndex` or before `startIndex`.
+    /// - Complexity: O(log(*count*)) where *count* is the number of elements in the set.
     public func index(_ i: Index, offsetBy n: Int, limitedBy limit: Index) -> Index? {
         return tree.index(i, offsetBy: n, limitedBy: limit)
     }
 
+    /// Offsets the given index by the specified distance, or so that it equals the given limiting index.
+    ///
+    /// - Requires: `index` and `limit` must be valid indices in this set. The operation must not advance the index beyond `endIndex` or before `startIndex`.
+    /// - Complexity: O(log(*count*)) where *count* is the number of elements in the set.
     @discardableResult
     public func formIndex(_ i: inout Index, offsetBy n: Int, limitedBy limit: Index) -> Bool {
         return tree.formIndex(&i, offsetBy: n, limitedBy: limit)
     }
 
+    /// Returns the distance between two indices.
+    ///
+    /// - Requires: `start` and `end` must be valid indices in this set.
+    /// - Complexity: O(1)
     public func distance(from start: Index, to end: Index) -> Int {
         return tree.distance(from: start, to: end)
     }
@@ -152,6 +192,21 @@ extension SortedSet: Collection {
 extension SortedSet {
     //MARK: Offset-based access
 
+    /// Returns the offset of the element at `index`.
+    ///
+    /// - Complexity: O(log(`count`))
+    public func index(ofOffset offset: Int) -> Index {
+        return tree.index(ofOffset: offset)
+    }
+
+    /// Returns the index of the element at `offset`.
+    ///
+    /// - Requires: `offset >= 0 && offset < count`
+    /// - Complexity: O(log(`count`))
+    public func offset(of index: Index) -> Int {
+        return tree.offset(of: index)
+    }
+    
     /// Returns the element at `offset` from the start of the set.
     ///
     /// - Complexity: O(log(`count`))
@@ -449,27 +504,28 @@ extension SortedSet {
 extension SortedSet {
     //MARK: Insertion
 
-    /// Insert a member into the set.
+    /// Insert a member into the set if it is not already present.
     ///
+    /// - Returns: `(true, newMember)` if `newMember` was not contained in the set.
+    ///    If an element equal to `newMember` was already contained in the set, the method returns `(false, oldMember)`,
+    ///    where `oldMember` is the element that was equal to `newMember`. In some cases, `oldMember` may be distinguishable
+    ///    from `newMember` by identity comparison or some other means.
     /// - Complexity: O(log(`count`))
     @discardableResult
-    public mutating func insert(_ element: Element) -> (inserted: Bool, memberAfterInsert: Element) {
-        if let old = tree.insertOrFind((element, ())) {
-            return (false, old.0)
-        }
-        else {
-            return (true, element)
+    public mutating func insert(_ newMember: Element) -> (inserted: Bool, memberAfterInsert: Element) {
+        guard let old = tree.insertOrFind((newMember, ())) else {
+            return (true, newMember)
         }
+        return (false, old.0)
     }
 
     /// Inserts the given element into the set unconditionally.
     ///
     /// If an element equal to `newMember` is already contained in the set,
-    /// `newMember` replaces the existing element. In this example, an existing
-    /// element is inserted into `classDays`, a set of days of the week.
+    /// `newMember` replaces the existing element.
     ///
     /// - Parameter newMember: An element to insert into the set.
-    /// - Returns: The element equal to `newMember` that was originally in the set, if exists; otherwise, nil.
+    /// - Returns: The element equal to `newMember` that was originally in the set, if exists; otherwise, `nil`.
     ///   In some cases, the returned element may be distinguishable from `newMember` by identity
     ///   comparison or some other means.
     public mutating func update(with newMember: Element) -> Element? {