ansi_align/

lib.rs

//! # ansi-align
//!
//! A Rust library for aligning text with proper support for ANSI escape sequences and Unicode characters.
//!
//! This crate provides functions to align text in various ways (left, center, right) while correctly
//! handling ANSI escape sequences (like color codes) and Unicode characters with varying display widths.
//!
//! ## Features
//!
//! - **ANSI-aware alignment**: Correctly handles text containing ANSI escape sequences
//! - **Unicode support**: Properly calculates display width for Unicode characters including CJK
//! - **Multiple alignment options**: Left, center, and right alignment
//! - **Customizable**: Configure split strings and padding characters
//! - **Performance optimized**: Single-pass processing with efficient memory usage
//! - **Type-safe**: Uses a [`Width`] type for display width values
//!
//! ## Quick Start
//!
//! ```rust
//! use ansi_align::{ansi_align, center, left, right};
//!
//! // Basic alignment (defaults to center)
//! let text = "hello\nworld";
//! let centered = ansi_align(text);
//!
//! // Specific alignment functions
//! let left_aligned = left("short\nlonger line");
//! let centered = center("short\nlonger line");
//! let right_aligned = right("short\nlonger line");
//! ```
//!
//! ## Advanced Usage
//!
//! ```rust
//! use ansi_align::{ansi_align_with_options, Alignment, AlignOptions};
//!
//! let text = "line1|line2|line3";
//! let options = AlignOptions::new(Alignment::Right)
//!     .with_split("|")
//!     .with_pad('.');
//!
//! let result = ansi_align_with_options(text, &options);
//! ```

#![deny(missing_docs)]
#![warn(clippy::all)]
#![warn(clippy::pedantic)]
#![warn(clippy::nursery)]

use std::fmt;
use std::ops::{Add, Div, Mul, Sub};
use string_width::string_width;

/// Specifies the alignment direction for text.
///
/// This enum defines the three possible alignment options that can be used
/// with the alignment functions.
///
/// # Examples
///
/// ```rust
/// use ansi_align::{Alignment, AlignOptions, ansi_align_with_options};
///
/// let text = "hello\nworld";
///
/// // Center alignment
/// let opts = AlignOptions::new(Alignment::Center);
/// let result = ansi_align_with_options(text, &opts);
///
/// // Right alignment
/// let opts = AlignOptions::new(Alignment::Right);
/// let result = ansi_align_with_options(text, &opts);
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Alignment {
    /// Align text to the left (no padding added to the left side)
    Left,
    /// Align text to the center (padding distributed evenly on both sides)
    Center,
    /// Align text to the right (padding added to the left side)
    Right,
}

/// A type-safe wrapper for display width values.
///
/// This type represents the visual width of text as it would appear on screen,
/// taking into account ANSI escape sequences and Unicode character widths.
/// It provides type safety to prevent confusion between byte lengths and display widths.
///
/// # Examples
///
/// ```rust
/// use ansi_align::Width;
///
/// let width = Width::new(42);
/// assert_eq!(width.get(), 42);
///
/// // Convert from usize
/// let width: Width = 24.into();
/// assert_eq!(width.get(), 24);
///
/// // Ordering works as expected
/// assert!(Width::new(10) < Width::new(20));
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub struct Width(usize);

impl Width {
    /// Creates a new `Width` value from a `usize`.
    ///
    /// # Arguments
    ///
    /// * `value` - The display width value
    ///
    /// # Examples
    ///
    /// ```rust
    /// use ansi_align::Width;
    ///
    /// let width = Width::new(10);
    /// assert_eq!(width.get(), 10);
    /// ```
    #[must_use]
    pub const fn new(value: usize) -> Self {
        Self(value)
    }

    /// Returns the underlying `usize` value.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use ansi_align::Width;
    ///
    /// let width = Width::new(42);
    /// assert_eq!(width.get(), 42);
    /// ```
    #[must_use]
    pub const fn get(self) -> usize {
        self.0
    }

