ustyle 0.1.1

A text-styling library for Rust `no_std` embedded targets.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70

use crate::{DESCRIPTOR_LEN, END, START, Style};
use core::fmt;
use core::fmt::{Arguments, Write};

impl Style {
    /// Encode the style to a 3 byte long descriptor.
    pub fn encode_desc_bytes(&self) -> [u8; DESCRIPTOR_LEN] {
        [
            self.foreground.to_byte(),
            self.background.to_byte(),
            self.attributes.to_byte(),
        ]
    }

    /// Encode the style to a 3 char long descriptor.
    pub fn encode_desc(&self) -> [char; DESCRIPTOR_LEN] {
        [
            char::from(self.foreground.to_byte()),
            char::from(self.background.to_byte()),
            char::from(self.attributes.to_byte()),
        ]
    }

    /// Style the given string by writing the style descriptor and content to the specified writer.
    ///
    /// This will write exactly 5 bytes + the length of the string to the writer.
    pub fn style_to(&self, write: &mut dyn Write, string: &str) -> fmt::Result {
        let [fg, bg, attr] = self.encode_desc();

        write!(write, "{START}")?;
        write!(write, "{fg}")?;
        write!(write, "{bg}")?;
        write!(write, "{attr}")?;
        write!(write, "{string}")?;
        write!(write, "{END}")?;

        Ok(())
    }

    /// Style the given [Arguments] by writing the style descriptor and content to the specified writer.
    ///
    /// This will write exactly 5 bytes + the length of the string to the writer.
    pub fn style_fmt_to(&self, write: &mut dyn Write, args: &Arguments) -> fmt::Result {
        let [fg, bg, attr] = self.encode_desc();

        write!(write, "{START}")?;
        write!(write, "{fg}")?;
        write!(write, "{bg}")?;
        write!(write, "{attr}")?;
        write!(write, "{args}")?;
        write!(write, "{END}")?;

        Ok(())
    }

    /// Style the given string by writing the start character (`\x01`)
    /// and the style descriptor at the start of the string
    /// and adding the end character (`\x02`) at the end of the string.
    ///
    /// Returns the resulting heap-allocated [alloc::string::String].
    #[cfg(feature = "alloc")]
    pub fn style(&self, string: &str) -> alloc::string::String {
        let mut out = alloc::string::String::with_capacity(string.len() + crate::STYLE_LEN);

        self.style_to(&mut out, string)
            .expect("failed to style string");

        out
    }
}