add format macro implementation

Author: ede1998

src/lib.rs

@@ -101,7 +101,7 @@ mod histbuf;
 mod indexmap;
 mod indexset;
 mod linear_map;
-mod string;
+pub mod string;
 mod vec;
 
 #[cfg(feature = "serde")]

src/string.rs

@@ -1,4 +1,6 @@
-use core::{cmp::Ordering, fmt, fmt::Write, hash, iter, ops, str};
+//! A fixed capacity [`String`](https://doc.rust-lang.org/std/string/struct.String.html)
+
+use core::{cmp::Ordering, fmt, fmt::{Arguments, Write}, hash, iter, ops, str};
 
 use crate::Vec;
 
@@ -290,7 +292,7 @@ impl<const N: usize> Default for String<N> {
 impl<'a, const N: usize> From<&'a str> for String<N> {
     fn from(s: &'a str) -> Self {
         let mut new = String::new();
-        new.push_str(s).unwrap();
+        new.push_str(s).expect("capacity exceeded");
         new
     }
 }
@@ -474,6 +476,53 @@ impl<const N: usize> Ord for String<N> {
     }
 }
 
+/// Equivalent to [`format`](https://doc.rust-lang.org/std/fmt/fn.format.html).
+///
+/// Please note that using [`format!`] might be preferable.
+///
+/// [`format!`]: crate::format!
+pub fn format<const N: usize>(args: Arguments<'_>) -> String<N> {
+    fn format_inner<const N: usize>(args: Arguments<'_>) -> String<N> {
+        let mut output = String::new();
+        output
+            .write_fmt(args)
+            // cannot differentiate between these error cases because fmt::Error is empty
+            .expect("capacity exceeded or a formatting trait implementation returned an error");
+        output
+    }
+
+    args.as_str()
+        .map_or_else(|| format_inner(args), String::from)
+}
+
+/// Macro that creates a fixed capacity [`String`]. Equivalent to [`format!`](https://doc.rust-lang.org/std/macro.format.html).
+///
+/// The first argument is the capacity of the `String`. The following arguments work in the same way as the regular macro.
+///
+/// # Panics
+///
+/// `format!` panics if the formatted `String` would exceeded its capacity.
+/// `format!` also panics if a formatting trait implementation returns an error (same as the regular macro).
+///
+/// # Examples
+///
+/// ```
+/// use heapless::format;
+///
+/// format!(4, "test");
+/// format!(15, "hello {}", "world!");
+/// format!(20, "x = {}, y = {y}", 10, y = 30);
+/// let (x, y) = (1, 2);
+/// format!(12, "{x} + {y} = 3");
+/// ```
+#[macro_export]
+macro_rules! format {
+    ($max:literal, $($arg:tt)*) => {{
+        let res = $crate::string::format::<$max>(core::format_args!($($arg)*));
+        res
+    }}
+}
+
 macro_rules! impl_from_num {
     ($num:ty, $size:expr) => {
         impl<const N: usize> From<$num> for String<N> {
@@ -708,4 +757,25 @@ mod tests {
         assert_eq!(0, s.len());
         assert_eq!(8, s.capacity());
     }
+
+    #[test]
+    fn format() {
+        let number = 5;
+        let float = 3.12;
+        let formatted = format!(15, "{:0>3} plus {float}", number);
+        assert_eq!(formatted, "005 plus 3.12")
+    }
+
+    #[test]
+    #[should_panic]
+    fn format_overflow() {
+        let i = 1234567;
+        format!(4, "13{}", i);
+    }
+
+    #[test]
+    #[should_panic]
+    fn format_plain_string_overflow() {
+        format!(2, "123");
+    }
 }