back

wcwidth.js

a javascript porting of C's wcwidth()

Stick to version 1.0.2 if need to support node.js <16.15.1.

wcwidth.js is a simple javascript porting of wcwidth() implemented in C by Markus Kuhn.

wcwidth() and its string version, wcswidth() are defined by IEEE Std 1002.1-2001, a.k.a. POSIX.1-2001, and return the number of columns used to represent a wide character and string on fixed-width output devices like terminals. Markus's implementation assumes wide characters to be encoded in ISO 10646, which is almost true for JavaScript; almost because JavaScript uses UCS-2 and has problems with surrogate pairs. wcwidth.js converts surrogate pairs to Unicode code points to handle them correctly.

Following the original implementation, this library defines the column width of an ISO 10646 character as follows:

  • the null character (U+0000) has a column width of opts.null (whose default value is 0);
  • other C0/C1 control characters and DEL will lead to a column width of opts.control (whose default value is 0);
  • non-spacing and enclosing combining characters (general category code Mn or Me) in the Unicode database) have a column width of 0;
  • SOFT HYPHEN (U+00AD) has a column width of 1;
  • other format characters (general category code Cf in the Unicode database) and ZERO WIDTH SPACE (U+200B) have a column width of 0;
  • Hangul Jamo medial vowels and final consonants (U+1160-U+11FF) have a column width of 0;
  • spacing characters in the East Asian Wide (W) or East Asian Full-width (F) category as defined in Unicode Technical Report #11 have a column width of 2; and
  • all remaining characters (including all printable ISO 8859-1 and WGL4 characters, Unicode control characters, etc.) have a column width of 1.

A surrogate high or low value which constitutes no pair is considered to have a column width of 1 according to the behavior of widespread terminals.

See the documentation from the C implementation for details.

wcwidth.js is simple to use:

import wcwidth from 'wcwidth.js';

wcwidth('한글'); // 4
wcwidth('\0'); // 0; NUL
wcwidth('\t'); // 0; control characters

Use [email protected] for CommonJS modules.

If you plan to replace NUL or control characters with, say, ??? before printing, use wcwidth.config() that returns a closure to run wcwidth with your configuration:

const mywidth = wcwidth.config({
  nul: 3,
  control: 3,
});

mywidth('\0\f'); // 6
mywidth('한\t글'); // 7

Setting these options to -1 gives a function that returns -1 for a string containing an instance of NUL or control characters:

const mywidth = wcwidth.config({
  nul: 0,
  control: -1,
});

mywidth('java\0script'); // 10
mywidth('java\tscript'); // -1

This is useful when detecting if a string has non-printable characters.

When necessary, you can add to String.prototype a wcwidth getter as follows:

Object.defineProperty(
  String.prototype,
  'wcwidth',
  {
    get() {
      return wcwidth(this.valueOf());
    },
  },
);
'한글'.wcwidth; // 4

JavaScript has no character type, thus meaningless to have two versions of wcwidth while POSIX does for C. wcwidth also accepts a code value obtained by charCodeAt():

wcwidth('한'); // prints 2
wcwidth('글'.charCodeAt(0)); // prints 2

If you have a question or suggestion, do not hesitate to contact me via email (woong.jun at gmail.com) or web.

How to install

Refer to INSTALL.md for an installation guide.

Repository

wcwidth.js had used Mercurial (which is also and commonly called hg) as its repository, and moved into git to be published on github. You can browse the repository through the web, or clone it as follows:

git clone https://github.com/mycoboco/wcwidth.js.git

If you want to contribute to the project, simply fork it and send me pull requests.

Recent commits are:

and more.

Issue tracker

wcwidth.js employed github for its issue tracker. If you'd like to file a bug or ask a question, do not hesitate to post a new issue; a self-describing title or a short text to deliver your idea would be enough. Even if issues I have posted are all written in English, nothing keeps you from posting in Korean.

Open issues are:

License

LICENSE.md describes the license imposed on users of wcwidth.js.