add write

Author: ModProg

src/hard_coded/mod.rs

@@ -5,7 +5,7 @@ macro_rules! format_value {
     ($name:ident($out:ident, $v:ident, $Trait:ident): $($tts:tt)*) => {
         #[allow(clippy::too_many_arguments)]
         pub(crate) fn $name(
-            $out: &mut String,
+            $out: &mut impl std::fmt::Write,
             $v: impl std::fmt::$Trait,
             width: Option<usize>,
             precision: Option<usize>,
@@ -15,7 +15,6 @@ macro_rules! format_value {
             zero: bool,
         ) -> crate::Result<(), std::fmt::Error> {
             use {crate::Alignment as A, crate::Sign as S};
-            use std::fmt::Write;
 
             match (width, precision, alignment, sign, hash, zero) {
                 $($tts)*
@@ -76,7 +75,7 @@ mod upper_hex_debug;
 
 #[allow(clippy::too_many_arguments)]
 pub(crate) fn format_value(
-    out: &mut String,
+    out: &mut impl Write,
     value: &Formattable,
     width: Option<usize>,
     precision: Option<usize>,

src/lib.rs

@@ -1,6 +1,6 @@
 //! Runtime implementation of [`format!`].
 //!
-//! See [`format()`] for details.
+//! See [`format`](format()) and [`write`](write()) for details.
 //!
 //! # Features
 //! By default only [`Display`] is supported, the rest of the
@@ -24,7 +24,7 @@ use std::error::Error as StdError;
 use std::fmt::Pointer;
 #[cfg(feature = "number")]
 use std::fmt::{Binary, LowerExp, LowerHex, Octal, UpperExp, UpperHex};
-use std::fmt::{Debug, Display, Error as FmtError};
+use std::fmt::{Debug, Display, Error as FmtError, Write};
 use std::hash::Hash;
 use std::num::ParseIntError;
 
@@ -494,21 +494,23 @@ impl<'a> FormatArgument<'a> {
     }
 }
 
-/// Runtime version of [`format!`].
+/// Runtime version of [`write!`].
 ///
-/// Takes a string and a context, containing [`Formattable`] values, returns a
-/// string.
+/// Takes a mutable [`Write`] e.g `&mut String`, a format string and a context,
+/// containing [`Formattable`] values.
 ///
 /// ```
-/// use template::{format, Formattable};
+/// use template::{write, Formattable};
 ///
-/// let formatted = format(
+/// let mut buf = String::new();
+/// write(
+///     &mut buf,
 ///     "{value:+05}", // could be dynamic
 ///     &[("value", Formattable::display(&12))].into_iter().collect(),
 /// )
 /// .unwrap();
 ///
-/// assert_eq!(formatted, format!("{:+05}", 12));
+/// assert_eq!(buf, format!("{:+05}", 12));
 /// ```
 ///
 /// # Errors
@@ -518,16 +520,17 @@ impl<'a> FormatArgument<'a> {
 /// failed.
 ///
 /// For more details have a look at [`Error`] and [`FormatArgumentError`].
-pub fn format<K: Borrow<str> + Eq + Hash>(
+pub fn write<K: Borrow<str> + Eq + Hash>(
+    out: &mut impl Write,
     mut format: &str,
     context: &HashMap<K, Formattable>,
-) -> Result<String> {
+) -> Result {
     let format = &mut format;
-    let mut out = String::with_capacity(format.len());
     let idx = &mut 0;
     while !format.is_empty() {
         if format.starts_with("{{") || format.starts_with("}}") {
-            out.push_str(&format[..1]);
+            out.write_str(&format[..1])
+                .map_err(|e| Error::FmtError(e, *idx))?;
             step(2, format, idx);
             continue;
         }
@@ -548,7 +551,7 @@ pub fn format<K: Borrow<str> + Eq + Hash>(
                 .get(ident)
                 .ok_or(Error::MissingValue(ident.to_string(), start))?;
             format_value(
-                &mut out, value, width, precision, alignment, sign, hash, zero, trait_, *idx,
+                out, value, width, precision, alignment, sign, hash, zero, trait_, *idx,
             )?;
             ensure!(
                 format.starts_with('}'),
@@ -561,8 +564,41 @@ pub fn format<K: Borrow<str> + Eq + Hash>(
             .chars()
             .next()
             .expect("should contain a char if not empty");
-        out.push(next);
+        out.write_char(next).map_err(|e| Error::FmtError(e, *idx))?;
         step(next.len_utf8(), format, idx);
     }
+    Ok(())
+}
+
+/// Runtime version of [`format!`].
+///
+/// Takes a string and a context, containing [`Formattable`] values, returns a
+/// string.
+///
+/// ```
+/// use template::{format, Formattable};
+///
+/// let formatted = format(
+///     "{value:+05}", // could be dynamic
+///     &[("value", Formattable::display(&12))].into_iter().collect(),
+/// )
+/// .unwrap();
+///
+/// assert_eq!(formatted, format!("{:+05}", 12));
+/// ```
+///
+/// # Errors
+///
+/// It will return an error if the specified format string has invalid syntax,
+/// the type doesn't implement the expected trait, or the formatting it self
+/// failed.
+///
+/// For more details have a look at [`Error`] and [`FormatArgumentError`].
+pub fn format<K: Borrow<str> + Eq + Hash>(
+    format: &str,
+    context: &HashMap<K, Formattable>,
+) -> Result<String> {
+    let mut out = String::with_capacity(format.len());
+    write(&mut out, format, context)?;
     Ok(out)
 }

tests/test.rs

@@ -120,16 +120,25 @@ fn test(
     t.pass_inline(
         &converter.to_token_stream().to_string(),
         &quote! {
-            use template::{{format, Formattable}};
+            use template::{{format, Formattable, write}};
             use std::thread;
+            use std::fmt::Write;
             fn main() {
                 // This stack overflows without the thread on windows + nightly
                 thread::spawn(move ||{
                     let value = &[("ident", Formattable::#converter(&#value))].into_iter().collect();
-                    #(assert!(
-                            format(#format_args, value).unwrap() ==  format!(#format_args, ident = #value),
+                    #(
+                        assert_eq!(
+                            format(#format_args, value).unwrap(),
+                            format!(#format_args, ident = #value),
                             "{}", #format_args
-                    );)*
+                        );
+                        let mut buf_rt = String::new();
+                        write(&mut buf_rt, #format_args, value).unwrap();
+                        let mut buf_ct = String::new();
+                        write!(&mut buf_ct, #format_args, ident = #value).unwrap();
+                        assert_eq!(buf_rt, buf_ct, "{}", #format_args);
+                    )*
                 }).join().unwrap();
             }
         }