tfmt 0.4.0

#![doc = include_str!("../README.md")]
#![cfg_attr(not(feature = "std"), no_std)]

mod helpers;
mod impls;
mod utils;
use core::{slice::from_raw_parts, str::from_utf8_unchecked};

/// Derive macro
pub mod derive {
    pub use tfmt_macros::uDebug;
}

#[doc(hidden)]
pub use utils::{uDisplayFloat, uDisplayHex, UnstableDoAsFormatter};

/// This trait is used to write a message into a stream.
#[allow(non_camel_case_types)]
pub trait uWrite {
    /// The error associated to this writer
    type Error;

    /// Writes a string slice into this writer, returning whether the write succeeded
    ///
    /// This method can only succeed if the entire string slice was successfully written, and this
    /// method will not return until all data has been written or an error occurs.
    fn write_str(&mut self, s: &str) -> Result<(), Self::Error>;

    /// Writes a [`char`] into this writer, returning whether the write succeeded
    ///
    /// A single [`char`] may be encoded as more than one byte. This method can only succeed if the
    /// entire byte sequence was successfully written, and this method will not return until all
    /// data has been written or an error occurs.
    fn write_char(&mut self, c: char) -> Result<(), Self::Error> {
        let mut buf: [u8; 4] = [0; 4];
        self.write_str(c.encode_utf8(&mut buf))
    }
}

/// Creates a `String` using interpolation of runtime expressions.
///
/// The first argument specifies the length of the string generated by the macro.
/// The second argument `uformat!` is a format string. This must be a string
/// literal. The power of the formatting string is in the `{}`s contained.
/// Additional parameters passed to `format!` replace the `{}`s within the
/// formatting string in the order given unless positional parameters
/// are used. The macro returns [Result][core::result::Result].
///
/// See the formatting syntax documentation for details.
///
/// **Note**: In the no_std environment, [heapless::String] is used for string
/// representation. The length specification is used to scale this string. With
/// the `std` feature set, this is not actually necessary. However, the parameter
/// is also required here to ensure compatibility of the code.
///
/// ```
/// use tfmt::uformat;
///
/// assert_eq!(
///     uformat!(100, "The answer to {} is {}", "everything", 42).unwrap().as_str(),
///     "The answer to everything is 42"
/// );
/// ```
#[macro_export]
#[cfg(not(feature = "std"))]
macro_rules! uformat {
    ($cap:expr, $($tt:tt)*) => {{
        let mut s = heapless::String::<$cap>::new();
        #[allow(unreachable_code)]
        match tfmt::uwrite!(&mut s, $($tt)*) {
            Ok(_) => Ok(s),
            Err(e) => Err(e),
        }
    }};
}

/// Documentation
#[macro_export]
#[cfg(feature = "std")]
macro_rules! uformat {
    ($cap:expr, $($tt:tt)*) => {{
        let mut s = String::new();
        #[allow(unreachable_code)]
        match tfmt::uwrite!(&mut s, $($tt)*) {
            Ok(_) => Ok(s),
            Err(e) => Err(e),
        }
    }};
}

