EXPORTS

Nothing per default, but can export the following per request:

:all
  wcwidth
  wcswidth

NAME

Terminal::WCWidth - determine columns needed for a wide character

DESCRIPTION

This module is mainly for console/tty programs that carefully produce output for Terminals, or make pretend to be an emulator.

SYNOPSIS

sub print_right_aligned {
  my ($s) = @_;
  print " " x (80 - wcswidth($s));
  say $s;
}
print_right_aligned("this is right-aligned");
print_right_aligned("another right-aligned string");

VARIABLES

$CACHE

By default, wcwidth is stateless and performs a binary search on every lookup to avoid unbounded memory growth (e.g., when iterating over the entire Unicode range).

To enable caching for repeated lookups, assign a hash reference to $Terminal::WCWidth::CACHE:

local $Terminal::WCWidth::CACHE = {};
my $width = wcswidth($long_text);

Using local restores the previous cache value when the enclosing scope exits, allowing the temporary cache to be reclaimed automatically. You may also bind a tied hash (such as Tie::Cache::LRU) to enforce a fixed memory limit.

SUBROUTINES

wcwidth

Takes a single codepoint and outputs its width:

wcwidth(0x3042) # "あ" - returns 2

Returns:

-1 for a control character
0 for a character that does not advance the cursor (NULL or combining)
1 for most characters
2 for full width characters

wcswidth

Takes a string and outputs its total width:

wcswidth("*ウルヰ*") # returns 8 = 2 + 6

Returns -1 if any control characters are found.

Note that the string must be a decoded character string (with Perl's internal UTF-8 flag enabled, e.g., via use utf8 or Encode::decode). Passing raw UTF-8 octets will produce incorrect results.

Unlike the original version, this module does not support getting the width of only the first n characters of a string, as you can use the substr method.

DIAGNOSTICS

Argument "%s" isn't numeric in numeric lt (<)

(W numeric) You probably passed a character string (like wcwidth("a")) instead of an integer codepoint (wcwidth(ord("a"))). Use wcswidth for strings or convert single characters with ord first.

Use of uninitialized value in subroutine entry

(W uninitialized) wcswidth was called with undef instead of a decoded character string. Pass a defined Unicode string with Perl's internal UTF-8 flag enabled.

Not a HASH reference

(F) $Terminal::WCWidth::CACHE contains a defined value that cannot be used as a hash reference. Set it to undef to disable caching, or assign a hash reference to enable caching.

COPYRIGHT AND LICENCE

This code was originally derived from C code with the name wcwidth.c.

Copyright (c) 2007 by Markus Kuhn

This library content was taken from the Terminal::WCWidth implementation of 
Raku (a Python port) which is licensed under MIT license.

Copyright (c) 2014 Jeff Quast
              2015-2017 +merlan #flirora
              2020,2024 Raku Community
              2024-2026 J. Schneider

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

AUTHORS

  • Markus Kuhn

  • Jeff Quast

  • +merlan #flirora

  • José Joaquín Atria

  • Raku Community

  • J. Schneider

DISCLAIMER OF WARRANTIES

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.

REQUIRES

5.010

SEE ALSO

Text::CharWidth

Text::VisualWidth::PP

wcwidth.c

Terminal::WCWidth