    /// Saturating subtraction that doesn't underflow
    ///
    /// # Examples
    ///
    /// ```rust
    /// use ansi_align::Width;
    ///
    /// let width = Width::new(5);
    /// let result = width.saturating_sub(Width::new(10));
    /// assert_eq!(result.get(), 0); // Would underflow, but saturates to 0
    /// ```
    #[must_use]
    pub const fn saturating_sub(self, other: Self) -> Self {
        Self(self.0.saturating_sub(other.0))
    }

    /// Check if width is zero
    ///
    /// # Examples
    ///
    /// ```rust
    /// use ansi_align::Width;
    ///
    /// assert!(Width::new(0).is_zero());
    /// assert!(!Width::new(5).is_zero());
    /// ```
    #[must_use]
    pub const fn is_zero(self) -> bool {
        self.0 == 0
    }
}

impl From<usize> for Width {
    fn from(value: usize) -> Self {
        Self(value)
    }
}

impl Add for Width {
    type Output = Self;
    fn add(self, other: Self) -> Self {
        Self(self.0 + other.0)
    }
}

impl Sub for Width {
    type Output = Self;
    fn sub(self, other: Self) -> Self {
        Self(self.0 - other.0)
    }
}

impl Mul for Width {
    type Output = Self;
    fn mul(self, other: Self) -> Self {
        Self(self.0 * other.0)
    }
}

impl Div for Width {
    type Output = Self;
    fn div(self, other: Self) -> Self {
        Self(self.0 / other.0)
    }
}

impl fmt::Display for Width {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.0)
    }
}

/// Configuration options for text alignment operations.
///
/// This struct allows you to customize how text alignment is performed,
/// including the alignment direction, line separator, and padding character.
///
/// # Examples
///
/// ```rust
/// use ansi_align::{AlignOptions, Alignment, ansi_align_with_options};
///
/// // Basic usage with default settings
/// let opts = AlignOptions::new(Alignment::Center);
///
/// // Customized options
/// let opts = AlignOptions::new(Alignment::Right)
///     .with_split("|")
///     .with_pad('.');
///
/// let text = "short|longer text";
/// let result = ansi_align_with_options(text, &opts);
/// ```
#[derive(Debug, Clone)]
pub struct AlignOptions {
    /// The alignment type (left, center, right)
    pub align: Alignment,
    /// The string to split lines on (default: "\n")
    pub split: String,
    /// The padding character to use (default: " ")
    pub pad: char,
}

impl Default for AlignOptions {
    fn default() -> Self {
        Self {
            align: Alignment::Center,
            split: "\n".to_string(),
            pad: ' ',
        }
    }
}

impl AlignOptions {
    /// Creates new alignment options with the specified alignment direction.
    ///
    /// Uses default values for split string (`"\n"`) and padding character (`' '`).
    ///
    /// # Arguments
    ///
    /// * `align` - The alignment direction to use
    ///
    /// # Examples
    ///
    /// ```rust
    /// use ansi_align::{AlignOptions, Alignment};
    ///
    /// let opts = AlignOptions::new(Alignment::Center);
    /// ```
    #[must_use]
    pub fn new(align: Alignment) -> Self {
        Self {
            align,
            ..Default::default()
        }
    }

    /// Sets the string used to split lines using the builder pattern.
    ///
    /// By default, lines are split on `"\n"`, but you can specify any string
    /// as a line separator.
    ///
    /// # Arguments
    ///
    /// * `split` - The string to use as a line separator
    ///
    /// # Examples
    ///
    /// ```rust
    /// use ansi_align::{AlignOptions, Alignment};
    ///
    /// let opts = AlignOptions::new(Alignment::Center)
    ///     .with_split("|")
    ///     .with_split("<->"); // Multi-character separators work too
    /// ```
    #[must_use]
    pub fn with_split<S: Into<String>>(mut self, split: S) -> Self {
        self.split = split.into();
        self
    }

