NAME

String::TtyLength - length or width of string excluding ANSI tty codes

SYNOPSIS

 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

DESCRIPTION

This module provides two functions which tell you the length and width of a string as it will appear on a terminal (tty), excluding any ANSI escape codes.

"tty_length" returns the length of a string excluding any ANSI tty / terminal escape codes.

"tty_width" returns the number of columns on a terminal that the string will take up, also excluding any escape codes.

For non-wide characters, the functions will return the same value. But consider the following:

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

If you're trying to align text in columns, then you'll probably want "tty_width"; if you just want to know the number of characters, using "tty_length".

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 returned by this function might not be the number of characters that would be visible on screen. But "length_of_string_excluding_escape_sequences()" was just too long.

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. If you do, please submit a bug, or email me at the address below.

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.

REPOSITORY

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

AUTHOR

Neil Bowers <neilb@cpan.org>

COPYRIGHT AND LICENSE

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