Struct WrapOptions 

pub struct WrapOptions {
    pub trim: bool,
    pub hard: bool,
    pub word_wrap: bool,
}

🎛️ Configuration options for advanced text wrapping behavior.

This struct provides fine-grained control over how text is wrapped, including whitespace handling, word breaking strategies, and wrapping modes. All options work seamlessly with ANSI escape sequences and Unicode text.

Quick Reference

Option	Default	Description
trim	true	Remove leading/trailing whitespace from wrapped lines
hard	false	Break long words at column boundary (vs. moving to next line)
word_wrap	true	Respect word boundaries when wrapping

Examples

Default Configuration

use wrap_ansi::{wrap_ansi, WrapOptions};

// These are equivalent
let result1 = wrap_ansi("Hello world", 10, None);
let result2 = wrap_ansi("Hello world", 10, Some(WrapOptions::default()));
assert_eq!(result1, result2);

Builder Pattern (Recommended)

use wrap_ansi::{wrap_ansi, WrapOptions};

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

let text = "supercalifragilisticexpialidocious";
let wrapped = wrap_ansi(text, 10, Some(options));
// Result: "supercalif\nragilistic\nexpialidoc\nious"

Struct Initialization

use wrap_ansi::{wrap_ansi, WrapOptions};

// Character-level wrapping for monospace layouts
let char_wrap = WrapOptions {
    hard: true,
    trim: true,
    word_wrap: false,  // Break anywhere, ignore word boundaries
};

let text = "hello world";
let wrapped = wrap_ansi(text, 7, Some(char_wrap));
// Result: "hello w\norld"

Common Configurations

Terminal Output (Default)

let terminal = WrapOptions::default(); // Soft wrap, trim spaces, respect words

Code/Monospace Text

let code = WrapOptions {
    hard: true,        // Break long identifiers
    trim: false,       // Preserve indentation
    word_wrap: false,  // Break anywhere for consistent columns
};

Natural Language

let prose = WrapOptions {
    hard: false,       // Keep words intact
    trim: true,        // Clean up spacing
    word_wrap: true,   // Break at word boundaries
};

Fields

trim: bool

🧹 Whitespace trimming control

When true (default), leading and trailing spaces are automatically removed from lines that result from wrapping, creating clean, left-aligned text. When false, all whitespace is preserved exactly as in the input.

Use Cases

• true: Clean terminal output, formatted text display
• false: Code formatting, preserving indentation, ASCII art

Examples

use wrap_ansi::{wrap_ansi, WrapOptions};

let text = "   hello    world   ";

// With trimming (default)
let trimmed = wrap_ansi(text, 8, None);
assert_eq!(trimmed, "hello\nworld");

// Without trimming - preserves all spaces
let options = WrapOptions { trim: false, ..Default::default() };
let untrimmed = wrap_ansi(text, 8, Some(options));
assert_eq!(untrimmed, "   hello\n    \nworld   ");

hard: bool

⚡ Word breaking strategy

Controls how long words that exceed the column limit are handled:

• false (default, soft wrapping): Long words move to the next line intact
• true (hard wrapping): Long words are broken at the column boundary

Use Cases

• Soft wrap: Natural text flow, readability, terminal output
• Hard wrap: Strict width constraints, tabular data, code formatting

Examples

use wrap_ansi::{wrap_ansi, WrapOptions};

let long_word = "supercalifragilisticexpialidocious";

// Soft wrapping - word stays intact
let soft = wrap_ansi(long_word, 10, None);
assert_eq!(soft, "supercalifragilisticexpialidocious"); // No wrapping!

// Hard wrapping - word is broken
let options = WrapOptions { hard: true, ..Default::default() };
let hard = wrap_ansi(long_word, 10, Some(options));
assert_eq!(hard, "supercalif\nragilistic\nexpialidoc\nious");

word_wrap: bool

🔤 Word boundary respect

Determines whether wrapping should occur at word boundaries (spaces) or can break anywhere within the text:

• true (default): Text wraps at word boundaries, preserving word integrity
• false: Text can wrap at any character position (character-level wrapping)

Use Cases

• Word boundaries: Natural language, readable text, most terminal output
• Character boundaries: Monospace layouts, code, precise column control

Examples

use wrap_ansi::{wrap_ansi, WrapOptions};

let text = "hello world";

// Word wrapping (default) - breaks at spaces
let word_wrap = wrap_ansi(text, 7, None);
assert_eq!(word_wrap, "hello\nworld");

// Character wrapping - breaks anywhere
let options = WrapOptions { word_wrap: false, ..Default::default() };
let char_wrap = wrap_ansi(text, 7, Some(options));
assert_eq!(char_wrap, "hello w\norld");

Implementations

impl WrapOptions

pub fn builder() -> WrapOptionsBuilder

🏗️ Create a new fluent builder for WrapOptions.

This is the recommended way to create custom WrapOptions configurations as it provides a clean, readable interface with method chaining.

Examples

use wrap_ansi::WrapOptions;

// Simple configuration
let options = WrapOptions::builder()
    .hard_wrap(true)
    .build();

// Complex configuration
let advanced = WrapOptions::builder()
    .hard_wrap(false)        // Soft wrapping
    .trim_whitespace(true)   // Clean output
    .word_wrap(true)         // Respect word boundaries
    .build();

Examples found in repository

examples/improved_features.rs (line 8)

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(())
}

Trait Implementations

impl Clone for WrapOptions

fn clone(&self) -> WrapOptions

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for WrapOptions

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for WrapOptions

fn default() -> Self

Returns the “default value” for a type.

impl Hash for WrapOptions

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for WrapOptions

fn eq(&self, other: &WrapOptions) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for WrapOptions

impl Eq for WrapOptions

impl StructuralPartialEq for WrapOptions