Docs

Author: rockbruno

Guides/PartialSort.md

@@ -5,7 +5,7 @@
 
 Returns the first k elements of this collection when it's sorted.
 
-If you need to sort a sequence but only need access to a prefix of its
+If you need to sort a collection but only need access to a prefix of its
 elements, using this method can give you a performance boost over sorting 
 the entire collection. The order of equal elements is guaranteed to be
 preserved.

Sources/Algorithms/PartialSort.swift

@@ -8,12 +8,28 @@
 // See https://swift.org/LICENSE.txt for license information
 //
 
-//===----------------------------------------------------------------------===//
-// sortedPrefix(_:by:)
-//===----------------------------------------------------------------------===//
-
 extension Collection {
-
+  /// Returns the first k elements of this collection when it's sorted using
+  /// the given predicate as the comparison between elements.
+  ///
+  /// This example partially sorts an array of integers to retrieve its three
+  /// smallest values:
+  ///
+  ///     let numbers = [7,1,6,2,8,3,9]
+  ///     let smallestThree = numbers.sortedPrefix(3, <)
+  ///     // [1, 2, 3]
+  ///
+  /// If you need to sort a collection but only need access to a prefix of its
+  /// elements, using this method can give you a performance boost over sorting
+  /// the entire collection. The order of equal elements is guaranteed to be
+  /// preserved.
+  ///
+  /// - Parameter count: The k number of elements to prefix.
+  /// - Parameter areInIncreasingOrder: A predicate that returns true if its
+  /// first argument should be ordered before its second argument;
+  /// otherwise, false.
+  ///
+  /// - Complexity: O(k log k + nk)
   public func sortedPrefix(
     _ count: Int,
     by areInIncreasingOrder: (Element, Element) throws -> Bool
@@ -35,17 +51,35 @@ extension Collection {
     var result = try self.prefix(count).sorted(by: areInIncreasingOrder)
     for e in self.dropFirst(count) {
       if let last = result.last, try areInIncreasingOrder(last, e) { continue }
-      if let insertionIndex = try result.firstIndex  (where: { try areInIncreasingOrder(e, $0) }) {
+      if let insertionIndex = try result.firstIndex(where: { try areInIncreasingOrder(e, $0) }) {
         result.insert(e, at: insertionIndex)
         result.removeLast()
       }
     }
+
     return result
   }
 }
 
 extension Collection where Element: Comparable {
-
+  /// Returns the first k elements of this collection when it's sorted using
+  /// the given predicate as the comparison between elements.
+  ///
+  /// This example partially sorts an array of integers to retrieve its three
+  /// smallest values:
+  ///
+  ///     let numbers = [7,1,6,2,8,3,9]
+  ///     let smallestThree = numbers.sortedPrefix(3, <)
+  ///     // [1, 2, 3]
+  ///
+  /// If you need to sort a collection but only need access to a prefix of its
+  /// elements, using this method can give you a performance boost over sorting
+  /// the entire collection. The order of equal elements is guaranteed to be
+  /// preserved.
+  ///
+  /// - Parameter count: The k number of elements to prefix.
+  ///
+  /// - Complexity: O(k log k + nk)
   public func sortedPrefix(_ count: Int) -> [Element] {
     return sortedPrefix(count, by: <)
   }