Function wrap_ansi 

pub fn wrap_ansi(
    string: &str,
    columns: usize,
    options: Option<WrapOptions>,
) -> String

🎨 The main text wrapping function with full ANSI escape sequence support.

This is the primary function for wrapping text while intelligently preserving ANSI escape sequences for colors, styles, and hyperlinks. It handles Unicode characters correctly and provides flexible wrapping options for any use case.

✨ Key Features

• 🎨 ANSI Preservation: Colors and styles are maintained across line breaks
• 🌍 Unicode Aware: Proper handling of CJK characters, emojis, and combining marks
• 🔗 Hyperlink Support: OSC 8 sequences remain clickable after wrapping
• ⚡ High Performance: Optimized algorithms with pre-compiled regex patterns
• 🛠️ Flexible Options: Customizable wrapping behavior via WrapOptions

Parameters

Parameter	Type	Description
string	&str	Input text (may contain ANSI sequences)
columns	usize	Maximum width in columns per line
options	Option<WrapOptions>	Wrapping configuration (uses defaults if None)

Returns

A String with text wrapped to the specified width, with all ANSI sequences properly preserved and applied to each line as needed.

Examples

📝 Basic Text Wrapping

use wrap_ansi::wrap_ansi;

let text = "The quick brown fox jumps over the lazy dog";
let wrapped = wrap_ansi(text, 20, None);
println!("{}", wrapped);
// Output:
// The quick brown fox
// jumps over the lazy
// dog

🎨 Colored Text Wrapping

use wrap_ansi::wrap_ansi;

// Red text that maintains color across line breaks
let colored = "\u{001B}[31mThis is a long red text that will be wrapped properly\u{001B}[39m";
let wrapped = wrap_ansi(colored, 15, None);
println!("{}", wrapped);
// Each line will have: \u{001B}[31m[text]\u{001B}[39m
// Output (with colors):
// This is a long
// red text that
// will be wrapped
// properly

🔗 Hyperlink Preservation

use wrap_ansi::wrap_ansi;

let link = "Visit \u{001B}]8;;https://example.com\u{0007}my website\u{001B}]8;;\u{0007} for more info";
let wrapped = wrap_ansi(link, 20, None);
// Hyperlinks remain clickable across line breaks

🌍 Unicode and Emoji Support

use wrap_ansi::wrap_ansi;

// CJK characters are counted as 2 columns each
let chinese = "你好世界！这是一个测试。";
let wrapped = wrap_ansi(chinese, 10, None);

// Emojis work correctly too
let emoji = "Hello 👋 World 🌍 with emojis 🎉";
let wrapped_emoji = wrap_ansi(emoji, 15, None);

⚙️ Advanced Configuration

use wrap_ansi::{wrap_ansi, WrapOptions};

// Using builder pattern for clean configuration
let options = WrapOptions::builder()
    .hard_wrap(true)           // Break long words at boundary
    .trim_whitespace(false)    // Preserve all whitespace
    .word_wrap(true)           // Still respect word boundaries where possible
    .build();

let text = "supercalifragilisticexpialidocious word";
let wrapped = wrap_ansi(text, 10, Some(options));
// Output:
// supercalif
// ragilistic
// expialidoc
// ious word

🎯 Real-World Use Cases

Terminal Application Help Text

use wrap_ansi::{wrap_ansi, WrapOptions};

fn format_help_text(text: &str, terminal_width: usize) -> String {
    let options = WrapOptions::builder()
        .hard_wrap(false)  // Keep words intact for readability
        .trim_whitespace(true)  // Clean formatting
        .build();
     
    wrap_ansi(text, terminal_width.saturating_sub(4), Some(options))
}

Code Syntax Highlighting

use wrap_ansi::wrap_ansi;

// Preserve syntax highlighting colors when wrapping code
let highlighted_code = "\u{001B}[34mfunction\u{001B}[39m \u{001B}[33mhello\u{001B}[39m() { \u{001B}[32m'world'\u{001B}[39m }";
let wrapped = wrap_ansi(highlighted_code, 25, None);
// Colors are preserved on each line

🎨 ANSI Sequence Support

Type	Codes	Description
Foreground Colors	30-37, 90-97	Standard and bright text colors
Background Colors	40-47, 100-107	Standard and bright background colors
Text Styles	1, 3, 4, 9	Bold, italic, underline, strikethrough
Color Resets	39, 49, 0	Foreground, background, and full reset
Hyperlinks	OSC 8	Clickable terminal links (OSC 8 sequences)
Custom SGR	Any	Support for any Select Graphic Rendition codes

When text with ANSI codes is wrapped across multiple lines, each line gets complete escape sequences (opening codes at the start, closing codes at the end).

🌍 Unicode Support Details

