Type Function
Library utf8.*
Return value Number
Revision Release 2024.3703
Keywords utf8, UTF-8, Unicode, string, width


Calculates the width of UTF-8 string s in terms of character positions, taking into account whether characters are double-width, "compose" characters (typically accents), unprintable, or regular single-width characters.

Note that this is an approximation which may be useful, but it's limited to circumstances where a monospace width estimate is appropriate.

The return value of this function depends on usage:


utf8.width( s [, ambiIsDouble [, defaultWidth]] )
s (required)

String. The string to examine.

ambiIsDouble (optional)

Boolean. If true, the ambiguous width character's width is regarded as 2; otherwise it's regarded as 1.

defaultWidth (optional)

Number. If specified, this value will be used as the width for unprintable characters.


local utf8 = require( "plugin.utf8" )

local testStr = "♡ 你好,世界 ♡"

print( utf8.width( testStr ) )  --> 14
print( utf8.width( testStr, true ) )  --> 16
print( utf8.width( utf8.codepoint( testStr, 5, 7 ), false ) )  --> 2