Optimised extend

Cargo.toml

@@ -18,10 +18,12 @@ criterion = "0.4.0"
 compiletest_rs = "0.10.0"
 
 [features]
-default = ["alloc"]
+default = ["alloc", "batched_extend"]
 # disable the alloc based ringbuffer, to make RingBuffers work in no_alloc environments
 alloc = []
 
+batched_extend = []
+
 [[bench]]
 name = "bench"
 harness = false

benches/bench.rs

@@ -1,5 +1,6 @@
-#![no_coverage]
-use criterion::{black_box, criterion_group, criterion_main, Bencher, Criterion};
+#![cfg(not(tarpaulin_include))]
+
+use criterion::{black_box, criterion_group, criterion_main, BatchSize, Bencher, Criterion};
 use ringbuffer::{AllocRingBuffer, ConstGenericRingBuffer, RingBuffer};
 
 fn benchmark_push<T: RingBuffer<i32>, F: Fn() -> T>(b: &mut Bencher, new: F) {
@@ -180,6 +181,68 @@ fn criterion_benchmark(c: &mut Criterion) {
         8192,
         8195
     ];
+
+    c.bench_function("extend too many", extend_too_many);
+    c.bench_function("extend many too many", extend_many_too_many);
+    c.bench_function("extend exact cap", extend_exact_cap);
+    c.bench_function("extend too few", extend_too_few);
+    c.bench_function("extend after one", extend_after_one);
+}
+
+fn extend_many_too_many(b: &mut Bencher) {
+    let rb = ConstGenericRingBuffer::new::<8192>();
+    let input = (0..16384).collect::<Vec<_>>();
+
+    b.iter_batched(
+        &|| rb.clone(),
+        |mut r| black_box(r.extend(black_box(input.as_slice()))),
+        BatchSize::SmallInput,
+    );
+}
+
+fn extend_too_many(b: &mut Bencher) {
+    let rb = ConstGenericRingBuffer::new::<8192>();
+    let input = (0..10000).collect::<Vec<_>>();
+
+    b.iter_batched(
+        &|| rb.clone(),
+        |mut r| black_box(r.extend(black_box(input.as_slice()))),
+        BatchSize::SmallInput,
+    );
+}
+
+fn extend_exact_cap(b: &mut Bencher) {
+    let rb = ConstGenericRingBuffer::new::<8192>();
+    let input = (0..8192).collect::<Vec<_>>();
+
+    b.iter_batched(
+        &|| rb.clone(),
+        |mut r| black_box(r.extend(black_box(input.as_slice()))),
+        BatchSize::SmallInput,
+    );
+}
+
+fn extend_too_few(b: &mut Bencher) {
+    let rb = ConstGenericRingBuffer::new::<8192>();
+    let input = (0..4096).collect::<Vec<_>>();
+
+    b.iter_batched(
+        &|| rb.clone(),
+        |mut r| black_box(r.extend(black_box(input.as_slice()))),
+        BatchSize::LargeInput,
+    );
+}
+
+fn extend_after_one(b: &mut Bencher) {
+    let mut rb = ConstGenericRingBuffer::new::<8192>();
+    rb.push(&0);
+    let input = (0..4096).collect::<Vec<_>>();
+
+    b.iter_batched(
+        &|| rb.clone(),
+        |mut r| black_box(r.extend(black_box(input.as_slice()))),
+        BatchSize::LargeInput,
+    );
 }
 
 criterion_group!(benches, criterion_benchmark);

src/ringbuffer_trait.rs

@@ -2,6 +2,7 @@ use core::ops::{Index, IndexMut};
 
 #[cfg(feature = "alloc")]
 extern crate alloc;
+
 #[cfg(feature = "alloc")]
 use alloc::vec::Vec;
 
@@ -83,6 +84,41 @@ pub unsafe trait RingBuffer<T>:
         self.push(value);
     }
 
+    /// alias for [`extend`](RingBuffer::extend).
+    #[inline]
+    fn enqueue_many<I: IntoIterator<Item = T>>(&mut self, items: I) {
+        self.extend(items);
+    }
+
+    /// Clones and appends all elements in a slice to the `Vec`.
+    ///
+    /// Iterates over the slice `other`, clones each element, and then appends
+    /// it to this `RingBuffer`. The `other` slice is traversed in-order.
+    ///
+    /// Depending on the `RingBuffer` implementation, may be faster than inserting items in a loop.
+    /// `ConstGenericRingBuffer` is especially optimised in this regard.
+    /// See also: [`ConstGenericRingBuffer::custom_extend_batched`](crate::with_const_generics::ConstGenericRingBuffer::custom_extend_batched)
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use ringbuffer::{ConstGenericRingBuffer, RingBuffer};
+    ///
+    /// let mut rb = ConstGenericRingBuffer::<_, 6>::new();
+    /// rb.push(1);
+    ///
+    /// rb.extend_from_slice(&[2, 3, 4]);
+    /// assert_eq!(rb.to_vec(), vec![1, 2, 3, 4]);
+    /// ```
+    ///
+    /// [`extend`]: RingBuffer::extend
+    fn extend_from_slice(&mut self, other: &[T])
+    where
+        T: Clone,
+    {
+        self.extend(other.iter().cloned());
+    }
+
     /// dequeues the top item off the ringbuffer, and moves this item out.
     fn dequeue(&mut self) -> Option<T>;
 
@@ -119,6 +155,24 @@ pub unsafe trait RingBuffer<T>:
         RingBufferDrainingIterator::new(self)
     }
 
+    /// Moves all the elements of `other` into `self`, leaving `other` empty.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use ringbuffer::{ConstGenericRingBuffer, RingBuffer};
+    ///
+    /// let mut vec = ConstGenericRingBuffer::<_, 6>::from(vec![1, 2, 3]);
+    /// let mut vec2 = ConstGenericRingBuffer::<_, 6>::from(vec![4, 5, 6]);
+    ///
+    /// vec.append(&mut vec2);
+    /// assert_eq!(vec.to_vec(), &[1, 2, 3, 4, 5, 6]);
+    /// assert_eq!(vec2.to_vec(), &[]);
+    /// ```
+    fn append(&mut self, other: &mut Self) {
+        self.extend(other.drain());
+    }
+
     /// Sets every element in the ringbuffer to the value returned by f.
     fn fill_with<F: FnMut() -> T>(&mut self, f: F);