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 ofopts.null
(whose default value is 0); - other
C0/C1 control characters
and
DEL
will lead to a column width ofopts.control
(whose default value is 0); - non-spacing and enclosing combining characters
(general category code
Mn
orMe
) 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) andZERO 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:
const wcwidth = require('wcwidth.js');
wcwidth('한글'); // 4
wcwidth('\0'); // 0; NUL
wcwidth('\t'); // 0; control characters
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.
Due to the risk of monkey-patching, no String
getter is provided anymore.
Even if discouraged, you can still monkey-patch by yourself as follows:
String.prototype.__defineGetter__(
'wcwidth',
function () { 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
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:
- doc(README): fix a bug in code again
- doc(README): fix a bug in example code
- feat(package): prepare to release v1.1.2
- refactor(all): rewrite for recent node versions
- Merge pull request #15 from mycoboco/dependabot/npm_and_yarn/minimist-1.2.6
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:
- Bump word-wrap from 1.2.3 to 1.2.4
- how can i get the wcwidth.js file not install with npm
- What about ambiguous-width characters
- add option to install a getter for String
License
LICENSE.md
describes the license imposed on users of wcwidth.js
.