    /// Sets the character used for padding using the builder pattern.
    ///
    /// By default, spaces (`' '`) are used for padding, but you can specify
    /// any character.
    ///
    /// # Arguments
    ///
    /// * `pad` - The character to use for padding
    ///
    /// # Examples
    ///
    /// ```rust
    /// use ansi_align::{AlignOptions, Alignment};
    ///
    /// let opts = AlignOptions::new(Alignment::Right)
    ///     .with_pad('.');
    /// ```
    #[must_use]
    pub const fn with_pad(mut self, pad: char) -> Self {
        self.pad = pad;
        self
    }
}

/// Efficiently create padding string for alignment
fn create_padding(pad_char: char, count: usize) -> String {
    match count {
        0 => String::new(),
        1 => pad_char.to_string(),
        // Use repeat for small counts (more efficient)
        2..=16 => pad_char.to_string().repeat(count),
        // Use with_capacity + push for larger counts to avoid reallocations
        _ => {
            let mut padding = String::with_capacity(count * pad_char.len_utf8());
            for _ in 0..count {
                padding.push(pad_char);
            }
            padding
        }
    }
}

/// Align text with center alignment (default behavior)
#[must_use]
pub fn ansi_align(text: &str) -> String {
    ansi_align_with_options(text, &AlignOptions::default())
}

/// Calculate display widths for lines
fn calculate_line_widths<'a>(text: &'a str, split: &str) -> Vec<(&'a str, Width)> {
    text.split(split)
        .map(|line| (line, Width::from(string_width(line))))
        .collect()
}

/// Find the maximum width among lines
fn find_max_width(line_data: &[(&str, Width)]) -> Width {
    line_data
        .iter()
        .map(|(_, width)| *width)
        .max()
        .unwrap_or(Width::new(0))
}

/// Apply alignment to a single line
fn align_line(
    line: &str,
    line_width: Width,
    max_width: Width,
    alignment: Alignment,
    pad_char: char,
) -> String {
    let padding_needed = match alignment {
        Alignment::Left => 0,
        Alignment::Center => (max_width.get() - line_width.get()) / 2,
        Alignment::Right => max_width.get() - line_width.get(),
    };

    if padding_needed == 0 {
        line.to_string()
    } else {
        let mut result = create_padding(pad_char, padding_needed);
        result.push_str(line);
        result
    }
}

/// Align text with support for ANSI escape sequences
///
/// This function handles text containing ANSI escape sequences (like color codes)
/// by calculating display width correctly, ignoring the escape sequences.
///
/// # Examples
///
/// ```
/// use ansi_align::{ansi_align, ansi_align_with_options, Alignment, AlignOptions};
///
/// // Basic center alignment
/// let result = ansi_align("hello\nworld");
///
/// // Right alignment with custom padding
/// let opts = AlignOptions::new(Alignment::Right).with_pad('.');
/// let result = ansi_align_with_options("hi\nhello", &opts);
///
/// // Works with ANSI escape sequences
/// let colored = "\x1b[31mred\x1b[0m\n\x1b[32mgreen\x1b[0m";
/// let result = ansi_align_with_options(colored, &AlignOptions::new(Alignment::Center));
/// ```
///
/// # Performance
///
/// This function makes a single pass through the input text for optimal performance.
/// For left alignment, it returns the input unchanged as an optimization.
#[must_use]
pub fn ansi_align_with_options(text: &str, opts: &AlignOptions) -> String {
    if text.is_empty() || opts.align == Alignment::Left {
        return text.to_string();
    }

    let line_data = calculate_line_widths(text, &opts.split);
    let max_width = find_max_width(&line_data);

    let aligned_lines: Vec<String> = line_data
        .into_iter()
        .map(|(line, width)| align_line(line, width, max_width, opts.align, opts.pad))
        .collect();

    aligned_lines.join(&opts.split)
}

/// Align text to the left (no-op, returns original text)
#[must_use]
pub fn left(text: &str) -> String {
    ansi_align_with_options(text, &AlignOptions::new(Alignment::Left))
}

