feat: Add Buffers type.

It allows to more easily manage a form of 'double buffering'
to better manage conditional alteration of a source buffer,
and to implement conversion pipelines which conditionally
transform an input over multiple steps.

Author: Byron

gix-utils/src/buffers.rs

@@ -0,0 +1,54 @@
+use crate::Buffers;
+
+/// Lifecycle
+impl Buffers {
+    /// Use this if there is an input buffer `src` which isn't owned by you, but which should be used as source when
+    /// asking for [`src_and_dest()`](WithForeignSource::src_and_dest()).
+    pub fn use_foreign_src<'a, 'src>(&'a mut self, src: &'src [u8]) -> WithForeignSource<'src, 'a> {
+        self.clear();
+        WithForeignSource {
+            ro_src: Some(src),
+            src: &mut self.src,
+            dest: &mut self.dest,
+        }
+    }
+}
+
+impl Buffers {
+    /// Clear all buffers, which should be called once processing is done.
+    pub fn clear(&mut self) {
+        self.src.clear();
+        self.dest.clear();
+    }
+
+    /// Must be called after every change (i.e. when it's known that `dest` was written.
+    pub fn swap(&mut self) {
+        std::mem::swap(&mut self.src, &mut self.dest);
+    }
+}
+
+/// A utility to do buffer-swapping with, similar to [`Buffers`], but with support for a
+/// read-only one-time buffer as source.
+pub struct WithForeignSource<'src, 'bufs> {
+    /// The original source buffer, or `None` if already altered.
+    pub ro_src: Option<&'src [u8]>,
+    /// The source buffer that will be used after the first call to `swap`.
+    pub src: &'bufs mut Vec<u8>,
+    dest: &'bufs mut Vec<u8>,
+}
+
+impl<'bufs> WithForeignSource<'_, 'bufs> {
+    /// Must be called after every change (i.e. when it's known that `dest` was written.
+    pub fn swap(&mut self) {
+        self.ro_src.take();
+        std::mem::swap(&mut self.src, &mut self.dest);
+        self.dest.clear();
+    }
+    /// Obtain `(source, destination)`, which reads from the read-only source exactly once.
+    pub fn src_and_dest(&mut self) -> (&[u8], &mut Vec<u8>) {
+        match self.ro_src {
+            Some(src) => (src, &mut self.dest),
+            None => (self.src, &mut self.dest),
+        }
+    }
+}

gix-utils/src/lib.rs

@@ -6,3 +6,20 @@
 
 ///
 pub mod backoff;
+
+///
+pub mod buffers;
+
+/// A utility to do buffer-swapping with.
+///
+/// Use `src` to read from and `dest` to write to, and after actually changing data, call [Buffers::swap()].
+/// To be able to repeat the process, this time using what was `dest` as `src`, freeing up `dest` for writing once more.
+///
+/// Note that after each [`Buffers::swap()`], `src` is the most recent version of the data, just like before each swap.
+#[derive(Default, Clone)]
+pub struct Buffers {
+    /// The source data, as basis for processing.
+    pub src: Vec<u8>,
+    /// The data produced after processing `src`.
+    pub dest: Vec<u8>,
+}

gix-utils/tests/buffers/mod.rs

@@ -0,0 +1,33 @@
+use gix_utils::Buffers;
+
+#[test]
+fn lifecycle() {
+    let mut bufs = Buffers::default();
+    let mut bufs = bufs.use_foreign_src(b"a");
+
+    assert_eq!(bufs.ro_src.unwrap(), b"a");
+
+    let (src, dest) = bufs.src_and_dest();
+
+    assert_eq!(src, b"a");
+    assert_eq!(dest.len(), 0);
+    dest.push(b'b');
+
+    bufs.swap();
+
+    assert_eq!(bufs.src, b"b");
+    assert!(bufs.ro_src.is_none());
+
+    let (src, dest) = bufs.src_and_dest();
+    assert_eq!(src, b"b");
+    assert_eq!(
+        dest.len(),
+        0,
+        "the original previously empty source buffer was swapped in "
+    );
+    dest.push(b'c');
+    bufs.swap();
+    let (src, dest) = bufs.src_and_dest();
+    assert_eq!(src, b"c");
+    assert_eq!(dest.len(), 0, "dest always starting  out empty");
+}

gix-utils/tests/utils.rs

@@ -1 +1,2 @@
 mod backoff;
+mod buffers;