gitee.com/quant1x/num@v0.3.2/internal/partial/README.md (about)

     1  # partial
     2  
     3  Fast, generic partial sorting algorithms in Go.
     4  
     5  Finding the top k items in a list is often done by sorting it first. This approach is slow for large lists as time is
     6  wasted sorting irrelevant items. The partial package provides a number of generic partial sorting algorithms to find
     7  them more efficiently. The interface mirrors that of Go's slices package. See below for benchmarks comparing performance
     8  to Go's standard sort.
     9  
    10  ## Installation
    11  
    12  ```shell
    13  go get -u github.com/viterin/partial
    14  ```
    15  
    16  ## Example usage
    17  
    18  ### Partial sort
    19  
    20  The `partial.Sort` function takes a slice of any ordered type and the number of elements to sort:
    21  
    22  ```go
    23  s := []int{9, 2, 5, -1, 4}
    24  partial.Sort(s, 2)
    25  fmt.Println(s[:2]) // [-1 2]
    26  ```
    27  
    28  The `partial.SortFunc` function accepts a slice of any type and sorts using a custom ordering function:
    29  
    30  ```go
    31  type Person struct {
    32      Name string
    33      Age  int
    34  }
    35  s := []Person{
    36      {"Karl", 39},
    37      {"Jane", 31},
    38      {"Bob", 45},
    39      {"Ann", 19},
    40  }
    41  partial.SortFunc(s, 2, func(a, b Person) bool { return a.Age > b.Age })
    42  fmt.Println(s[:2]) // [{Bob 45}, {Karl 39}]
    43  ```
    44  
    45  ### Top k elements
    46  
    47  The `partial.TopK` function places the smallest k elements of a slice in front, but only guarantees that the kth element
    48  is in sorted order. This can be significantly faster than a partial sort if the order among the elements is unimportant,
    49  especially for large k:
    50  
    51  ```go
    52  s := []int{9, 2, 5, -1, 4}
    53  partial.TopK(s, 3)
    54  fmt.Println(s[:3]) // [-1 2 4] or [2 -1 4]
    55  ```
    56  
    57  The `partial.TopKFunc` accepts a slice of any type and a custom ordering function.
    58  
    59  ## Benchmarks
    60  
    61  ### Partial sort
    62  
    63  Sorting the first 100 elements of various sized slices (times in microseconds):
    64  
    65  |                      | **1,000** | **10,000** | **100,000** |
    66  |----------------------|-----------|------------|-------------|
    67  | **sort.Slice**       | 22        | 597        | 8,237       |
    68  | **slices.Sort**      | 9         | 344        | 5,080       |
    69  | **slices.SortFunc**  | 21        | 495        | 7,121       |
    70  | **partial.Sort**     | **3**     | **7**      | **107**     |
    71  | **partial.SortFunc** | 8         | 28         | 347         |
    72  
    73  ### Top k elements
    74  
    75  Selecting the top 50% of various sized slices (times in microseconds):
    76  
    77  |                      | **1,000** | **10,000** | **100,000** |
    78  |----------------------|-----------|------------|-------------|
    79  | **slices.Sort**      | 9         | 344        | 5,080       |
    80  | **slices.SortFunc**  | 21        | 495        | 7,121       |
    81  | **partial.Sort**     | 6         | 194        | 3,010       |
    82  | **partial.SortFunc** | 14        | 297        | 4,295       |
    83  | **partial.TopK**     | **2**     | **15**     | **585**     |
    84  | **partial.TopKFunc** | 6         | 61         | 913         |