Skip to main content

jmap_types/
text.rs

1//! Text handling for display text (draft-atwood-jmap-updates-00 §6).
2//!
3//! - [`truncate_graphemes`]: shorten text at an extended grapheme cluster
4//!   boundary (UAX #29) within an octet limit (§6.5), for previews,
5//!   notification bodies and push payloads.
6//! - [`check_display_text`]: the display-text profile of §6.2 (the
7//!   one- and two-dimensional Modern Network Unicode rules). It is a SHOULD
8//!   on content and a MAY for rejection; the crates offer the check and do
9//!   not enforce it by default (gap G4 in `docs/design/updates.md`).
10//!
11//! Servers SHOULD NOT normalize text they store and return (§6.3), and
12//! SHOULD give display text no meaning (§6.4): nothing here normalizes.
13
14use std::fmt;
15
16use icu_segmenter::GraphemeClusterSegmenter;
17
18/// The longest prefix of `s` that is at most `max_octets` bytes of UTF-8
19/// and ends at an extended grapheme cluster boundary (UAX #29), so no code
20/// point, combining sequence, emoji sequence or Hangul syllable is split
21/// (§6.5). Returns `s` unchanged when it already fits; the empty string
22/// when even the first cluster does not.
23///
24/// ```rust
25/// use jmap_types::text::truncate_graphemes;
26///
27/// // "e" + U+0301 COMBINING ACUTE ACCENT is one cluster of 3 octets.
28/// assert_eq!(truncate_graphemes("ae\u{301}b", 3), "a");
29/// assert_eq!(truncate_graphemes("ae\u{301}b", 4), "ae\u{301}");
30/// assert_eq!(truncate_graphemes("short", 100), "short");
31/// ```
32pub fn truncate_graphemes(s: &str, max_octets: usize) -> &str {
33    if s.len() <= max_octets {
34        return s;
35    }
36    let mut cut = 0;
37    for boundary in GraphemeClusterSegmenter::new().segment_str(s) {
38        if boundary > max_octets {
39            break;
40        }
41        cut = boundary;
42    }
43    &s[..cut]
44}
45
46/// [`truncate_graphemes`] for a limit in characters (Unicode scalar
47/// values) rather than octets, as the RFC 8621 §4.1.4 Email `preview`
48/// ("up to 256 characters") states it: the longest prefix of at most
49/// `max_chars` characters that ends at a grapheme cluster boundary.
50///
51/// ```rust
52/// use jmap_types::text::truncate_graphemes_chars;
53///
54/// assert_eq!(truncate_graphemes_chars("ae\u{301}b", 2), "a");
55/// assert_eq!(truncate_graphemes_chars("ae\u{301}b", 3), "ae\u{301}");
56/// ```
57pub fn truncate_graphemes_chars(s: &str, max_chars: usize) -> &str {
58    let limit = s.char_indices().nth(max_chars).map_or(s.len(), |(i, _)| i);
59    truncate_graphemes(s, limit)
60}
61
62/// Why a string breaks the display-text profile of
63/// draft-atwood-jmap-updates-00 §6.2.
64#[non_exhaustive]
65#[derive(Debug, Clone, PartialEq, Eq)]
66pub struct DisplayTextError {
67    /// Byte offset of the offending character.
68    pub index: usize,
69    /// The offending character.
70    pub ch: char,
71}
72
73impl fmt::Display for DisplayTextError {
74    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
75        write!(
76            f,
77            "display text has U+{:04X} at byte {}, which the display-text profile excludes",
78            self.ch as u32, self.index
79        )
80    }
81}
82
83impl std::error::Error for DisplayTextError {}
84
85/// Check `s` against the display-text profile of
86/// draft-atwood-jmap-updates-00 §6.2: no control characters U+0000 to
87/// U+001F and U+007F to U+009F (except U+000A LINE FEED when `multiline`,
88/// so lines end with LF alone and CR is rejected), no U+2028 LINE
89/// SEPARATOR or U+2029 PARAGRAPH SEPARATOR, no noncharacters U+FFFE and
90/// U+FFFF, and no leading U+FEFF byte order mark.
91///
92/// A server MAY reject display text that fails with an
93/// `invalidProperties` SetError naming the property. A specification may
94/// require a stricter profile, as RFC 8621 does for Mailbox names.
95///
96/// # Errors
97///
98/// [`DisplayTextError`] naming the first offending character.
99///
100/// ```rust
101/// use jmap_types::text::check_display_text;
102///
103/// assert!(check_display_text("Team contacts", false).is_ok());
104/// assert!(check_display_text("line 1\nline 2", true).is_ok());
105/// assert!(check_display_text("line 1\nline 2", false).is_err());
106/// assert!(check_display_text("line 1\r\nline 2", true).is_err());
107/// ```
108pub fn check_display_text(s: &str, multiline: bool) -> Result<(), DisplayTextError> {
109    for (index, ch) in s.char_indices() {
110        let u = ch as u32;
111        let bad = match u {
112            0x0A => !multiline,
113            0x00..=0x1F | 0x7F..=0x9F => true,
114            0x2028 | 0x2029 | 0xFFFE | 0xFFFF => true,
115            0xFEFF => index == 0,
116            _ => false,
117        };
118        if bad {
119            return Err(DisplayTextError { index, ch });
120        }
121    }
122    Ok(())
123}
124
125#[cfg(test)]
126mod tests {
127    use super::*;
128
129    /// UAX #29 examples: an emoji ZWJ sequence (GB11), a regional-indicator
130    /// flag (GB12/13) and a Hangul syllable of conjoining jamo (GB6-8) are
131    /// each one cluster and are never split.
132    #[test]
133    fn never_splits_clusters() {
134        // U+1F469 U+200D U+1F4BB (woman technologist): 4 + 3 + 4 octets.
135        let tech = "\u{1F469}\u{200D}\u{1F4BB}";
136        assert_eq!(truncate_graphemes(&format!("{tech}x"), 10), "");
137        assert_eq!(truncate_graphemes(&format!("{tech}x"), 11), tech);
138        // U+1F1E9 U+1F1EA (flag DE): 8 octets.
139        let de = "\u{1F1E9}\u{1F1EA}";
140        assert_eq!(truncate_graphemes(&format!("a{de}"), 8), "a");
141        // U+1100 U+1161 U+11A8 (Hangul L V T): 9 octets.
142        let gak = "\u{1100}\u{1161}\u{11A8}";
143        assert_eq!(truncate_graphemes(&format!("{gak}{gak}"), 12), gak);
144    }
145
146    /// §6.5: limits are in octets; a CR LF pair is one cluster (GB3).
147    #[test]
148    fn crlf_is_one_cluster() {
149        assert_eq!(truncate_graphemes("a\r\nb", 2), "a");
150        assert_eq!(truncate_graphemes("a\r\nb", 3), "a\r\n");
151    }
152
153    #[test]
154    fn zero_limit() {
155        assert_eq!(truncate_graphemes("abc", 0), "");
156    }
157
158    /// §6.2 profile, character by character.
159    #[test]
160    fn display_text_profile() {
161        for (s, multi) in [
162            ("tab\there", true),
163            ("nul\0", true),
164            ("del\u{7F}", true),
165            ("c1\u{85}", true),
166            ("ls\u{2028}", true),
167            ("ps\u{2029}", true),
168            ("nc\u{FFFE}", true),
169            ("nc\u{FFFF}", true),
170            ("\u{FEFF}bom", true),
171            ("cr\r", true),
172        ] {
173            assert!(check_display_text(s, multi).is_err(), "{s:?}");
174        }
175        // A U+FEFF that is not leading is a ZWNBSP, not a BOM.
176        assert!(check_display_text("a\u{FEFF}b", false).is_ok());
177        // Non-ASCII text and other format characters are fine.
178        assert!(check_display_text("Équipe \u{200D} 東京", false).is_ok());
179        let err = check_display_text("ab\u{2028}", false).unwrap_err();
180        assert_eq!((err.index, err.ch), (2, '\u{2028}'));
181    }
182}