one-indexed-vec 0.2.0

A one-based (1-indexed) wrapper around Vec<T>: element at position N is accessed via vec[N].
Documentation
//! Capacity management.

use crate::Vec1;

impl<T> Vec1<T> {
    /// Shrinks capacity if `cap > factor * len`.
    ///
    /// ```rust
    /// use one_indexed_vec::{vec1, Vec1};
    /// let mut v = Vec1::with_capacity(1000);
    /// v.extend(vec1![1, 2, 3, 4, 5].iter().copied());
    /// v.shrink_to_fit_if(4);
    /// assert!(v.capacity() < 20);
    /// ```
    #[inline]
    pub fn shrink_to_fit_if(&mut self, factor: usize) {
        if factor == 0 {
            self.shrink_to_fit();
            return;
        }
        let len = self.len();
        let cap = self.capacity();
        if cap > len * factor {
            self.shrink_to_fit();
        }
    }

    /// Shrinks capacity if `cap - len > threshold`.
    #[inline]
    pub fn shrink_to_fit_if_excess(&mut self, threshold: usize) {
        let len = self.len();
        let cap = self.capacity();
        if cap > len && cap - len > threshold {
            self.shrink_to_fit();
        }
    }

    /// Ensures capacity ≥ `min_capacity`; returns the new capacity.
    #[inline]
    pub fn ensure_capacity(&mut self, min_capacity: usize) -> usize {
        if self.capacity() < min_capacity {
            self.reserve(min_capacity - self.capacity());
        }
        self.capacity()
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::vec1;

    #[test]
    fn shrink_to_fit_if_basic() {
        let mut v = Vec1::with_capacity(1000);
        v.extend(vec1![1, 2, 3, 4, 5].iter().copied());
        v.shrink_to_fit_if(4);
        assert!(v.capacity() < 20);
    }

    #[test]
    fn shrink_to_fit_if_no_shrink() {
        let mut v = Vec1::with_capacity(100);
        v.extend(vec1![1, 2, 3, 4, 5, 6, 7, 8, 9, 10].iter().copied());
        v.shrink_to_fit_if(20);
        assert!(v.capacity() >= 100);
    }

    #[test]
    fn shrink_to_fit_if_excess() {
        let mut v = Vec1::with_capacity(1000);
        v.extend(vec1![1, 2, 3].iter().copied());
        v.shrink_to_fit_if_excess(10);
        assert!(v.capacity() < 100);
    }

    #[test]
    fn ensure_capacity_grows() {
        let mut v = Vec1::new();
        for i in 1..=3 {
            v.push(i);
        }
        let old = v.capacity();
        let new = v.ensure_capacity(old + 50);
        assert!(new > old);
    }
}