lua-wcwidth
When writing output to a fixed-width output system (such as a terminal), the
displayed length of a string does not always match the number of characters
(also known as runes, or
code points) contained by the string. Some characters occupy two spaces
(full-wide characters), and others occupy none.
POSIX.1-2001 and POSIX.1-2008 specify the
wcwidth(3) function
which can be used to know how many spaces (or cells) must be used to display
a Unicode code point. This Lua contains a portable and
standalone implementation based on the Unicode Standard release files.
This module is useful mainly for implementing programs which must produce
output to terminals, while handling proper alignment for double-width and
zero-width Unicode code points.
Usage
The following snippet defines a function which can determine the display width
for a string:
local wcwidth, utf8 = require "wcwidth", require "utf8"
local function display_width(s)
local len = 0
for _, rune in utf8.codes(s) do
local l = wcwidth(rune)
if l >= 0 then
len = len + l
end
end
return len
end
The function above can be used to print any UTF-8 string properly
right-aligned to a terminal:
local function alignright(s, cols)
local numspaces = cols - display_width(s)
local spaces = ""
while numspaces > 0 do
numspaces = numspaces - 1
spaces = spaces .. " "
end
return spaces .. s
end
print(alignright("コンニチハ", 80))
The wcwidth() function takes a Unicode code point as argument, and returns
one of the following values:
-1: Width cannot be determined (the code point is not printable).
0: The code point does not advance the cursor (e.g. NULL, or a combining
character).
2: The character is East Asian wide (W) or East Asian full-width (F),
and is displayed using two spaces.
1: All the rest of characters, which take a single space.
Note that the
wcswidth(3) companion
function is deliberately not provided by this module: while Lua 5.3 provides
utf8.codes() and
utf8.codepoint()
to convert UTF8 byte sequences to code points, for other Lua versions it would
be needed to depend on a third party module, and that would be against the
goal of wcwidth being standalone. If needed be, wcswidth() can be
implemented as follows using the Lua 5.3 utf8 module (or any other
implementation which provides a compatible implementation):
-- Calculates the printable length of first "n" characters of string "s"
-- on a terminal. Returns the number of cells or -1 if the string contains
-- non-printable characters. Raises an error on invalid UTF8 input.
function wcswidth(s, n)
local cells = 0
if n then
local count = 0
for _, rune in utf8.codes(s) do
local w = wcwidth(rune)
if w < 0 then return -1 end
count = count + 1
if count >= n then break end
end
else
for _, rune in utf8.codes(s) do
local w = wcwidth(rune)
if w < 0 then return -1 end
cells = cells + w
end
end
return cells
end
Installation
LuaRocks is recommended for installation.
The stable version (recommended) can be installed with:
luarocks install wcwidth
The development version can be installed with:
luarocks install --server=https://luarocks.org/dev wcwidth
Strict No LLM / No AI Policy
No LLMs for issues.
No LLMs for pull requests.
No LLMs for comments on the bug tracker, including translation. English
is encouraged, but not required. You are welcome to post in your native
language and rely on others to have their own translation tools of choice
to interpret your words.
Unicode Tables
The update-tables script downloads the following resources from the Unicode
Consortium website:
With them, it generates the following files:
The most current version of wcwidth uses the following versions of the above
Unicode Standard release files:
EastAsianWidth-17.0.0.txt, Date: 2025-07-24, 00:12:54 GMT, © 2025 Unicode®, Inc.
DerivedGeneralCategory-17.0.0.txt, Date: 2025-07-24, 00:12:50 GMT, © 2025 Unicode®, Inc.