/// Align text to the center
#[must_use]
pub fn center(text: &str) -> String {
    ansi_align_with_options(text, &AlignOptions::new(Alignment::Center))
}

/// Align text to the right
#[must_use]
pub fn right(text: &str) -> String {
    ansi_align_with_options(text, &AlignOptions::new(Alignment::Right))
}

#[cfg(test)]
mod tests {
    use super::*;

    // Basic alignment tests
    #[test]
    fn test_left_alignment() {
        let text = "hello\nworld";
        let result = left(text);
        assert_eq!(result, text); // Left alignment should be no-op
    }

    #[test]
    fn test_center_alignment() {
        let text = "hi\nhello";
        let result = center(text);
        let lines: Vec<&str> = result.split('\n').collect();
        assert_eq!(lines[0], " hi"); // 1 space padding for "hi"
        assert_eq!(lines[1], "hello"); // No padding for "hello"
    }

    #[test]
    fn test_right_alignment() {
        let text = "hi\nhello";
        let result = right(text);
        let lines: Vec<&str> = result.split('\n').collect();
        assert_eq!(lines[0], "   hi"); // 3 spaces padding for "hi"
        assert_eq!(lines[1], "hello"); // No padding for "hello"
    }

    // Unicode and ANSI tests
    #[test]
    fn test_unicode_characters() {
        let text = "古\n古古古";
        let result = center(text);
        let lines: Vec<&str> = result.split('\n').collect();
        assert_eq!(lines[0], "  古"); // 2 spaces padding (CJK char is width 2)
        assert_eq!(lines[1], "古古古"); // No padding
    }

    #[test]
    fn test_ansi_escape_sequences() {
        let text = "hello\n\u{001B}[1mworld\u{001B}[0m";
        let result = center(text);
        let lines: Vec<&str> = result.split('\n').collect();
        assert_eq!(lines[0], "hello");
        assert_eq!(lines[1], "\u{001B}[1mworld\u{001B}[0m"); // ANSI codes preserved
    }

    #[test]
    fn test_complex_ansi_sequences() {
        // Test with multiple ANSI codes and colors
        let text = "\x1b[31m\x1b[1mred\x1b[0m\n\x1b[32mgreen text\x1b[0m";
        let result = right(text);
        let lines: Vec<&str> = result.split('\n').collect();
        // "red" has display width 3, "green text" has width 10
        assert_eq!(lines[0], "       \x1b[31m\x1b[1mred\x1b[0m"); // 7 spaces padding
        assert_eq!(lines[1], "\x1b[32mgreen text\x1b[0m"); // No padding
    }

    // Edge cases
    #[test]
    fn test_empty_string() {
        assert_eq!(ansi_align_with_options("", &AlignOptions::default()), "");
        assert_eq!(left(""), "");
        assert_eq!(center(""), "");
        assert_eq!(right(""), "");
    }

    #[test]
    fn test_single_line() {
        let text = "hello";
        assert_eq!(left(text), "hello");
        assert_eq!(center(text), "hello");
        assert_eq!(right(text), "hello");
    }

    #[test]
    fn test_single_character() {
        let text = "a\nb";
        let result = center(text);
        assert_eq!(result, "a\nb"); // Both lines same width, no padding needed
    }

    #[test]
    fn test_whitespace_only() {
        let text = "   \n ";
        let result = center(text);
        let lines: Vec<&str> = result.split('\n').collect();
        assert_eq!(lines[0], "   "); // 3 spaces, no padding needed
        assert_eq!(lines[1], "  "); // 1 space + 1 padding space
    }

    // Custom options tests
    #[test]
    fn test_custom_split_and_pad() {
        let text = "a|bb";
        let opts = AlignOptions::new(Alignment::Right)
            .with_split("|")
            .with_pad('.');
        let result = ansi_align_with_options(text, &opts);
        assert_eq!(result, ".a|bb");
    }