#[doc(hidden)]
#[macro_export]
macro_rules! udisplay_as_udebug {
    ($type: ty) => {
        impl uDebug for $type {
            #[inline(always)]
            fn fmt<W>(&self, f: &mut Formatter<'_, W>) -> Result<(), W::Error>
            where
                W: uWrite + ?Sized,
            {
                <$type as uDisplay>::fmt(self, f)
            }
        }
    };
}

/// Write formatted data into a buffer
///
/// This macro accepts a format string, a list of arguments, and a 'writer'. Arguments will be
/// formatted according to the specified format string and the result will be passed to the writer.
/// The writer must have type `[&mut] impl uWrite` or `[&mut] ufmt::Formatter<'_, impl uWrite>`. The
/// macro returns the associated `Error` type of the `uWrite`-r.
///
/// This is a procedural macro, which means that it is executed at compile time and the content is
/// interpreted then. The result is efficient executable code in the target system that does not
/// perform any interpretation or dynamic dispatch.
///
/// ```
/// use tfmt::uwrite;
///
/// let mut s = String::new();
/// uwrite!(&mut s, "the {} is {}", "number", 42).unwrap();
/// assert!(s.as_str() == "the number is 42");
/// ```
///
/// The syntax is similar to [`core::write!`]. The following patterns are supported:
///
/// | Pattern | Trait to be implemented | Remarks                                      |
/// |---------|-------------------------|----------------------------------------------|
/// | {}      | [uDisplay]              |                                              |
/// | {:8}    | [uDisplayPadded]        | pad_char: ' ', padding: Usual(8)             |
/// | {:08}   | [uDisplayPadded]        | pad_char: '0', padding: Usual(8)             |
/// | {:<8}   | [uDisplayPadded]        | pad_char: ' ', padding: LeftAligned(8)       |
/// | {:>8}   | [uDisplayPadded]        | pad_char: ' ', padding: RightAligned(8)      |
/// | {:^08}  | [uDisplayPadded]        | pad_char: '0', padding: CenterAligned(8)     |
/// | {:8a2}  | [uDisplayFormatted]     | padding: Usual(8), cmd: 'a', behind: 2       |
/// | {:08a2} | [uDisplayFormatted]     | pad_char: '0', for the rest see above        |
/// | {:#8a2} | [uDisplayFormatted]     | prefix: true, for the rest see above         |
/// | {:.2}   | internal float          | padding: Usual(0), behind: 2                 |
/// | {:8.2}  | internal float          | padding: Usual(8), behind: 2                 |
/// | {:08.2} | internal float          | pad_char: '0', for the rest see above        |
/// | {:x}    | internal hex            | padding: Usual(0)                            |
/// | {:8x}   | internal hex            | pad_char: ' ', padding: Usual(8)             |
/// | {:08x}  | internal hex            | pad_char: '0', padding: Usual(8)             |
/// | {:08x}  | internal hex            | pad_char: '0', padding: Usual(8)             |
/// | {:#x}   | internal hex            | prefix: true                                 |
/// | {{, }}  | -                       | escape braces                                |
///
/// For more details see:
/// - integer formatting: `tests/int.rs`
/// - float formatting: `tests/float.rs`
/// - string and char formatting: `tests/core.rs`
/// - [uDisplayFormatted] example: `examples/coords`
///
#[cfg(not(doctest))] // only ok with features "std"
pub use tfmt_macros::uwrite;

/// Write formatted data into a buffer, with a newline appended
///
/// See [`uwrite!`](macro.uwrite.html) for more details
pub use tfmt_macros::uwriteln;

/// Configuration for formatting
#[allow(non_camel_case_types)]
pub struct Formatter<'w, W>
where
    W: uWrite + ?Sized,
{
    writer: &'w mut W,
    indentation: usize,
    pretty: bool,
}

impl<'w, W> Formatter<'w, W>
where
    W: uWrite + ?Sized,
{
    /// Creates a formatter from the given writer
    pub fn new(writer: &'w mut W) -> Self {
        Self {
            writer,
            indentation: 0,
            pretty: false,
        }
    }

    /// Writes a character to the underlying buffer
    pub fn write_char(&mut self, c: char) -> Result<(), W::Error> {
        let mut buf = [0_u8; 4];
        let s = c.encode_utf8(&mut buf);
        self.writer.write_str(s)
    }

    /// Writes a string slice to the underlying buffer
    pub fn write_str(&mut self, s: &str) -> Result<(), W::Error> {
        self.writer.write_str(s)
    }

    /// Execute the closure with pretty-printing enabled
    pub fn pretty(
        &mut self,
        f: impl FnOnce(&mut Self) -> Result<(), W::Error>,
    ) -> Result<(), W::Error> {
        let pretty = self.pretty;
        self.pretty = true;
        f(self)?;
        self.pretty = pretty;
        Ok(())
    }

    /// Write whitespace according to the current `self.indentation`
    fn indent(&mut self) -> Result<(), W::Error> {
        for _ in 0..self.indentation {
            self.write_str("    ")?;
        }

        Ok(())
    }

    /// Writes a string slice to the underlying buffer and fills it with the pad_char according to
    /// the padding specifications. Here, `Padding::Usual` is treated in the same way as
    /// `Padding::RightAligned`.
    pub fn write_padded(
        &mut self,
        s: &str,
        pad_char: char,
        padding: Padding,
    ) -> Result<(), W::Error> {
        // Converting a char to &str is expensive, so we only do it once
        let mut buf = [0_u8; 4];
        let pad_c = pad_char.encode_utf8(&mut buf);
        match padding {
            Padding::LeftAligned(pad_length) => {
                self.writer.write_str(s)?;
                for _ in s.len()..pad_length {
                    self.writer.write_str(pad_c)?;
                }
                Ok(())
            }
            Padding::Usual(pad_length) | Padding::RightAligned(pad_length) => {
                for _ in s.len()..pad_length {
                    self.writer.write_str(pad_c)?;
                }
                self.writer.write_str(s)
            }
            Padding::CenterAligned(pad_length) => {
                let padding = pad_length - s.len();
                let half = padding / 2;
                for _ in 0..half {
                    self.writer.write_str(pad_c)?;
                }
                self.writer.write_str(s)?;
                for _ in half..padding {
                    self.writer.write_str(pad_c)?;
                }
                Ok(())
            }
        }
    }
}

/// Implement this trait if `{}` is to be used with the write macro.
///
/// See [uwrite] for details
#[allow(non_camel_case_types)]
pub trait uDisplay {
    /// Formats the value using the given formatter
    fn fmt<W>(&self, _: &mut Formatter<'_, W>) -> Result<(), W::Error>
    where
        W: uWrite + ?Sized;
}

/// Just like `core::fmt::Debug`
#[allow(non_camel_case_types)]
pub trait uDebug {
    /// Formats the value using the given formatter
    fn fmt<W>(&self, _: &mut Formatter<'_, W>) -> Result<(), W::Error>
    where
        W: uWrite + ?Sized;
}

/// This enum determines how the display is to be filled, see [uwrite] for more details.
#[derive(PartialEq, Clone, Copy)]
pub enum Padding {
    /// Usual padding left or right depending on type
    Usual(usize),
    /// Padding left aligned
    LeftAligned(usize),
    /// Padding right aligned
    RightAligned(usize),
    /// Padding on left and right side
    CenterAligned(usize),
}

/// Creating padded output string
///
/// See [uwrite] for details.
/// 
/// ```
/// use tfmt::{uformat, uDisplayPadded, Convert};
/// 
/// struct Time {
///     hour: u8,
///     min: u8,
///     sec: u8,
/// }
/// 
/// impl uDisplayPadded for Time {
///     fn fmt_padded<W>(
///             &self,
///             fmt: &mut tfmt::Formatter<'_, W>,
///             padding: tfmt::Padding,
///             pad_char: char,
///         ) -> Result<(), W::Error>
///         where
///             W: tfmt::uWrite + ?Sized 
///     {
///         let mut conv = Convert::<6>::new(b'0');
///         conv.u32_pad(self.sec as u32, 2).unwrap();
///         conv.u32_pad(self.min as u32, 2).unwrap();
///         conv.u32_pad(self.hour as u32, 2).unwrap();
///         fmt.write_padded(conv.as_str(), pad_char, padding)
///     }
/// }
/// 
/// let time = Time { hour: 3, min: 17, sec: 7 };
/// let s = uformat!(100, "{:^10}", time).unwrap();
/// assert_eq!("  031707  ", s.as_str());
/// ```
#[allow(non_camel_case_types)]
pub trait uDisplayPadded {
    /// Formats the value using the given formatter
    fn fmt_padded<W>(
        &self,
        _: &mut Formatter<'_, W>,
        padding: Padding,
        pad_char: char,
    ) -> Result<(), W::Error>
    where
        W: uWrite + ?Sized;
}

/// Creating formatted output string
///
/// See [uwrite] for details
/// 
/// ```
/// use std::f64::consts::PI;
/// use tfmt::{uDisplayFormatted, uformat, Convert};
///
/// struct Coord(f64);
///
/// impl uDisplayFormatted for Coord {
///     fn fmt_formatted<W>(
///         &self,
///         fmt: &mut tfmt::Formatter<'_, W>,
///         _prefix: bool,
///         cmd: char,
///         padding: tfmt::Padding,
///         pad_char: char,
///         decimal_places: usize,
///     ) -> Result<(), W::Error>
///     where
///         W: tfmt::uWrite + ?Sized,
///     {
///         let (sign, rad) = match cmd {
///             'E' => {
///                 if (*self).0.is_sign_positive() {
///                     (b'E', (*self).0)
///                 } else {
///                     (b'W', -(*self).0)
///                 }
///             }
///             _ => {
///                 if (*self).0.is_sign_positive() {
///                     (b'N', (*self).0)
///                 } else {
///                     (b'S', -(*self).0)
///                 }
///             }
///         };

///         let degs = rad * 180.0 / PI;
///         let mins = degs.fract() * 60.0;

///         let l_min = if decimal_places > 0 {
///             decimal_places + 3
///         } else {
///             decimal_places + 2
///         };

///         let mut conv = Convert::<15>::new(b'0');
///         conv.write_u8(sign).unwrap();
///         conv.write_u8(b',').unwrap();
///         conv.f64_pad(mins, l_min, decimal_places).unwrap();
///         conv.u32(degs as u32).unwrap();
///         fmt.write_padded(conv.as_str(), pad_char, padding)
///     }
/// }

/// let lat_berlin = Coord(0.9180516165333352);
/// let lon_berlin = Coord(0.23304198843966833);

/// /// format for coord is dddmm
/// let s = uformat!(100, "{:N0},{:E0}", lat_berlin, lon_berlin).unwrap();
/// assert_eq!("5236,N,1321,E", s.as_str());

/// /// format for coord is dddmm.mmm
/// let s = uformat!(100, "{:N3},{:E3}", lat_berlin, lon_berlin).unwrap();
/// assert_eq!("5236.029,N,1321.139,E", s.as_str());

/// /// format for coord is dddmm.mmmmmm
/// let s = uformat!(100, "{:013N6},{:014E6}", lat_berlin, lon_berlin).unwrap();
/// assert_eq!("5236.028980,N,01321.139343,E", s.as_str());
/// ```
#[allow(non_camel_case_types)]
pub trait uDisplayFormatted {
    /// Formats the value using the given formatter
    fn fmt_formatted<W>(
        &self,
        _: &mut Formatter<'_, W>,
        prefix: bool,
        cmd: char,
        padding: Padding,
        pad_char: char,
        behind: usize,
    ) -> Result<(), W::Error>
    where
        W: uWrite + ?Sized;
}

/// Converts numerical data types to &str
///
/// Convert contains a little public toolbox to convert numerical data to strings. So You can
/// integrate your own data types easily and efficiently.
///
/// You will only need this component eventually if you implement yourself the [uDisplay],
/// [uDisplayPadded] or the [uDisplayFormatted] trait of this crate.
pub struct Convert<const CAP: usize> {
    buf: [u8; CAP],
    idx: usize,
}

impl<const CAP: usize> Convert<CAP> {
    /// Creates a new Convert instance with buffer set to pad_char
    pub fn new(pad_char: u8) -> Convert<CAP> {
        Convert { buf: [pad_char; CAP], idx: CAP }
    }

    /// Returns a reference to the string contained in Convert
    pub fn as_str(&self) -> &str {
        // SAFETY: We only return characters here that we have previously initialised. This is
        // therefore safe and a new check for utf8 conformity is pointless.
        unsafe {
            let p_buf = self.buf.as_ptr().cast::<u8>();
            let length = CAP - self.idx;
            let slice = from_raw_parts(p_buf.add(self.idx), length);
            from_utf8_unchecked(slice)
        }
    }

    /// Writes a u8 to the buffer and post decrements the idx
    pub fn write_u8(&mut self, c: u8) -> Result<(), ()> {
        if self.idx > 0 {
            let p_buf = self.buf.as_mut_ptr().cast::<u8>();
            self.idx -= 1;
            // SAFETY: Since idx >= 0 and below CAP, this access is secure. This construct is
            // necessary because rust array accesses generate an undesired panicking branch.
            unsafe { p_buf.add(self.idx).write_volatile(c) };
            Ok(())
        } else {
            Err(())
        }
    }

    /// Writes a string to the buffer
    pub fn write_str(&mut self, s: &str) -> Result<(), ()> {
        for c in s.bytes().rev() {
            self.write_u8(c)?;
        }
        Ok(())
    }
}