devela/text/fmt/
namespace.rs

Help
1// devela::text::fmt::namespace
2//
3//! [`Fmt`] namespace.
4//
5
6use super::WriteTo;
7use crate::{FmtArguments, FmtError, FmtWrite, _core::fmt::write};
8#[cfg(feature = "alloc")]
9use crate::{String, _dep::_alloc::fmt::format};
10
11#[doc = crate::TAG_NAMESPACE!()]
12/// A string formatting namespace.
13///
14/// See also the [`std::fmt`] module.
15pub struct Fmt;
16
17///
18impl Fmt {
19    /// Takes an [`FmtArguments`] struct and returns the resulting formatted string.
20    ///
21    /// The `FmtArguments` instance can be created with the [`format_args!`] macro.
22    ///
23    /// See `alloc::fmt::`[`format`][fn@format].
24    ///
25    /// [`format_args!`]: crate::format_args
26    #[must_use]
27    #[cfg(feature = "alloc")]
28    #[cfg_attr(feature = "nightly_doc", doc(cfg(feature = "alloc")))]
29    pub fn format(args: FmtArguments<'_>) -> String {
30        format(args)
31    }
32
33    /// Writes formatted output into the given byte buffer.
34    ///
35    /// Returns:
36    /// - `Ok(&str)` if all the formatted data fits into `buf`.
37    /// - `Err(&str)` containing the valid partial result if truncation occurred.
38    ///
39    /// # Example
40    /// ```
41    /// # use devela::Fmt;
42    /// let mut buf = [0u8; 32]; // Big enough to fit everything
43    /// let s = Fmt::format_buf(&mut buf, format_args!["Test: {} {}", "foo", 42]);
44    /// assert_eq!(Ok("Test: foo 42"), s);
45    ///
46    /// let mut buf = [0u8; 9]; // Can't fit everything
47    /// let s = Fmt::format_buf(&mut buf, format_args!["Test: {} {}", "foo", 42]);
48    /// assert_eq!(Err("Test: foo"), s);
49    /// ```
50    pub fn format_buf<'a>(buf: &'a mut [u8], args: FmtArguments) -> Result<&'a str, &'a str> {
51        let mut w = WriteTo::new(buf);
52        let _ = Fmt::write(&mut w, args);
53        if w.truncated {
54            Err(w.as_str())
55        } else {
56            Ok(w.as_str())
57        }
58    }
59
60    /// Takes an output stream and an `FmtArguments` struct
61    /// that can be precompiled with the [`format_args!`] macro.
62    ///
63    /// The arguments will be formatted according to the specified format string
64    /// into the output stream provided.
65    ///
66    /// See `core::fmt::`[`write`][fn@write].
67    ///
68    /// [`format_args!`]: crate::format_args
69    pub fn write(output: &mut dyn FmtWrite, args: FmtArguments<'_>) -> Result<(), FmtError> {
70        write(output, args)
71    }
72
73    // /// Creates a type whose `fmt::Debug` and `fmt::Display` impls
74    // /// are provided with the function `f`.
75    // // WAIT: [debug_closure_helpers](https://github.com/rust-lang/rust/issues/117729)
76    // pub fn from_fn<F>(f: F) -> FromFn<F>
77    // where
78    //     F: Fn(&mut Formatter<'_>) -> Result<(), Error>,
79    // {
80    //     crate::_core::fmt::from_fn(f)
81    // }
82}
devela/text/fmt/namespace.rs

devela/text/fmt/
namespace.rs
