Replace HistoryBuf::write with push

HistoryBuf already uses extend in method names for ingesting multiple
items at once and other heapless containers use push for methods
ingesting a single item. Let's be more consistent with this naming
scheme by switching from write to push here as well.

Author: sirhcel

CHANGELOG.md

@@ -15,6 +15,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - Switch from `serde` to `serde_core` for enabling faster compilations.
 - Removed `impl Deref` for `HistoryBuf` to make accessing the raw backing array explicit (use `as_slice`).
 - Replace `HistoryBuf::as_slice` with `HistoryBuf::as_unordered_slice` to clarify ordering.
+- Replace `HistoryBuf::write` with `HistoryBuf::push` for a more consistent naming scheme.
 
 ## [v0.9.1] - 2025-08-19
 

src/history_buf.rs

@@ -1,6 +1,6 @@
 //! 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
+//! This buffer keeps a fixed number of elements.  On push, 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.
 //!
@@ -14,8 +14,8 @@
 //! // Starts with no data
 //! assert_eq!(buf.recent(), None);
 //!
-//! buf.write(3);
-//! buf.write(5);
+//! buf.push(3);
+//! buf.push(5);
 //! buf.extend(&[4, 4]);
 //!
 //! // The most recent written element is a four.
@@ -157,7 +157,7 @@ pub struct HistoryBufInner<T, S: HistoryBufStorage<T> + ?Sized> {
 
 /// 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
+/// This buffer keeps a fixed number of elements.  On push, 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.
 ///
@@ -171,8 +171,8 @@ pub struct HistoryBufInner<T, S: HistoryBufStorage<T> + ?Sized> {
 /// // Starts with no data
 /// assert_eq!(buf.recent(), None);
 ///
-/// buf.write(3);
-/// buf.write(5);
+/// buf.push(3);
+/// buf.push(5);
 /// buf.extend(&[4, 4]);
 ///
 /// // The most recent written element is a four.
@@ -204,8 +204,8 @@ pub type HistoryBuf<T, const N: usize> = HistoryBufInner<T, OwnedHistoryBufStora
 /// // Starts with no data
 /// assert_eq!(buf.recent(), None);
 ///
-/// buf.write(3);
-/// buf.write(5);
+/// buf.push(3);
+/// buf.push(5);
 /// buf.extend(&[4, 4]);
 ///
 /// // The most recent written element is a four.
@@ -369,7 +369,13 @@ impl<T, S: HistoryBufStorage<T> + ?Sized> HistoryBufInner<T, S> {
     }
 
     /// Writes an element to the buffer, overwriting the oldest value.
+    #[deprecated(note = "Superseeded by push for harmonizing naming with other containers.")]
     pub fn write(&mut self, t: T) {
+        self.push(t);
+    }
+
+    /// Pushes an element to the buffer, overwriting the oldest value.
+    pub fn push(&mut self, t: T) {
         if self.filled {
             // Drop the old before we overwrite it.
             unsafe { ptr::drop_in_place(self.data.borrow_mut()[self.write_at].as_mut_ptr()) }
@@ -392,7 +398,7 @@ impl<T, S: HistoryBufStorage<T> + ?Sized> HistoryBufInner<T, S> {
         T: Clone,
     {
         for item in other {
-            self.write(item.clone());
+            self.push(item.clone());
         }
     }
 
@@ -404,8 +410,8 @@ impl<T, S: HistoryBufStorage<T> + ?Sized> HistoryBufInner<T, S> {
     /// use heapless::HistoryBuf;
     ///
     /// let mut x: HistoryBuf<u8, 16> = HistoryBuf::new();
-    /// x.write(4);
-    /// x.write(10);
+    /// x.push(4);
+    /// x.push(10);
     /// assert_eq!(x.recent(), Some(&10));
     /// ```
     pub fn recent(&self) -> Option<&T> {
@@ -421,8 +427,8 @@ impl<T, S: HistoryBufStorage<T> + ?Sized> HistoryBufInner<T, S> {
     /// use heapless::HistoryBuf;
     ///
     /// let mut x: HistoryBuf<u8, 16> = HistoryBuf::new();
-    /// x.write(4);
-    /// x.write(10);
+    /// x.push(4);
+    /// x.push(10);
     /// assert_eq!(x.recent_index(), Some(1));
     /// ```
     pub fn recent_index(&self) -> Option<usize> {
@@ -445,8 +451,8 @@ impl<T, S: HistoryBufStorage<T> + ?Sized> HistoryBufInner<T, S> {
     /// use heapless::HistoryBuf;
     ///
     /// let mut x: HistoryBuf<u8, 16> = HistoryBuf::new();
-    /// x.write(4);
-    /// x.write(10);
+    /// x.push(4);
+    /// x.push(10);
     /// assert_eq!(x.oldest(), Some(&4));
     /// ```
     pub fn oldest(&self) -> Option<&T> {
@@ -462,8 +468,8 @@ impl<T, S: HistoryBufStorage<T> + ?Sized> HistoryBufInner<T, S> {
     /// use heapless::HistoryBuf;
     ///
     /// let mut x: HistoryBuf<u8, 16> = HistoryBuf::new();
-    /// x.write(4);
-    /// x.write(10);
+    /// x.push(4);
+    /// x.push(10);
     /// assert_eq!(x.oldest_index(), Some(0));
     /// ```
     pub fn oldest_index(&self) -> Option<usize> {
@@ -542,7 +548,7 @@ impl<T, S: HistoryBufStorage<T> + ?Sized> Extend<T> for HistoryBufInner<T, S> {
         I: IntoIterator<Item = T>,
     {
         for item in iter.into_iter() {
-            self.write(item);
+            self.push(item);
         }
     }
 }
@@ -672,16 +678,41 @@ mod tests {
         assert!(!x.is_full());
     }
 
+    #[allow(deprecated)]
     #[test]
     fn write() {
+        let mut write: HistoryBuf<u8, 4> = HistoryBuf::new();
+        let mut push: HistoryBuf<u8, 4> = HistoryBuf::new();
+
+        write.write(1);
+        write.write(4);
+        push.push(1);
+        push.push(4);
+        assert_eq!(write, push);
+
+        write.push(5);
+        write.push(6);
+        write.push(10);
+        push.push(5);
+        push.push(6);
+        push.push(10);
+        assert_eq!(write, push);
+
+        write.extend([11, 12].iter());
+        push.extend([11, 12].iter());
+        assert_eq!(write, push);
+    }
+
+    #[test]
+    fn push() {
         let mut x: HistoryBuf<u8, 4> = HistoryBuf::new();
-        x.write(1);
-        x.write(4);
+        x.push(1);
+        x.push(4);
         assert_eq!(x.as_unordered_slice(), [1, 4]);
 
-        x.write(5);
-        x.write(6);
-        x.write(10);
+        x.push(5);
+        x.push(6);
+        x.push(10);
         assert_eq!(x.as_unordered_slice(), [10, 4, 5, 6]);
 
         x.extend([11, 12].iter());
@@ -704,7 +735,7 @@ mod tests {
         let mut x: HistoryBuf<u8, 3> = HistoryBuf::new();
         for i in 0..10 {
             assert_eq!(x.as_unordered_slice(), x.clone().as_unordered_slice());
-            x.write(i);
+            x.push(i);
         }
 
         // Records number of clones locally and globally.
@@ -722,11 +753,11 @@ mod tests {
         let mut y: HistoryBuf<InstrumentedClone, 2> = HistoryBuf::new();
         let _ = y.clone();
         assert_eq!(GLOBAL.load(Ordering::Relaxed), 0);
-        y.write(InstrumentedClone(0));
+        y.push(InstrumentedClone(0));
         assert_eq!(GLOBAL.load(Ordering::Relaxed), 0);
         assert_eq!(y.clone().as_unordered_slice(), [InstrumentedClone(1)]);
         assert_eq!(GLOBAL.load(Ordering::Relaxed), 1);
-        y.write(InstrumentedClone(0));
+        y.push(InstrumentedClone(0));
         assert_eq!(GLOBAL.load(Ordering::Relaxed), 1);
         assert_eq!(
             y.clone().as_unordered_slice(),
@@ -746,14 +777,14 @@ mod tests {
         assert_eq!(x.recent_index(), None);
         assert_eq!(x.recent(), None);
 
-        x.write(1);
-        x.write(4);
+        x.push(1);
+        x.push(4);
         assert_eq!(x.recent_index(), Some(1));
         assert_eq!(x.recent(), Some(&4));
 
-        x.write(5);
-        x.write(6);
-        x.write(10);
+        x.push(5);
+        x.push(6);
+        x.push(10);
         assert_eq!(x.recent_index(), Some(0));
         assert_eq!(x.recent(), Some(&10));
     }
@@ -764,14 +795,14 @@ mod tests {
         assert_eq!(x.oldest_index(), None);
         assert_eq!(x.oldest(), None);
 
-        x.write(1);
-        x.write(4);
+        x.push(1);
+        x.push(4);
         assert_eq!(x.oldest_index(), Some(0));
         assert_eq!(x.oldest(), Some(&1));
 
-        x.write(5);
-        x.write(6);
-        x.write(10);
+        x.push(5);
+        x.push(6);
+        x.push(10);
         assert_eq!(x.oldest_index(), Some(1));
         assert_eq!(x.oldest(), Some(&4));
     }
@@ -821,7 +852,7 @@ mod tests {
         let mut buffer: HistoryBuf<u8, 6> = HistoryBuf::new();
 
         for n in 0..20 {
-            buffer.write(n);
+            buffer.push(n);
             let (head, tail) = buffer.as_slices();
             assert_eq_iter(
                 [head, tail].iter().copied().flatten(),
@@ -911,16 +942,16 @@ mod tests {
         let mut x: HistoryBuf<u8, 3> = HistoryBuf::new();
         let mut y: HistoryBuf<u8, 3> = HistoryBuf::new();
         assert_eq!(x, y);
-        x.write(1);
+        x.push(1);
         assert_ne!(x, y);
-        y.write(1);
+        y.push(1);
         assert_eq!(x, y);
         for _ in 0..4 {
-            x.write(2);
+            x.push(2);
             assert_ne!(x, y);
             for i in 0..5 {
-                x.write(i);
-                y.write(i);
+                x.push(i);
+                y.push(i);
             }
             assert_eq!(
                 x,
@@ -945,9 +976,9 @@ mod tests {
         }
 
         let mut x: HistoryBuf<DropCheck, 3> = HistoryBuf::new();
-        x.write(DropCheck {});
-        x.write(DropCheck {});
-        x.write(DropCheck {});
+        x.push(DropCheck {});
+        x.push(DropCheck {});
+        x.push(DropCheck {});
 
         assert_eq!(DROP_COUNT.load(Ordering::SeqCst), 0);
         x.clear();