string-width 0.1.0

Accurate Unicode string width calculation for terminal applications, handling emoji, East Asian characters, combining marks, and ANSI escape sequences
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97

#![deny(missing_docs)]

//! # string-width
//!
//! Accurate Unicode string width calculation for terminal applications.
//!
//! This library correctly handles:
//! - **Emoji sequences** (πŸ‘¨β€πŸ‘©β€πŸ‘§β€πŸ‘¦, πŸ‡ΊπŸ‡Έ, 1️⃣)
//! - **East Asian characters** (δ½ ε₯½, こんにけは, μ•ˆλ…•ν•˜μ„Έμš”)
//! - **Combining marks and diacritics** (Γ©, Γ±, ΓΌ)
//! - **Zero-width characters** (ZWJ, ZWNJ, format characters)
//! - **ANSI escape sequences** (colors, cursor movement)
//! - **Ambiguous width characters** (Β±, Γ—, Γ·)
//!
//! ## Quick Start
//!
//! ```rust
//! use string_width::string_width;
//!
//! // ASCII text
//! assert_eq!(string_width("Hello"), 5);
//!
//! // East Asian characters (full-width)
//! assert_eq!(string_width("δ½ ε₯½"), 4);
//!
//! // Emoji
//! assert_eq!(string_width("πŸ‘‹"), 2);
//! assert_eq!(string_width("πŸ‡ΊπŸ‡Έ"), 2);  // Flag
//! assert_eq!(string_width("1️⃣"), 2);   // Keycap sequence
//!
//! // Mixed content
//! assert_eq!(string_width("Hello πŸ‘‹ δΈ–η•Œ"), 13);
//!
//! // ANSI escape sequences are ignored by default
//! assert_eq!(string_width("\x1b[31mRed\x1b[0m"), 3);
//! ```
//!
//! ## Advanced Configuration
//!
//! ```rust
//! use string_width::{string_width, string_width_with_options, StringWidthOptions, AmbiguousWidthTreatment};
//!
//! // Direct configuration
//! let options = StringWidthOptions {
//!     count_ansi: true,  // Count ANSI escape sequences
//!     ambiguous_width: AmbiguousWidthTreatment::Wide,  // Treat ambiguous as wide
//! };
//!
//! assert_eq!(string_width_with_options("Β±Γ—Γ·", options.clone()), 6);  // Ambiguous chars as wide
//! assert_eq!(string_width_with_options("\x1b[31mRed\x1b[0m", options), 12);  // Count ANSI
//!
//! // Using the builder pattern (recommended)
//! let options = StringWidthOptions::builder()
//!     .count_ansi(true)
//!     .ambiguous_as_wide()
//!     .build();
//!
//! assert_eq!(string_width_with_options("Β±Γ—Γ·", options), 6);
//! ```
//!
//! ## Using the DisplayWidth Trait
//!
//! ```rust
//! use string_width::{DisplayWidth, StringWidthOptions};
//!
//! let text = "Hello 🌍";
//! println!("Width: {}", text.display_width());
//!
//! // With custom options
//! let options = StringWidthOptions::default();
//! println!("Width: {}", text.display_width_with_options(options));
//! ```

// Re-export the main functionality
pub use crate::options::{AmbiguousWidthTreatment, StringWidthOptions, StringWidthOptionsBuilder};
pub use crate::width_calculation::{DisplayWidth, string_width, string_width_with_options};

// Internal modules
/// Character classification utilities for width calculation
///
/// This module provides functions and types for classifying Unicode characters
/// into categories needed for accurate width calculation, including combining
/// marks, format characters, and prepend characters.
mod character_classification;

/// Emoji detection and classification
///
/// This module handles the complex logic of determining whether a grapheme
/// cluster represents an emoji that should be displayed with width 2,
/// including variation selectors, keycap sequences, and regional indicators.
mod emoji;
mod options;
mod unicode_constants;
mod width_calculation;

#[cfg(test)]
mod tests;