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
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
//! Terminal display width that gets emoji, CJK and ANSI colour right.
//!
//! `"π¨βπ©βπ§βπ¦".len()` is 25. `"π¨βπ©βπ§βπ¦".chars().count()` is 7. A terminal draws it in **2**
//! columns. Every CLI table, progress bar, box border and status line needs
//! that third number, and getting it wrong is why so much terminal output is
//! subtly ragged.
//!
//! ```
//! use cellwidth::{width, cell, truncate};
//!
//! assert_eq!(width("cafΓ©"), 4); // combining accents don't count
//! assert_eq!(width("ζ₯ζ¬θͺ"), 6); // CJK is double-width
//! assert_eq!(width("π¨βπ©βπ§βπ¦"), 2); // one glyph, not seven
//! assert_eq!(width("\x1b[31mred\x1b[0m"), 3); // colour codes are free
//!
//! // Cuts land on cluster boundaries, never mid-character.
//! assert_eq!(truncate("ζ₯ζ¬θͺγγγΉγ", 7), "ζ₯ζ¬θͺ");
//!
//! // And this is always exactly 10 columns wide, whatever you feed it.
//! assert_eq!(width(&cell("π―π΅ TΕkyΕ ζ±δΊ¬", 10)), 10);
//! ```
//!
//! # What makes this correct
//!
//! * Widths come from the East Asian Width property of the Unicode Character
//! Database, version [`UNICODE_VERSION`], generated into plain sorted tables.
//! * Text is segmented into extended grapheme clusters per UAX #29 -- including
//! emoji ZWJ sequences, regional indicator flags, skin tone modifiers and
//! Indic conjuncts -- so a "character" means what a user thinks it means.
//! * Variation selectors are honoured: `β€` is 1 column, `β€οΈ` is 2.
//! * ANSI escape sequences are parsed properly (CSI, OSC, DCS and the 8-bit C1
//! forms), counted as zero columns, and never cut in half.
//!
//! # Choosing a policy
//!
//! The free functions use [`Width::DEFAULT`]. Where the answer genuinely
//! depends on the terminal -- East Asian Ambiguous characters, tab stops, how
//! old the emoji font is -- build a [`Width`] instead:
//!
//! ```
//! use cellwidth::{Ambiguous, Width};
//!
//! const CJK: Width = Width::DEFAULT.ambiguous(Ambiguous::Wide).tab_stop(4);
//! assert_eq!(CJK.of("Β°C"), 3);
//! ```
//!
//! # No dependencies
//!
//! None, and no build script: the Unicode tables are generated ahead of time by
//! `tools/gen_tables.py` and committed. `no_std` is supported by disabling the
//! `std` feature; measurement works with no allocator at all, and the
//! `alloc` feature adds the functions that return owned strings.
extern crate alloc;
pub
pub
pub use cratestrip_ansi;
pub use crate;
pub use crateELLIPSIS;
pub use crateGraphemes;
pub use crate;
pub use crate;
pub use crate;
pub use crateUNICODE_VERSION;
use ;
/// Columns a string occupies in a terminal, using [`Width::DEFAULT`].
///
/// ```
/// # use cellwidth::width;
/// assert_eq!(width("hello"), 5);
/// assert_eq!(width("ππ½"), 2);
/// ```
/// Columns a single `char` occupies, using [`Width::DEFAULT`].
///
/// Remember that a `char` is not a user-perceived character; prefer [`width`]
/// for real text.
/// Iterate the extended grapheme clusters of a string (UAX #29).
///
/// ```
/// # use cellwidth::graphemes;
/// let g: Vec<&str> = graphemes("aππ½π―π΅").collect();
/// assert_eq!(g, ["a", "ππ½", "π―π΅"]);
/// ```
/// Iterate the places a line may be broken (UAX #14).
///
/// Yields byte offsets, so `&s[..offset]` is a complete line. The final offset
/// is always `s.len()`.
///
/// ```
/// # use cellwidth::{line_breaks, Break};
/// let b: Vec<_> = line_breaks("a b").collect();
/// assert_eq!(b, [(2, Break::Allowed), (3, Break::Mandatory)]);
/// ```
/// Split a string into printable text runs and escape sequences.
///
/// ```
/// # use cellwidth::{pieces, Piece};
/// let p: Vec<Piece> = pieces("\x1b[1mbold\x1b[0m").collect();
/// assert_eq!(p[1], Piece::Text("bold"));
/// ```
/// Longest prefix of `s` fitting in `max` columns, using [`Width::DEFAULT`].
///
/// Never allocates and never cuts inside a character or an escape sequence.
/// Fit `s` into exactly `width` columns, truncating with `β¦` or padding with
/// spaces. The table-cell workhorse.
///
/// ```
/// # use cellwidth::{cell, width};
/// assert_eq!(cell("hi", 5), "hi ");
/// assert_eq!(cell("ζ₯ζ¬θͺγγγΉγ", 8), "ζ₯ζ¬θͺβ¦ ");
/// assert_eq!(width(&cell("π¨βπ©βπ§βπ¦ crew", 6)), 6);
/// ```
/// Pad `s` with spaces on the right to at least `width` columns.
/// Pad `s` with spaces on the left to at least `width` columns.
/// Break `s` into lines of at most `width` columns, breaking at whitespace.