Clarify endIndex behavior of partitioningIndex(where:) in documentation (Resolves #170) (#171)

The returned index isn’t necessarily an index of an element. In the case where it returns `endIndex`, it’s not valid for subscripting the collection.

Author: mdznr

Sources/Algorithms/Partition.swift

@@ -168,8 +168,8 @@ extension MutableCollection where Self: BidirectionalCollection {
 //===----------------------------------------------------------------------===//
 
 extension Collection {
-  /// Returns the index of the first element in the collection that matches
-  /// the predicate.
+  /// Returns the start index of the partition of a collection that matches
+  /// the given predicate.
   ///
   /// The collection must already be partitioned according to the predicate.
   /// That is, there should be an index `i` where for every element in
@@ -179,7 +179,8 @@ extension Collection {
   /// - Parameter belongsInSecondPartition: A predicate that partitions the
   ///   collection.
   /// - Returns: The index of the first element in the collection for which
-  ///   `predicate` returns `true`.
+  ///   `predicate` returns `true`, or `endIndex` if there are no elements
+  ///   for which `predicate` returns `true`.
   ///
   /// - Complexity: O(log *n*), where *n* is the length of this collection if
   ///   the collection conforms to `RandomAccessCollection`, otherwise O(*n*).

Tests/SwiftAlgorithmsTests/PartitionTests.swift

@@ -92,6 +92,26 @@ final class PartitionTests: XCTestCase {
     }
   }
 
+  func testPartitioningIndexWithEmptyInput() {
+    let input: [Int] = []
+    
+    let a = input.partitioningIndex(where: { _ in return true })
+    XCTAssertEqual(a, input.startIndex)
+    
+    let b = input.partitioningIndex(where: { _ in return false })
+    XCTAssertEqual(b, input.endIndex)
+  }
+  
+  func testPartitioningIndexWithOneEmptyPartition() {
+    let input: Range<Int> = (0 ..< 10)
+    
+    let a = input.partitioningIndex(where: { $0 > 10 })
+    XCTAssertEqual(a, input.endIndex)
+    
+    let b = input.partitioningIndex(where: { $0 >= 0 })
+    XCTAssertEqual(b, input.startIndex)
+  }
+  
   func testPartitionWithSubrangeBidirectionalCollection() {
     for length in 10...20 {
       let a = Array(0..<length)