String::TtyLength(3)

💖 String::TtyLength 💖

okay bestie, so this is a page from the User Contributed Perl Documentation collection, and it's about String::TtyLength — the little module that tells you how long a string ACTUALLY is once you stop letting ANSI escape codes catfish you. 🎀

---

✨ NAME ✨

String::TtyLength — length or width of string excluding ANSI tty codes. no cap, that's the whole vibe.

---

🌸 SYNOPSIS 🌸

here's the tea, literally copy-paste this:

use String::TtyLength 0.02 qw/ tty_length tty_width /;
$length = tty_length("\e[1mbold text\e[0m");
print "length = $length\n";
# 9

$width = tty_width("😄");
print "width = $width\n";
# 2

see how the escape codes just... don't count?? iconic behavior fr fr 💅

---

🦋 DESCRIPTION 🦋

so this module hands you two functions that tell you the length and the width of a string as it's gonna show up on a terminal (tty), and it excludes all the ANSI escape codes. like, the codes are there, they're doing their little color thing, but they are NOT invited to the length party. 🙈

tty_length gives you back the length of a string, excluding any ANSI tty / terminal escape codes.

tty_width gives you back the number of columns on a terminal that the string will take up, also excluding any escape codes. two different questions, two different answers, and both are valid bestie.

for non-wide characters, the two functions will return the same value. they're matching. they're synchronized. but consider this:

my $emoji  = "😄";
my $length = tty_length($emoji);   # 1
my $width  = tty_width($emoji);    # 2

😭 the emoji is ONE character but takes up TWO columns. the betrayal. the audacity.

so like — if you're trying to align text in columns, you probably want tty_width. if you just want to know the number of characters, use tty_length. choose your fighter. ⭐

💜 tty_length( STRING ) 💜

takes a single string, and returns the length of the string, excluding any escape sequences.

note: the escape sequences could include cursor movement, so the length this function returns might not be the number of characters that would actually be visible on screen. but length_of_string_excluding_escape_sequences() was just too long. 💀 imagine typing that every time. no thanks.

💜 tty_width( STRING ) 💜

takes a single string and returns the number of columns that the string will take up on a terminal.

you may find that sometimes tty_width() returns the wrong number. and if you do — please submit a bug, or email me at the address below. i wanna know, bestie, i'm not gonna be weird about it. 🫶

this was added in version 0.02 of String::TtyLength, so you should require at least that version of this module, as per the SYNOPSIS. don't skip the version number, it's giving necessary. ✨

---

🌈 SEE ALSO 🌈

colorstrip() in Term::ANSIColor will remove ANSI color escape sequences from a string, but not all ANSI escape sequences. so like... it's close but it's not the full picture. read the fine print bestie.

---

🧚 REPOSITORY 🧚

<https://github.com/neilb/String-TtyLength>

go star it. go file issues. go be part of the community. 👑

---

🎀 AUTHOR 🎀

Neil Bowers <neilb@cpan.org>

---

👑 COPYRIGHT AND LICENSE 👑

this software is copyright (c) 2020 by Neil Bowers.

this is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. free software slay. 💚

---

and that's the whole page!! this was perl v5.42.0, dated 2025-07-25, and it's the String::TtyLength(3) manual page — mwah, bye bestie!! 💖✨🌸🦋💅