Crate ansi_align 

ansi-align

A high-performance Rust library for aligning text with comprehensive support for ANSI escape sequences, Unicode characters, and customizable formatting options.

This crate provides robust text alignment capabilities that correctly handle:

• ANSI escape sequences (colors, formatting codes)
• Unicode characters with varying display widths (including CJK characters)
• Custom line separators and padding characters
• Performance-optimized algorithms for large text processing

🚀 Features

• 🎨 ANSI-aware alignment: Correctly handles text containing ANSI escape sequences
• 🌍 Unicode support: Properly calculates display width for all Unicode characters
• ⚡ High performance: Single-pass processing with optimized memory usage
• 🔧 Highly customizable: Configure alignment, separators, and padding
• 🛡️ Type-safe: Uses a Width type to prevent display width confusion
• 📦 Zero-copy optimizations: Left alignment is implemented as a no-op

📖 Quick Start

Add this to your Cargo.toml:

[dependencies]
ansi-align = "0.1.0"

Basic Usage

use ansi_align::{ansi_align, center, left, right};

// Basic alignment (defaults to center)
let text = "hello\nworld";
let centered = ansi_align(text);
println!("{}", centered);
// Output:
//  hello
// world

// Specific alignment functions
let left_aligned = left("short\nlonger line");
let centered = center("short\nlonger line");
let right_aligned = right("short\nlonger line");

ANSI Color Support

use ansi_align::center;

// Colors and formatting are preserved but don't affect alignment
let colored_text = "\x1b[31mRed\x1b[0m\n\x1b[32mGreen Text\x1b[0m";
let aligned = center(colored_text);
println!("{}", aligned);
// ANSI codes are preserved in output but ignored for width calculation

Unicode Character Support

use ansi_align::right;

// Correctly handles wide Unicode characters (CJK, emojis, etc.)
let unicode_text = "古\n古古古\nHello 世界";
let aligned = right(unicode_text);
println!("{}", aligned);
// Properly accounts for double-width characters

🔧 Advanced Usage

Custom Options

use ansi_align::{ansi_align_with_options, Alignment, AlignOptions};

// Custom separator and padding
let data = "Name|Age|City";
let options = AlignOptions::new(Alignment::Center)
    .with_split("|")
    .with_pad('_');

let result = ansi_align_with_options(data, &options);
println!("{}", result);
// Output: __Name|Age|City

Builder Pattern

use ansi_align::{ansi_align_with_options, Alignment, AlignOptions};

let options = AlignOptions::new(Alignment::Right)
    .with_split("<->")
    .with_pad('.');

let text = "short<->very long line";
let result = ansi_align_with_options(text, &options);

📊 Performance Characteristics

• Left alignment: O(1) - implemented as a no-op for maximum performance
• Center/Right alignment: O(n) - single pass through input text
• Memory usage: Minimal allocations with pre-calculated capacity
• Large text handling: Optimized padding creation for different sizes

🎯 Use Cases

• CLI applications: Align help text, tables, and menus
• Terminal UIs: Create visually appealing layouts
• Log formatting: Align log entries and structured output
• Code generation: Format generated code with proper indentation
• Documentation: Align text blocks in generated docs

🏗️ Architecture

The library is built around three core concepts:

1. Alignment - Defines the alignment direction (Left, Center, Right)
2. AlignOptions - Configuration for alignment behavior
3. Width - Type-safe wrapper for display width calculations

The main entry point is ansi_align_with_options, which provides full customization, while convenience functions like left, center, and right offer simplified APIs.

🔍 Examples

Menu Alignment

use ansi_align::center;

let menu = "🏠 Home\n📋 About\n📞 Contact\n⚙️ Settings";
let aligned_menu = center(menu);
println!("{}", aligned_menu);

Table-like Data

use ansi_align::{ansi_align_with_options, Alignment, AlignOptions};

let data = "ID|Name|Status";
let options = AlignOptions::new(Alignment::Center).with_split("|");
let result = ansi_align_with_options(data, &options);

Code Block Alignment

use ansi_align::right;

let code = "if condition:\n    execute()\nelse:\n    handle_error()";
let aligned = right(code);
println!("{}", aligned);

Structs

AlignOptions

Configuration options for text alignment operations.

Width

A type-safe wrapper for display width values.

Enums

Alignment

Specifies the alignment direction for text.

Functions

ansi_align

Align text with center alignment (default behavior)

ansi_align_with_options

Aligns text with comprehensive support for ANSI escape sequences and Unicode characters.

center

Align text to the center

left

Align text to the left (no-op, returns original text)

right

Align text to the right