Coverage Report

Created: 2025-12-11 07:11

next uncovered line (L), next uncovered region (R), next uncovered branch (B)
/rust/registry/src/index.crates.io-1949cf8c6b5b557f/itertools-0.14.0/src/k_smallest.rs
Line
Count
Source
1
use alloc::vec::Vec;
2
use core::cmp::Ordering;
3
4
/// Consumes a given iterator, returning the minimum elements in **ascending** order.
5
0
pub(crate) fn k_smallest_general<I, F>(iter: I, k: usize, mut comparator: F) -> Vec<I::Item>
6
0
where
7
0
    I: Iterator,
8
0
    F: FnMut(&I::Item, &I::Item) -> Ordering,
9
{
10
    /// Sift the element currently at `origin` away from the root until it is properly ordered.
11
    ///
12
    /// This will leave **larger** elements closer to the root of the heap.
13
0
    fn sift_down<T, F>(heap: &mut [T], is_less_than: &mut F, mut origin: usize)
14
0
    where
15
0
        F: FnMut(&T, &T) -> bool,
16
    {
17
        #[inline]
18
0
        fn children_of(n: usize) -> (usize, usize) {
19
0
            (2 * n + 1, 2 * n + 2)
20
0
        }
21
22
0
        while origin < heap.len() {
23
0
            let (left_idx, right_idx) = children_of(origin);
24
0
            if left_idx >= heap.len() {
25
0
                return;
26
0
            }
27
28
0
            let replacement_idx =
29
0
                if right_idx < heap.len() && is_less_than(&heap[left_idx], &heap[right_idx]) {
30
0
                    right_idx
31
                } else {
32
0
                    left_idx
33
                };
34
35
0
            if is_less_than(&heap[origin], &heap[replacement_idx]) {
36
0
                heap.swap(origin, replacement_idx);
37
0
                origin = replacement_idx;
38
0
            } else {
39
0
                return;
40
            }
41
        }
42
0
    }
43
44
0
    if k == 0 {
45
0
        iter.last();
46
0
        return Vec::new();
47
0
    }
48
0
    if k == 1 {
49
0
        return iter.min_by(comparator).into_iter().collect();
50
0
    }
51
0
    let mut iter = iter.fuse();
52
0
    let mut storage: Vec<I::Item> = iter.by_ref().take(k).collect();
53
54
0
    let mut is_less_than = move |a: &_, b: &_| comparator(a, b) == Ordering::Less;
55
56
    // Rearrange the storage into a valid heap by reordering from the second-bottom-most layer up to the root.
57
    // Slightly faster than ordering on each insert, but only by a factor of lg(k).
58
    // The resulting heap has the **largest** item on top.
59
0
    for i in (0..=(storage.len() / 2)).rev() {
60
0
        sift_down(&mut storage, &mut is_less_than, i);
61
0
    }
62
63
0
    iter.for_each(|val| {
64
0
        debug_assert_eq!(storage.len(), k);
65
0
        if is_less_than(&val, &storage[0]) {
66
0
            // Treating this as an push-and-pop saves having to write a sift-up implementation.
67
0
            // https://en.wikipedia.org/wiki/Binary_heap#Insert_then_extract
68
0
            storage[0] = val;
69
0
            // We retain the smallest items we've seen so far, but ordered largest first so we can drop the largest efficiently.
70
0
            sift_down(&mut storage, &mut is_less_than, 0);
71
0
        }
72
0
    });
73
74
    // Ultimately the items need to be in least-first, strict order, but the heap is currently largest-first.
75
    // To achieve this, repeatedly,
76
    // 1) "pop" the largest item off the heap into the tail slot of the underlying storage,
77
    // 2) shrink the logical size of the heap by 1,
78
    // 3) restore the heap property over the remaining items.
79
0
    let mut heap = &mut storage[..];
80
0
    while heap.len() > 1 {
81
0
        let last_idx = heap.len() - 1;
82
0
        heap.swap(0, last_idx);
83
0
        // Sifting over a truncated slice means that the sifting will not disturb already popped elements.
84
0
        heap = &mut heap[..last_idx];
85
0
        sift_down(heap, &mut is_less_than, 0);
86
0
    }
87
88
0
    storage
89
0
}
90
91
0
pub(crate) fn k_smallest_relaxed_general<I, F>(iter: I, k: usize, mut comparator: F) -> Vec<I::Item>
92
0
where
93
0
    I: Iterator,
94
0
    F: FnMut(&I::Item, &I::Item) -> Ordering,
95
{
96
0
    if k == 0 {
97
0
        iter.last();
98
0
        return Vec::new();
99
0
    }
100
101
0
    let mut iter = iter.fuse();
102
0
    let mut buf = iter.by_ref().take(2 * k).collect::<Vec<_>>();
103
104
0
    if buf.len() < k {
105
0
        buf.sort_unstable_by(&mut comparator);
106
0
        return buf;
107
0
    }
108
109
0
    buf.select_nth_unstable_by(k - 1, &mut comparator);
110
0
    buf.truncate(k);
111
112
0
    iter.for_each(|val| {
113
0
        if comparator(&val, &buf[k - 1]) != Ordering::Less {
114
0
            return;
115
0
        }
116
117
0
        assert_ne!(buf.len(), buf.capacity());
118
0
        buf.push(val);
119
120
0
        if buf.len() == 2 * k {
121
0
            buf.select_nth_unstable_by(k - 1, &mut comparator);
122
0
            buf.truncate(k);
123
0
        }
124
0
    });
125
126
0
    buf.sort_unstable_by(&mut comparator);
127
0
    buf.truncate(k);
128
0
    buf
129
0
}
130
131
#[inline]
132
0
pub(crate) fn key_to_cmp<T, K, F>(mut key: F) -> impl FnMut(&T, &T) -> Ordering
133
0
where
134
0
    F: FnMut(&T) -> K,
135
0
    K: Ord,
136
{
137
0
    move |a, b| key(a).cmp(&key(b))
138
0
}