    #[test]
    fn test_custom_split_multichar() {
        let text = "short<->very long line";
        let opts = AlignOptions::new(Alignment::Center).with_split("<->");
        let result = ansi_align_with_options(text, &opts);
        assert_eq!(result, "    short<->very long line");
    }

    #[test]
    fn test_different_padding_chars() {
        let text = "hi\nhello";

        // Test dot padding
        let opts = AlignOptions::new(Alignment::Right).with_pad('.');
        let result = ansi_align_with_options(text, &opts);
        assert_eq!(result, "...hi\nhello");

        // Test underscore padding
        let opts = AlignOptions::new(Alignment::Center).with_pad('_');
        let result = ansi_align_with_options(text, &opts);
        assert_eq!(result, "_hi\nhello");

        // Test zero padding
        let opts = AlignOptions::new(Alignment::Right).with_pad('0');
        let result = ansi_align_with_options(text, &opts);
        assert_eq!(result, "000hi\nhello");
    }

    // Performance and memory optimization tests
    #[test]
    fn test_large_padding() {
        let text = format!("a\n{}", "b".repeat(100));
        let result = right(&text);
        let lines: Vec<&str> = result.split('\n').collect();
        assert_eq!(lines[0].len(), 100); // 99 spaces + "a"
        assert!(lines[0].starts_with(&" ".repeat(99)));
        assert!(lines[0].ends_with('a'));
        assert_eq!(lines[1], "b".repeat(100));
    }

    #[test]
    fn test_no_padding_optimization() {
        // Test that lines requiring no padding are handled efficiently
        let text = "same\nsame\nsame";
        let result = center(text);
        assert_eq!(result, text); // Should be unchanged
    }

    // Width type tests
    #[test]
    fn test_width_type() {
        let width = Width::new(42);
        assert_eq!(width.get(), 42);

        let width_from_usize: Width = 24.into();
        assert_eq!(width_from_usize.get(), 24);

        // Test ordering
        assert!(Width::new(10) < Width::new(20));
        assert_eq!(Width::new(15), Width::new(15));
    }

    #[test]
    fn test_width_arithmetic() {
        let w1 = Width::new(10);
        let w2 = Width::new(5);

        // Test addition
        assert_eq!((w1 + w2).get(), 15);

        // Test subtraction
        assert_eq!((w1 - w2).get(), 5);

        // Test multiplication
        assert_eq!((w1 * w2).get(), 50);

        // Test division
        assert_eq!((w1 / w2).get(), 2);

        // Test saturating subtraction
        assert_eq!(w2.saturating_sub(w1).get(), 0); // 5 - 10 = 0 (saturated)
        assert_eq!(w1.saturating_sub(w2).get(), 5); // 10 - 5 = 5

        // Test is_zero
        assert!(Width::new(0).is_zero());
        assert!(!w1.is_zero());
    }

    #[test]
    fn test_width_display() {
        let width = Width::new(42);
        assert_eq!(format!("{width}"), "42");
    }

    // Comprehensive alignment scenarios
    #[test]
    fn test_mixed_width_lines() {
        let text = "a\nbb\nccc\ndddd\neeeee";

        // Center alignment
        let result = center(text);
        let lines: Vec<&str> = result.split('\n').collect();

        // The longest line is "eeeee" with 5 chars
        // So padding for center should be: (5-1)/2=2, (5-2)/2=1, (5-3)/2=1, (5-4)/2=0, (5-5)/2=0
        assert_eq!(lines[0], "  a"); // 2 spaces + "a"
        assert_eq!(lines[1], " bb"); // 1 space + "bb"
        assert_eq!(lines[2], " ccc"); // 1 space + "ccc" (corrected)
        assert_eq!(lines[3], "dddd"); // no padding (corrected)
        assert_eq!(lines[4], "eeeee"); // no padding

        // Right alignment
        let result = right(text);
        let lines: Vec<&str> = result.split('\n').collect();
        assert_eq!(lines[0], "    a"); // 4 spaces + "a"
        assert_eq!(lines[1], "   bb"); // 3 spaces + "bb"
        assert_eq!(lines[2], "  ccc"); // 2 spaces + "ccc"
        assert_eq!(lines[3], " dddd"); // 1 space + "dddd"
        assert_eq!(lines[4], "eeeee"); // no padding
    }

