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

Unicode Tables

The update-tables script downloads the following resources from the Unicode Consortium website:

• http://www.unicode.org/Public/UNIDATA/EastAsianWidth.txt
• http://www.unicode.org/Public/UNIDATA/extracted/DerivedGeneralCategory.txt

With them, it generates the following files:

• wcwidth/widetab.lua
• wcwidth/zerotab.lua

The most current version of wcwidth uses the following versions of the above Unicode Standard release files:

• EastAsianWidth-13.0.0.txt, Date: 2029-01-21, 18:14:00 GMT [KW, LI], © 2020 Unicode®, Inc.
• DerivedGeneralCategory-13.0.0.txt, Date: 2019-10-21, 14:30:32 GMT, © 2019 Unicode®, Inc.