pencil_box/array/
drop_start.rs

1/// Truncates elements from the start of a vector, dropping the specified number of items in place.
2///
3/// # Type Parameters
4/// - `T`: The element type contained in the vector.
5///
6/// # Arguments
7/// - `values`: A mutable reference to the vector from which elements will be removed.
8/// - `no_of_elements_to_drop`: The number of elements to remove from the start of the vector.
9///
10/// # Returns
11/// This function does not return a value. It modifies the input vector in place.
12///
13/// # Behavior
14/// - Removes the first `no_of_elements_to_drop` elements from the vector.
15/// - If `no_of_elements_to_drop` is `0`, the vector remains unchanged.
16/// - If `no_of_elements_to_drop` is greater than or equal to the vector’s length, the vector is cleared.
17///
18/// # Performance
19/// - Time complexity is **O(n - k)** where `k` is the number of elements dropped,
20///   since remaining elements must be shifted left.
21/// - Performs in-place mutation using `drain` without reallocating or cloning.
22/// - For frequent truncation from the start, consider using [`VecDeque`] for O(1) behavior.
23///
24/// # Examples
25///
26/// ## ✅ Drop a few elements from the start
27/// ```
28/// use pencil_box::array::drop_start::drop_start;
29///
30/// let mut data = vec![10, 20, 30, 40];
31/// drop_start(&mut data, 2);
32/// assert_eq!(data, vec![30, 40]);
33/// ```
34///
35/// ## ⛔ Drop more elements than present (clears the vector)
36/// ```
37/// let mut data = vec![1, 2, 3];
38/// drop_start(&mut data, 10);
39/// assert!(data.is_empty());
40/// ```
41///
42/// ## 🔁 Drop exactly the length (clears the vector)
43/// ```
44/// let mut data = vec![7, 8, 9];
45/// drop_start(&mut data, 3);
46/// assert!(data.is_empty());
47/// ```
48///
49/// ## ⚙️ Drop zero elements (no-op)
50/// ```
51/// let mut data = vec![1, 2, 3];
52/// drop_start(&mut data, 0);
53/// assert_eq!(data, vec![1, 2, 3]);
54/// ```
55///
56/// ## 🧵 Works with `String`s and owned types
57/// ```
58/// let mut data = vec!["a".to_string(), "b".to_string(), "c".to_string()];
59/// drop_start(&mut data, 1);
60/// assert_eq!(data, vec!["b", "c"]);
61/// ```
62///
63/// ## 📭 Empty input vector
64/// ```
65/// let mut data: Vec<i32> = vec![];
66/// drop_start(&mut data, 3); // no panic
67/// assert!(data.is_empty());
68/// ```
69
70pub fn drop_start<T>(values: &mut Vec<T>, no_of_elements_to_drop: usize) {
71    if no_of_elements_to_drop == 0 {
72        return;
73    }
74
75    if no_of_elements_to_drop >= values.len() {
76        values.clear();
77    } else {
78        values.drain(0..no_of_elements_to_drop);
79    }
80}
pencil_box/array/drop_start.rs

pencil_box/array/
drop_start.rs
