string_width/
lib.rs

1#![deny(missing_docs)]
2
3//! # string-width
4//!
5//! Accurate Unicode string width calculation for terminal applications.
6//!
7//! This library correctly handles:
8//! - **Emoji sequences** (πŸ‘¨β€πŸ‘©β€πŸ‘§β€πŸ‘¦, πŸ‡ΊπŸ‡Έ, 1️⃣)
9//! - **East Asian characters** (δ½ ε₯½, こんにけは, μ•ˆλ…•ν•˜μ„Έμš”)
10//! - **Combining marks and diacritics** (Γ©, Γ±, ΓΌ)
11//! - **Zero-width characters** (ZWJ, ZWNJ, format characters)
12//! - **ANSI escape sequences** (colors, cursor movement)
13//! - **Ambiguous width characters** (Β±, Γ—, Γ·)
14//!
15//! ## Quick Start
16//!
17//! ```rust
18//! use string_width::string_width;
19//!
20//! // ASCII text
21//! assert_eq!(string_width("Hello"), 5);
22//!
23//! // East Asian characters (full-width)
24//! assert_eq!(string_width("δ½ ε₯½"), 4);
25//!
26//! // Emoji
27//! assert_eq!(string_width("πŸ‘‹"), 2);
28//! assert_eq!(string_width("πŸ‡ΊπŸ‡Έ"), 2);  // Flag
29//! assert_eq!(string_width("1️⃣"), 2);   // Keycap sequence
30//!
31//! // Mixed content
32//! assert_eq!(string_width("Hello πŸ‘‹ δΈ–η•Œ"), 13);
33//!
34//! // ANSI escape sequences are ignored by default
35//! assert_eq!(string_width("\x1b[31mRed\x1b[0m"), 3);
36//! ```
37//!
38//! ## Advanced Configuration
39//!
40//! ```rust
41//! use string_width::{string_width, string_width_with_options, StringWidthOptions, AmbiguousWidthTreatment};
42//!
43//! // Direct configuration
44//! let options = StringWidthOptions {
45//!     count_ansi: true,  // Count ANSI escape sequences
46//!     ambiguous_width: AmbiguousWidthTreatment::Wide,  // Treat ambiguous as wide
47//! };
48//!
49//! assert_eq!(string_width_with_options("Β±Γ—Γ·", options.clone()), 6);  // Ambiguous chars as wide
50//! assert_eq!(string_width_with_options("\x1b[31mRed\x1b[0m", options), 12);  // Count ANSI
51//!
52//! // Using the builder pattern (recommended)
53//! let options = StringWidthOptions::builder()
54//!     .count_ansi(true)
55//!     .ambiguous_as_wide()
56//!     .build();
57//!
58//! assert_eq!(string_width_with_options("Β±Γ—Γ·", options), 6);
59//! ```
60//!
61//! ## Using the DisplayWidth Trait
62//!
63//! ```rust
64//! use string_width::{DisplayWidth, StringWidthOptions};
65//!
66//! let text = "Hello 🌍";
67//! println!("Width: {}", text.display_width());
68//!
69//! // With custom options
70//! let options = StringWidthOptions::default();
71//! println!("Width: {}", text.display_width_with_options(options));
72//! ```
73
74// Re-export the main functionality
75pub use crate::options::{AmbiguousWidthTreatment, StringWidthOptions, StringWidthOptionsBuilder};
76pub use crate::width_calculation::{DisplayWidth, string_width, string_width_with_options};
77
78// Internal modules
79/// Character classification utilities for width calculation
80///
81/// This module provides functions and types for classifying Unicode characters
82/// into categories needed for accurate width calculation, including combining
83/// marks, format characters, and prepend characters.
84mod character_classification;
85
86/// Emoji detection and classification
87///
88/// This module handles the complex logic of determining whether a grapheme
89/// cluster represents an emoji that should be displayed with width 2,
90/// including variation selectors, keycap sequences, and regional indicators.
91mod emoji;
92mod options;
93mod unicode_constants;
94mod width_calculation;
95
96#[cfg(test)]
97mod tests;