Feature	Support	Description
Fullwidth Characters	✅	CJK characters counted as 2 columns
Surrogate Pairs	✅	Proper handling of 4-byte Unicode sequences
Combining Characters	✅	Don’t add to visual width
Emoji	✅	Correct width calculation for emoji sequences
RTL Text	⚠️	Basic support (visual width only)

⚡ Performance Characteristics

• Time Complexity: O(n) where n is input length
• Space Complexity: O(n) for output string
• Regex Compilation: Pre-compiled patterns for optimal performance
• Memory Usage: Efficient string operations with capacity pre-allocation
• ANSI Parsing: Optimized state machine for escape sequence detection

🔧 Performance Tips

use wrap_ansi::{wrap_ansi, WrapOptions};

// For maximum performance with trusted input:
let fast_options = WrapOptions {
    trim: false,      // Skip trimming operations
    hard: false,      // Avoid complex word breaking
    word_wrap: true,  // Use efficient word boundary detection
};

// For memory-constrained environments, process in chunks:
fn wrap_large_text(text: &str, columns: usize) -> String {
    text.lines()
        .map(|line| wrap_ansi(line, columns, None))
        .collect::<Vec<_>>()
        .join("\n")
}

🚨 Important Notes

• Column Width: Must be > 0 (use wrap_ansi_checked for validation)
• Input Size: No built-in limits (use wrap_ansi_checked for protection)
• Line Endings: \r\n is normalized to \n automatically
• ANSI Sequences: Malformed sequences are passed through unchanged

See Also

• wrap_ansi_checked: Safe version with input validation and error handling
• WrapOptions: Detailed configuration options
• WrapOptionsBuilder: Fluent interface for creating options
• WrapError: Error types for the checked version

Examples found in repository

examples/improved_features.rs (line 15)

fn main() -> Result<(), WrapError> {
    println!("=== Wrap-ANSI Improved Features Demo ===\n");

    // 1. Builder Pattern for Options
    println!("1. Builder Pattern for Options:");
    let options = WrapOptions::builder()
        .hard_wrap(true)
        .trim_whitespace(false)
        .word_wrap(true)
        .build();

    let text = "This is a verylongwordthatexceedslimit example";
    let wrapped = wrap_ansi(text, 15, Some(options));
    println!("Input: {}", text);
    println!("Output:\n{}\n", wrapped);

    // 2. Error Handling with Input Validation
    println!("2. Error Handling:");

    // Valid input
    match wrap_ansi_checked("Hello world", 10, None) {
        Ok(result) => println!("Valid input wrapped: {}", result.replace('\n', "\\n")),
        Err(e) => println!("Error: {}", e),
    }

    // Invalid column width
    match wrap_ansi_checked("Hello world", 0, None) {
        Ok(result) => println!("Result: {}", result),
        Err(e) => println!("Expected error: {}", e),
    }

    // Large input (simulated)
    let large_text = "x".repeat(100);
    match wrap_ansi_checked(&large_text, 10, None) {
        Ok(result) => println!(
            "Large input handled: {} chars -> {} chars",
            large_text.len(),
            result.len()
        ),
        Err(e) => println!("Error with large input: {}", e),
    }

    println!();

    // 3. ANSI Color Preservation with Named Constants
    println!("3. ANSI Color Preservation:");
    let colored_text =
        "\u{001B}[31mThis is red text that will be wrapped across multiple lines\u{001B}[39m";
    let wrapped_colored = wrap_ansi(colored_text, 20, None);
    println!("Colored text wrapped:");
    println!("{}", wrapped_colored);
    println!();

    // 4. Hyperlink Preservation
    println!("4. Hyperlink Preservation:");
    let hyperlink_text = "\u{001B}]8;;https://example.com\u{0007}This is a clickable link that spans multiple lines\u{001B}]8;;\u{0007}";
    let wrapped_hyperlink = wrap_ansi(hyperlink_text, 15, None);
    println!("Hyperlink text wrapped:");
    println!("{}", wrapped_hyperlink);
    println!();

    // 5. Performance with Complex ANSI Sequences
    println!("5. Complex ANSI Sequences:");
    let complex_text =
        "\u{001B}[31m\u{001B}[42mRed text on green background\u{001B}[39m\u{001B}[49m normal text";
    let wrapped_complex = wrap_ansi(complex_text, 12, None);
    println!("Complex ANSI wrapped:");
    println!("{}", wrapped_complex);
    println!();

    // 6. Unicode Support
    println!("6. Unicode Support:");
    let unicode_text = "Hello 世界 🌍 こんにちは";
    let wrapped_unicode = wrap_ansi(unicode_text, 10, None);
    println!("Unicode text wrapped:");
    println!("{}", wrapped_unicode);

    Ok(())
}