humfmt 0.6.0

Ergonomic human-readable formatting toolkit for Rust
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
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101

/// Builder-style configuration for list formatting.
///
/// `humfmt` list formatting is intentionally minimal and predictable:
/// it joins slices into natural-language lists with optional overrides.
///
/// # Examples
///
/// ```rust
/// use humfmt::ListOptions;
///
/// let opts = ListOptions::new()
///     .serial_comma_enabled(false)
///     .conjunction("plus");
///
/// assert_eq!(
///     humfmt::list_with(&["red", "green", "blue"], opts).to_string(),
///     "red, green plus blue"
/// );
/// ```
#[derive(Copy, Clone, Debug)]
pub struct ListOptions {
    pub(crate) serial_comma: bool,
    pub(crate) conjunction: &'static str,
    pub(crate) separator: &'static str,
}

impl ListOptions {
    /// Creates default list formatting options.
    ///
    /// Defaults:
    /// - serial comma: enabled (Oxford comma)
    /// - conjunction: `"and"`
    /// - separator: `", "`
    #[inline]
    pub const fn new() -> Self {
        Self {
            serial_comma: true,
            conjunction: "and",
            separator: ", ",
        }
    }

    /// Enables the serial comma before the final list item.
    ///
    /// Equivalent to `.serial_comma_enabled(true)`.
    #[inline]
    pub const fn serial_comma(mut self) -> Self {
        self.serial_comma = true;
        self
    }

    /// Configures serial-comma behavior with an explicit boolean.
    ///
    /// - `true`: `"a, b, and c"`
    /// - `false`: `"a, b and c"`
    #[inline]
    pub const fn serial_comma_enabled(mut self, enabled: bool) -> Self {
        self.serial_comma = enabled;
        self
    }

    /// Disables the serial comma before the final list item.
    ///
    /// Equivalent to `.serial_comma_enabled(false)`.
    #[inline]
    pub const fn no_serial_comma(mut self) -> Self {
        self.serial_comma = false;
        self
    }

    /// Overrides the conjunction used to join the final list item.
    ///
    /// Default is `"and"`.
    ///
    /// Example: `"plus"` produces `"a, b plus c"`.
    #[inline]
    pub const fn conjunction(mut self, word: &'static str) -> Self {
        self.conjunction = word;
        self
    }

    /// Overrides the separator placed between list items.
    ///
    /// Default is `", "`.
    ///
    /// Note: serial comma is only injected when the separator is comma-style.
    /// Custom separators like `" | "` will not get a serial comma even if
    /// enabled.
    #[inline]
    pub const fn separator(mut self, sep: &'static str) -> Self {
        self.separator = sep;
        self
    }
}

impl Default for ListOptions {
    #[inline]
    fn default() -> Self {
        Self::new()
    }
}