orx_concurrent_iter/
concurrent_drainable.rs

1use crate::ConcurrentIter;
2use core::ops::RangeBounds;
3
4/// A type which can create a concurrent draining iterator over any of its sub-slices.
5///
6/// * Created draining iterator yields all elements of the slice defined by the `range`,
7/// * Further, the slice is removed from the original collection.
8///
9/// If the iterator is dropped before being fully consumed, it drops the remaining removed elements.
10///
11/// If the complete range is provided (`..` or `0..self.len()`), self will remain empty.
12///
13/// # Examples
14///
15/// ```
16/// use orx_concurrent_iter::*;
17///
18/// let mut v = vec![1, 2, 3];
19/// let u: Vec<_> = v.con_drain(1..).item_puller().collect();
20///
21/// assert_eq!(v, &[1]);
22/// assert_eq!(u, &[2, 3]);
23/// ```
24pub trait ConcurrentDrainableOverSlice {
25    /// Type of draining iterator elements.
26    type Item;
27
28    /// Type of the concurrent draining iterator created by `con_drain` method.
29    type DrainingIter<'a>: ConcurrentIter<Item = Self::Item>
30    where
31        Self: 'a;
32
33    /// Creates a concurrent draining iterators such that:
34    ///
35    /// * the iterator yields all elements of the slice defined by the `range`,
36    /// * this slice will be removed from the original collection (`self`).
37    ///
38    /// If the iterator is dropped before being fully consumed, it drops the remaining removed elements.
39    ///
40    /// If the complete range is provided (`..` or `0..self.len()`), self will remain empty.
41    ///
42    /// # Panics:
43    ///
44    /// * if the starting point of the `range` is greater than the ending point; or
45    /// * if the ending point of the `range` is greater than `vec.len()`.
46    ///
47    /// # Leaking
48    ///
49    /// If the returned iterator goes out of scope without being dropped (due to mem::forget, for example),
50    /// `self` may have lost and leaked elements arbitrarily, including elements outside the range.
51    ///
52    /// # Examples
53    ///
54    /// ```
55    /// use orx_concurrent_iter::*;
56    ///
57    /// let mut v = vec![1, 2, 3];
58    /// let u: Vec<_> = v.con_drain(1..).item_puller().collect();
59    ///
60    /// assert_eq!(v, &[1]);
61    /// assert_eq!(u, &[2, 3]);
62    /// ```
63    fn con_drain<R>(&mut self, range: R) -> Self::DrainingIter<'_>
64    where
65        R: RangeBounds<usize>;
66}
orx_concurrent_iter/concurrent_drainable.rs

orx_concurrent_iter/
concurrent_drainable.rs