    #[test]
    fn test_center_odd_padding() {
        // Test center alignment with odd padding amounts
        let text = "a\nbbbb";
        let result = center(text);
        let lines: Vec<&str> = result.split('\n').collect();
        assert_eq!(lines[0], " a"); // (4-1)/2 = 1 space
        assert_eq!(lines[1], "bbbb"); // no padding
    }

    #[test]
    fn test_multiline_with_empty_lines() {
        let text = "hello\n\nworld";
        let result = center(text);
        let lines: Vec<&str> = result.split('\n').collect();
        assert_eq!(lines[0], "hello");
        assert_eq!(lines[1], "  "); // 2 spaces for empty line (center of 5-char width)
        assert_eq!(lines[2], "world");
    }

    // Regression tests for performance improvements
    #[test]
    fn test_no_unnecessary_allocations() {
        // This test ensures we don't regress on the performance improvements
        let text = "line1\nline2\nline3";
        let result = left(text);
        // Left alignment should return original string (no allocations for processing)
        assert_eq!(result, text);
    }

    #[test]
    fn test_padding_efficiency() {
        // Test the efficient padding creation for different sizes
        let text = format!("a\n{}", "b".repeat(20));

        // Small padding (should use repeat)
        let opts = AlignOptions::new(Alignment::Right);
        let result = ansi_align_with_options("a\nbb", &opts);
        assert_eq!(result, " a\nbb");

        // Large padding (should use with_capacity)
        let result = ansi_align_with_options(&text, &opts);
        let lines: Vec<&str> = result.split('\n').collect();
        assert_eq!(lines[0].len(), 20); // 19 spaces + "a"
        assert!(lines[0].ends_with('a'));
    }

    #[test]
    fn test_create_padding_unicode() {
        // Test padding with Unicode characters
        let text = "a\nbb";
        let opts = AlignOptions::new(Alignment::Right).with_pad('•');
        let result = ansi_align_with_options(text, &opts);
        assert_eq!(result, "•a\nbb");

        // Test with multi-byte Unicode character
        let opts = AlignOptions::new(Alignment::Right).with_pad('🎯');
        let result = ansi_align_with_options(text, &opts);
        assert_eq!(result, "🎯a\nbb");
    }

    // Integration tests
    #[test]
    fn test_real_world_scenario() {
        // Simulate aligning a simple table or menu
        let menu = "Home\nAbout Us\nContact\nServices";
        let result = center(menu);
        let lines: Vec<&str> = result.split('\n').collect();

        // "About Us" and "Services" are both 8 chars (longest)
        assert_eq!(lines[0], "  Home"); // 2 spaces (8-4)/2 = 2
        assert_eq!(lines[1], "About Us"); // no padding (8 chars)
        assert_eq!(lines[2], "Contact"); // no padding - "Contact" is 7 chars, (8-7)/2 = 0
        assert_eq!(lines[3], "Services"); // no padding (8 chars)
    }

    #[test]
    fn test_code_alignment() {
        // Test aligning code-like content
        let code = "if x:\n    return y\nelse:\n    return z";
        let result = right(code);
        let lines: Vec<&str> = result.split('\n').collect();

        // "    return y" and "    return z" are longest at 12 chars
        assert_eq!(lines[0], "       if x:"); // 7 spaces + "if x:" (12-5=7)
        assert_eq!(lines[1], "    return y"); // no padding (12 chars)
        assert_eq!(lines[2], "       else:"); // 7 spaces + "else:" (12-5=7)
        assert_eq!(lines[3], "    return z"); // no padding (12 chars)
    }
}