Module org.jline.terminal

Package org.jline.utils

Class WCWidth

java.lang.Object

org.jline.utils.WCWidth

public final class WCWidth
extends Object

Utility class for determining the display width of Unicode characters.

The WCWidth class provides methods for calculating the display width of Unicode characters in terminal environments. This is important for proper text alignment and cursor positioning, especially when dealing with wide characters (such as East Asian characters) and zero-width characters (such as combining marks).

This implementation is based on Markus Kuhn's wcwidth implementation, which follows the Unicode Standard guidelines for character width. It categorizes characters as:

• Zero width (0) - Control characters, combining marks, format characters
• Single width (1) - Most Latin, Greek, Cyrillic, and other scripts
• Double width (2) - East Asian scripts (Chinese, Japanese, Korean)
• Ambiguous width (-1) - Characters with context-dependent width

Tables are generated from Unicode 16.0 data files:

• combining table from UnicodeData.txt (categories Mn, Me, Cf, plus Hangul Jamo U+1160-11FF and U+200B)
• East Asian Width from EastAsianWidth.txt
• Emoji presentation from emoji-data.txt

This class is used throughout JLine for calculating string display widths, which is essential for proper terminal display formatting, cursor positioning, and text alignment.

Method Summary

Modifier and Type	Method	Description
static int	charCountForDisplay(CharSequence cs, int index, Terminal terminal)	Compute the number of Java chars that form the display unit (code point or grapheme cluster) starting at index in cs.
static int	charCountForGraphemeCluster(CharSequence cs, int index)	Returns the number of chars consumed by the grapheme cluster starting at index in the given CharSequence.
static boolean	isRegionalIndicator(int cp)	Determines whether a Unicode code point is a Regional Indicator Symbol (U+1F1E6..U+1F1FF).
static int	wcwidth(int ucs)
static int	wcwidthForDisplay(CharSequence cs, int index, Terminal terminal)	Compute the display width in terminal columns of the character or grapheme cluster that begins at the given index in the character sequence.
static int	wcwidthForGraphemeCluster(CharSequence cs, int index)	Returns the display width of the grapheme cluster starting at index.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

wcwidth

public static int wcwidth(int ucs)

charCountForGraphemeCluster

public static int charCountForGraphemeCluster(CharSequence cs,
 int index)

Returns the number of chars consumed by the grapheme cluster starting at index in the given CharSequence.

A grapheme cluster is a user-perceived character that may be composed of multiple Unicode code points. This method recognizes:

• ZWJ sequences (e.g., family emoji ???????)
• Regional indicator pairs (flags, e.g., ??)
• Emoji modifier sequences (skin tones, e.g., ??)
• Variation selector sequences (U+FE0E, U+FE0F)
• Combining mark sequences

Parameters:

cs - the character sequence

index - the starting char index

Returns:

the number of chars consumed by the grapheme cluster

wcwidthForGraphemeCluster

public static int wcwidthForGraphemeCluster(CharSequence cs,
 int index)

Returns the display width of the grapheme cluster starting at index.

Variation selectors override the base code point's width: VS16 (U+FE0F) upgrades the cluster to emoji presentation (width 2), while VS15 (U+FE0E) downgrades it to text presentation (width 1). When neither is present, the width of the base code point (via wcwidth(int)) is used.

Parameters:

cs - the character sequence

index - the starting char index

Returns:

the display width of the grapheme cluster, same range as wcwidth(int)

wcwidthForDisplay

public static int wcwidthForDisplay(CharSequence cs,
 int index,
 Terminal terminal)

Compute the display width in terminal columns of the character or grapheme cluster that begins at the given index in the character sequence.

If the terminal has grapheme-cluster mode enabled, or if terminal is null and the runtime provides JDK-level grapheme-cluster support (JDK 21+), the measurement is grapheme-cluster-aware so emoji variation selectors and ZWJ sequences are handled as a single display unit. Otherwise the width of the single code point at index is returned.

Parameters:

cs - the character sequence containing the cluster

index - the starting char index of the character or cluster

terminal - the terminal to query for grapheme-cluster mode, or null

Returns:

the display width in terminal columns for the character or cluster

charCountForDisplay

public static int charCountForDisplay(CharSequence cs,
 int index,
 Terminal terminal)

Compute the number of Java chars that form the display unit (code point or grapheme cluster) starting at index in cs.

If the terminal indicates grapheme cluster mode, or when terminal is null and JDK grapheme-cluster support is available (JDK 21+), this uses grapheme-cluster segmentation so ZWJ sequences, flag pairs, skin-tone modifiers, and similar multi-code-point units are treated as a single unit and may span multiple chars. Otherwise it returns the char count for the code point at index.

Parameters:

cs - the character sequence

index - the starting char index

terminal - the terminal to consult for grapheme cluster mode, or null

Returns:

the number of char units to advance past the display unit beginning at index

isRegionalIndicator

public static boolean isRegionalIndicator(int cp)

Determines whether a Unicode code point is a Regional Indicator Symbol (U+1F1E6..U+1F1FF).

Parameters:

cp - the Unicode code point to test

Returns:

`true` if the code point is within U+1F1E6..U+1F1FF, `false` otherwise