Implementation:ClickHouse ClickHouse Widechar Width

Knowledge Sources	ClickHouse
Domains	Unicode, Text_Processing
Last Updated	2026-02-08 00:00 GMT

Overview

A Unicode character width calculation library that determines the display width of Unicode characters for terminal and text rendering applications.

Description

This implementation provides functionality to determine the visual width of Unicode characters according to Unicode East Asian Width and emoji properties. It categorizes characters into different width classes: single-width (1), double-width (2), combining (0), non-printable, ambiguous, private use, and unassigned. The library includes comprehensive Unicode character tables for different categories including CJK characters, emojis, combining marks, and control characters.

The code is auto-generated from official Unicode data files (`UnicodeData.txt`, `EastAsianWidth.txt`, `emoji-data.txt`) ensuring accuracy and consistency with Unicode standards.

Usage

Use this implementation when you need to:

• Calculate the display width of Unicode text for terminal rendering
• Determine column alignment for text containing CJK characters and emojis
• Handle combining characters and zero-width characters correctly
• Support East Asian Width properties for proper text layout

Code Reference

Source Location

• Repository: ClickHouse
• File: base/widechar_width/widechar_width.h
• Lines: 1-525

Signature

// Special width values
enum {
    widechar_nonprint = -1,
    widechar_combining = -2,
    widechar_ambiguous = -3,
    widechar_private_use = -4,
    widechar_unassigned = -5,
    widechar_widened_in_9 = -6
};

// Character range structure
struct widechar_range {
    int32_t lo;
    int32_t hi;
};

// Main width calculation function
inline int widechar_wcwidth(wchar_t c);

// Helper function
template <typename Collection>
bool widechar_in_table(const Collection &arr, int32_t c);

Import

#include <base/widechar_width/widechar_width.h>

I/O Contract

Input	Type	Description
c	wchar_t	Unicode character code point

Output	Type	Description
width	int	Character width: 0 (combining), 1 (single-width), 2 (double-width), or negative values for special cases

Usage Examples

#include <base/widechar_width/widechar_width.h>

// Calculate width of ASCII character
int width_a = widechar_wcwidth(L'A');  // Returns 1

// Calculate width of CJK character
int width_cjk = widechar_wcwidth(L'中');  // Returns 2

// Calculate width of combining character
int width_combining = widechar_wcwidth(0x0301);  // Returns widechar_combining (-2)

// Calculate width of emoji
int width_emoji = widechar_wcwidth(0x1F600);  // Returns 2

// Check for non-printable
int width_control = widechar_wcwidth(0x0001);  // Returns widechar_nonprint (-1)

Related Pages

• Principle:ClickHouse_ClickHouse_Unicode_Character_Width