Merge branch 'master' into write

Author: korken89

CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
+## [v0.5.4] - 2020-04-06
+
+### Added
+
+- Added `StableDeref` implementation for `pool::Box` and `pool::singleton::Box`.
+
 ## [v0.5.3] - 2020-01-27
 
 ### Added
@@ -288,7 +294,9 @@ architecture.
 
 - Initial release
 
-[Unreleased]: https://github.com/japaric/heapless/compare/v0.5.2...HEAD
+[Unreleased]: https://github.com/japaric/heapless/compare/v0.5.4...HEAD
+[v0.5.4]: https://github.com/japaric/heapless/compare/v0.5.3...v0.5.4
+[v0.5.3]: https://github.com/japaric/heapless/compare/v0.5.2...v0.5.3
 [v0.5.2]: https://github.com/japaric/heapless/compare/v0.5.1...v0.5.2
 [v0.5.1]: https://github.com/japaric/heapless/compare/v0.5.0...v0.5.1
 [v0.5.0]: https://github.com/japaric/heapless/compare/v0.4.4...v0.5.0

Cargo.toml

@@ -17,11 +17,12 @@ keywords = [
 license = "MIT OR Apache-2.0"
 name = "heapless"
 repository = "https://github.com/japaric/heapless"
-version = "0.5.3"
+version = "0.5.4"
 
 [features]
 default = ["cas"]
 cas = []
+ufmt-impl = ["ufmt-write"]
 # only for tests
 __trybuild = []
 
@@ -37,3 +38,14 @@ hash32 = "0.1.0"
 version = "1"
 optional = true
 default-features = false
+
+[dependencies.stable_deref_trait]
+version = "1"
+default-features = false
+
+[dependencies.ufmt-write]
+version = "0.1"
+optional = true
+
+[dev-dependencies.ufmt]
+version = "0.1"

build.rs

@@ -11,7 +11,7 @@ fn main() -> Result<(), Box<dyn Error>> {
         println!("cargo:rustc-cfg=armv7m");
     } else if target.starts_with("thumbv7em-") {
         println!("cargo:rustc-cfg=armv7m");
-    } else if target.starts_with("armv7r-") {
+    } else if target.starts_with("armv7r-") | target.starts_with("armebv7r-") {
         println!("cargo:rustc-cfg=armv7r");
     } else if target.starts_with("thumbv8m.base") {
         println!("cargo:rustc-cfg=armv8m_base");

src/histbuf.rs

@@ -0,0 +1,256 @@
+use generic_array::{ArrayLength, GenericArray, sequence::GenericSequence};
+
+/// A "history buffer", similar to a write-only ring buffer of fixed length.
+///
+/// This buffer keeps a fixed number of elements.  On write, the oldest element
+/// is overwritten. Thus, the buffer is useful to keep a history of values with
+/// some desired depth, and for example calculate a rolling average.
+///
+/// The buffer is always fully initialized; depending on the constructor, the
+/// initial value is either the default value for the element type or a supplied
+/// initial value. This simplifies the API and is mostly irrelevant for the
+/// intended use case.
+///
+/// # Examples
+/// ```
+/// use heapless::HistoryBuffer;
+/// use heapless::consts::*;
+///
+/// // Initialize a new buffer with 8 elements, all initially zero.
+/// let mut buf = HistoryBuffer::<_, U8>::new();
+///
+/// buf.write(3);
+/// buf.write(5);
+/// buf.extend(&[4, 4]);
+///
+/// // The most recent written element is a four.
+/// assert_eq!(buf.recent(), &4);
+///
+/// // To access all elements in an unspecified order, use `as_slice()`.
+/// for el in buf.as_slice() { println!("{:?}", el); }
+///
+/// // Now we can prepare an average of all values, which comes out to 2.
+/// let avg = buf.as_slice().iter().sum::<usize>() / buf.len();
+/// assert_eq!(avg, 2);
+/// ```
+#[derive(Clone)]
+pub struct HistoryBuffer<T, N>
+where
+    N: ArrayLength<T>,
+{
+    data: GenericArray<T, N>,
+    write_at: usize,
+}
+
+
+impl<T, N> HistoryBuffer<T, N>
+where
+    N: ArrayLength<T>,
+    T: Default,
+{
+    /// Constructs a new history buffer, where every element is filled with the
+    /// default value of the type `T`.
+    ///
+    /// `HistoryBuffer` currently cannot be constructed in `const` context.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use heapless::HistoryBuffer;
+    /// use heapless::consts::*;
+    ///
+    /// // Allocate a 16-element buffer on the stack
+    /// let mut x: HistoryBuffer<u8, U16> = HistoryBuffer::new();
+    /// // All elements are zero
+    /// assert_eq!(x.as_slice(), [0; 16]);
+    /// ```
+    pub fn new() -> Self {
+        Self {
+            data: Default::default(),
+            write_at: 0,
+        }
+    }
+
+    /// Clears the buffer, replacing every element with the default value of
+    /// type `T`.
+    pub fn clear(&mut self) {
+        *self = Self::new();
+    }
+}
+
+impl<T, N> HistoryBuffer<T, N>
+where
+    N: ArrayLength<T>,
+    T: Clone,
+{
+    /// Constructs a new history buffer, where every element is the given value.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use heapless::HistoryBuffer;
+    /// use heapless::consts::*;
+    ///
+    /// // Allocate a 16-element buffer on the stack
+    /// let mut x: HistoryBuffer<u8, U16> = HistoryBuffer::new_with(4);
+    /// // All elements are four
+    /// assert_eq!(x.as_slice(), [4; 16]);
+    /// ```
+    pub fn new_with(t: T) -> Self {
+        Self {
+            data: GenericArray::generate(|_| t.clone()),
+            write_at: 0,
+        }
+    }
+
+    /// Clears the buffer, replacing every element with the given value.
+    pub fn clear_with(&mut self, t: T) {
+        *self = Self::new_with(t);
+    }
+}
+
+impl<T, N> HistoryBuffer<T, N>
+where
+    N: ArrayLength<T>,
+{
+    /// Returns the capacity of the buffer, which is the length of the
+    /// underlying backing array.
+    pub fn len(&self) -> usize {
+        self.data.len()
+    }
+
+    /// Writes an element to the buffer, overwriting the oldest value.
+    pub fn write(&mut self, t: T) {
+        self.data[self.write_at] = t;
+        self.write_at = (self.write_at + 1) % self.len();
+    }
+
+    /// Clones and writes all elements in a slice to the buffer.
+    ///
+    /// If the slice is longer than the buffer, only the last `self.len()`
+    /// elements will actually be stored.
+    pub fn extend_from_slice(&mut self, other: &[T])
+    where
+        T: Clone,
+    {
+        for item in other {
+            self.write(item.clone());
+        }
+    }
+
+    /// Returns a reference to the most recently written value.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use heapless::HistoryBuffer;
+    /// use heapless::consts::*;
+    ///
+    /// let mut x: HistoryBuffer<u8, U16> = HistoryBuffer::new();
+    /// x.write(4);
+    /// x.write(10);
+    /// assert_eq!(x.recent(), &10);
+    /// ```
+    pub fn recent(&self) -> &T {
+        &self.data[(self.write_at + self.len() - 1) % self.len()]
+    }
+
+    /// Returns the array slice backing the buffer, without keeping track
+    /// of the write position. Therefore, the element order is unspecified.
+    pub fn as_slice(&self) -> &[T] {
+        &self.data
+    }
+}
+
+impl<T, N> Extend<T> for HistoryBuffer<T, N>
+where
+    N: ArrayLength<T>,
+{
+    fn extend<I>(&mut self, iter: I)
+    where
+        I: IntoIterator<Item = T>,
+    {
+        for item in iter.into_iter() {
+            self.write(item);
+        }
+    }
+}
+
+impl<'a, T, N> Extend<&'a T> for HistoryBuffer<T, N>
+where
+    T: 'a + Clone,
+    N: ArrayLength<T>,
+{
+    fn extend<I>(&mut self, iter: I)
+    where
+        I: IntoIterator<Item = &'a T>,
+    {
+        self.extend(iter.into_iter().cloned())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::{consts::*, HistoryBuffer};
+
+    #[test]
+    fn new() {
+        let x: HistoryBuffer<u8, U4> = HistoryBuffer::new_with(1);
+        assert_eq!(x.len(), 4);
+        assert_eq!(x.as_slice(), [1; 4]);
+
+        let x: HistoryBuffer<u8, U4> = HistoryBuffer::new();
+        assert_eq!(x.as_slice(), [0; 4]);
+    }
+
+    #[test]
+    fn write() {
+        let mut x: HistoryBuffer<u8, U4> = HistoryBuffer::new();
+        x.write(1);
+        x.write(4);
+        assert_eq!(x.as_slice(), [1, 4, 0, 0]);
+
+        x.write(5);
+        x.write(6);
+        x.write(10);
+        assert_eq!(x.as_slice(), [10, 4, 5, 6]);
+
+        x.extend([11, 12].iter());
+        assert_eq!(x.as_slice(), [10, 11, 12, 6]);
+    }
+
+    #[test]
+    fn clear() {
+        let mut x: HistoryBuffer<u8, U4> = HistoryBuffer::new_with(1);
+        x.clear();
+        assert_eq!(x.as_slice(), [0; 4]);
+
+        let mut x: HistoryBuffer<u8, U4> = HistoryBuffer::new();
+        x.clear_with(1);
+        assert_eq!(x.as_slice(), [1; 4]);
+    }
+
+    #[test]
+    fn recent() {
+        let mut x: HistoryBuffer<u8, U4> = HistoryBuffer::new();
+        assert_eq!(x.recent(), &0);
+
+        x.write(1);
+        x.write(4);
+        assert_eq!(x.recent(), &4);
+
+        x.write(5);
+        x.write(6);
+        x.write(10);
+        assert_eq!(x.recent(), &10);
+    }
+
+    #[test]
+    fn as_slice() {
+        let mut x: HistoryBuffer<u8, U4> = HistoryBuffer::new();
+
+        x.extend([1, 2, 3, 4, 5].iter());
+
+        assert_eq!(x.as_slice(), [5, 2, 3, 4]);
+    }
+}

src/lib.rs

@@ -56,6 +56,14 @@
 //! - [`mpmc::Q*`](mpmc/index.html) -- multiple producer multiple consumer lock-free queue
 //! - [`spsc::Queue`](spsc/struct.Queue.html) -- single producer single consumer lock-free queue
 //!
+//! # Optional Features
+//!
+//! The `heapless` crate provides the following optional Cargo features:
+//!
+//! - `ufmt-impl`: Implement [`ufmt_write::uWrite`] for `String<N>` and `Vec<u8, N>`
+//!
+//! [`ufmt_write::uWrite`]: https://docs.rs/ufmt-write/
+//!
 //! # Minimum Supported Rust Version (MSRV)
 //!
 //! This crate is guaranteed to compile on stable Rust 1.36 and up with its default set of features.
@@ -75,13 +83,15 @@ pub use indexset::{FnvIndexSet, IndexSet};
 pub use linear_map::LinearMap;
 pub use string::String;
 pub use vec::Vec;
+pub use histbuf::HistoryBuffer;
 
 // NOTE this code was last ported from v0.4.1 of the indexmap crate
 mod indexmap;
 mod indexset;
 mod linear_map;
 mod string;
 mod vec;
+mod histbuf;
 
 #[cfg(feature = "serde")]
 mod de;
@@ -97,4 +107,7 @@ pub mod pool;
 #[cfg(has_atomics)]
 pub mod spsc;
 
+#[cfg(feature = "ufmt-impl")]
+mod ufmt;
+
 mod sealed;

src/pool/mod.rs

@@ -375,6 +375,8 @@ unsafe impl<T, S> Send for Box<T, S> where T: Send {}
 
 unsafe impl<T, S> Sync for Box<T, S> where T: Sync {}
 
+unsafe impl<T> stable_deref_trait::StableDeref for Box<T> {}
+
 impl<A> AsSlice for Box<A>
 where
     A: AsSlice,

src/pool/singleton.rs

@@ -160,6 +160,8 @@ where
     }
 }
 
+unsafe impl<P: Pool> stable_deref_trait::StableDeref for Box<P> {}
+
 impl<P> fmt::Debug for Box<P>
 where
     P: Pool,