runefix_core/

grapheme.rs

use unicode_segmentation::UnicodeSegmentation;
use crate::width::get_display_width;

/// Returns the display width (in columns) of each grapheme cluster in the input string.
///
/// This function segments the input string into Unicode grapheme clusters and computes
/// the display width of each one individually. It is useful for scenarios like monospace
/// text layout, visual alignment, or rendering terminals where East Asian characters
/// and emoji take more than one column.
///
/// # Arguments
///
/// * `s` - The input string to analyze
///
/// # Returns
///
/// A vector of display widths (`usize`) for each grapheme cluster in order.
///
/// # Example
///
/// ```
/// use runefix_core::display_widths;
///
/// let widths = display_widths("Hi，世界");
/// assert_eq!(widths, vec![1, 1, 2, 2, 2]);
/// ```
pub fn display_widths(s: &str) -> Vec<usize> {
    UnicodeSegmentation::graphemes(s, true)
        .map(|g| get_display_width(g))
        .collect()
}

/// Returns the total display width (in columns) of a string, based on grapheme clusters.
///
/// This function segments the input string into Unicode grapheme clusters and sums
/// the display width of each one using [`display_width`]. The result reflects
/// how much horizontal space the entire string occupies in a monospace terminal,
/// accounting for wide characters such as CJK ideographs and emoji.
///
/// # Arguments
///
/// * `s` - The input string to measure
///
/// # Returns
///
/// The total display width of the string in terminal columns.
///
/// # Example
///
/// ```
/// use runefix_core::display_width;
///
/// let width = display_width("Hi，世界");
/// assert_eq!(width, 8); // 1 + 1 + 2 + 2 + 2
/// ```
pub fn display_width(s: &str) -> usize {
    display_widths(s).iter().sum()
}

/// Returns all grapheme clusters in the input string as a vector of string slices.
///
/// This function uses Unicode text segmentation to split the input into grapheme clusters,
/// which represent user-perceived characters. It correctly preserves multi-codepoint
/// graphemes such as emoji with skin tone modifiers, ZWJ sequences, and composed Hangul.
///
/// Useful when you need to iterate over characters in a way that aligns with human perception.
///
/// # Arguments
///
/// * `s` - The input string to split
///
/// # Returns
///
/// A vector of `&str`, each representing a single grapheme cluster in order.
///
/// # Example
///
/// ```
/// use runefix_core::split_graphemes;
///
/// let clusters = split_graphemes("Love👩‍❤️‍💋‍👨爱");
/// assert_eq!(clusters, vec!["L", "o", "v", "e", "👩‍❤️‍💋‍👨", "爱"]);
/// ```
pub fn split_graphemes(s: &str) -> Vec<&str> {
    UnicodeSegmentation::graphemes(s, true).collect()
}

/// Returns the display width of each grapheme cluster in the input string.
///
/// This function splits the string into Unicode grapheme clusters and pairs
/// each one with its terminal display width (in columns). This is useful for
/// visually aligned rendering, layout calculation, and Unicode debugging,
/// especially with complex emoji or East Asian characters.
///
/// # Arguments
///
/// * `s` - The input string to analyze
///
/// # Returns
///
/// A vector of tuples, where each item is a grapheme cluster and its
/// corresponding display width: `(&str, usize)`
///
/// # Example
///
/// ```
/// use runefix_core::grapheme_widths;
/// 
/// let result = grapheme_widths("Hi，世界");
/// assert_eq!(
///     result,
///     vec![("H", 1), ("i", 1), ("，", 2), ("世", 2), ("界", 2)]
/// );
/// ```
pub fn grapheme_widths(s: &str) -> Vec<(&str, usize)> {
    UnicodeSegmentation::graphemes(s, true)
        .map(|g| {
            let width = get_display_width(g);
            (g, width)
        })
        .collect()
}

/// Truncates a string by display width while preserving grapheme cluster boundaries.
///
/// This function ensures that wide characters such as emoji or CJK ideographs are
/// never split in the middle. It safely cuts off the string so that its total
/// display width does not exceed the given `max_width`, making it ideal for
/// terminal or TUI rendering.
///
/// # Arguments
///
/// * `s` - The input string to truncate
/// * `max_width` - Maximum allowed display width in terminal columns
///
/// # Returns
///
/// A string slice that fits within the specified display width without cutting graphemes.
///
/// # Example
///
/// ```
/// use runefix_core::truncate_by_width;
///
/// let s = "Hi 👋，世界";
/// let short = truncate_by_width(s, 6);
/// assert_eq!(short, "Hi 👋");
/// ```
pub fn truncate_by_width(s: &str, max_width: usize) -> &str {
    let mut total_width = 0;
    let mut end_byte = 0;

    for g in UnicodeSegmentation::graphemes(s, true) {
        let w = get_display_width(g);

        if total_width + w > max_width {
            break;
        }

        total_width += w;
        end_byte += g.len(); // Byte offset to cut safely
    }

    &s[..end_byte]
}

/// Splits a string into lines based on display width, preserving grapheme boundaries.
///
/// This function ensures that wide characters such as emoji, CJK ideographs, or
/// fullwidth punctuation are not split mid-grapheme. It breaks the input string
/// into a sequence of lines, each with a total display width that does not exceed
/// the given `max_width`. Ideal for terminal word wrapping and monospace layout.
///
/// # Arguments
///
/// * `s` - The input string to wrap
/// * `max_width` - Maximum display width (in columns) for each line
///
/// # Returns
///
/// A vector of strings, each representing a wrapped line within the given width.
///
/// # Example
///
/// ```
/// use runefix_core::split_by_width;
///
/// let lines = split_by_width("Hello 👋 世界！", 5);
/// assert_eq!(lines, vec!["Hello", " 👋 ", "世界", "！"]);
/// ```
pub fn split_by_width(s: &str, max_width: usize) -> Vec<String> {
    let mut result = Vec::new();
    let mut current_line = String::new();
    let mut current_width = 0;

    for g in UnicodeSegmentation::graphemes(s, true) {
        let width: usize = get_display_width(g);

        if current_width + width > max_width && !current_line.is_empty() {
            result.push(current_line.clone());
            current_line.clear();
            current_width = 0;
        }

        current_line.push_str(g);
        current_width += width;
    }

    if !current_line.is_empty() {
        result.push(current_line);
    }

    result
}