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:
-1for a control character0for a character that does not advance the cursor (NULL or combining)1for most characters2for 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"))). Usewcswidthfor strings or convert single characters withordfirst. Use of uninitialized value in subroutine entry-
(W uninitialized)
wcswidthwas called withundefinstead 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::CACHEcontains a defined value that cannot be used as a hash reference. Set it toundefto 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.